# Começando

Esta página leva você do zero ao primeiro hotsite publicado. Leva uns cinco
minutos. Se preferir que o seu agente faça tudo, pule para
[Conectando seu agente](agentes.md), mas instale a CLI mesmo assim: é ela que
o agente usa.

## 1. Peça um convite

O acesso é por convite. Mande o seu **usuário do GitHub** para o
administrador, que roda `rapadura admin invite <seu-usuario>` (veja
[Administração](admin.md)). Sem convite, o `rapadura login` responde
`not_invited`.

## 2. Instale a CLI

**macOS e Linux**

```sh
curl -fsSL https://agents.rapadura.net/install.sh | sh
```

O instalador coloca o binário em `~/.local/bin/rapadura` e avisa se essa
pasta ainda não está no seu `PATH`. Para confirmar:

```sh
rapadura --version
```

**Windows (PowerShell)**

```powershell
New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\rapadura" | Out-Null
Invoke-WebRequest https://agents.rapadura.net/dl/rapadura_windows_amd64.exe -OutFile "$env:LOCALAPPDATA\rapadura\rapadura.exe"
```

Depois adicione `%LOCALAPPDATA%\rapadura` ao PATH, ou chame o executável pelo
caminho completo.

**Download manual.** Todos os binários e as somas SHA-256 estão em
<https://agents.rapadura.net/dl/>.

## 3. Entre com o GitHub

```sh
rapadura login
```

A CLI mostra um código e o endereço `https://github.com/login/device`. Abra o
endereço, digite o código, autorize o aplicativo **rapadura**. A CLI percebe
sozinha e grava um token em `~/.config/rapadura/credentials.json` no macOS e
no Linux, ou em `%AppData%\rapadura\credentials.json` no Windows (só o seu
usuário consegue ler). Cada máquina tem o seu próprio token; ele vale 90 dias
e pode ser revogado a qualquer momento com `rapadura logout`.

Confira quem você é para o sistema:

```sh
rapadura whoami
```

## 4. Publique

Tenha uma pasta com os arquivos públicos do site e um `index.html` na raiz.
Pode ser HTML escrito à mão ou a saída de um gerador (Astro, Hugo, Vite,
Jekyll, Stattic, o que for). Publique **a pasta de saída**, nunca a raiz do
repositório.

```sh
rapadura publish ./dist --site meetup-sobral --create --title "Meetup Sobral 2026"
```

- `--site` é o nome do hotsite. Só o nome curto (`meetup-sobral`) vira
  `meetup-sobral.rapadura.net`. Para a outra zona, use o nome completo
  (`meetup-sobral.phpcomrapadura.org`) ou `--zone phpcomrapadura.org`.
- `--create` cria o site se ele ainda não existir.
- `--title` é só um rótulo amigável que aparece nos recibos.

A resposta é um **recibo**: o endereço, o número da versão, quantos arquivos
subiram e os próximos passos. A primeira visita em HTTPS pode levar alguns
segundos enquanto o certificado é emitido.

## 5. Atualize, volte, inspecione

```sh
rapadura publish ./dist --site meetup-sobral -m "ajuste no rodapé"   # nova versão
rapadura versions meetup-sobral                                      # histórico
rapadura rollback meetup-sobral 3                                    # volta para a versão 3
rapadura sites list                                                  # seus sites
rapadura sites show meetup-sobral                                    # detalhes de um
rapadura logs meetup-sobral -n 50                                    # últimos acessos
```

Para tirar um site do ar:

```sh
rapadura sites delete meetup-sobral --yes
```

Os arquivos ficam guardados por um tempo e o administrador consegue restaurar.

## 6. Em outra máquina, ou em CI

Rode `rapadura login` de novo na nova máquina. Cada uma recebe um token
próprio. Em CI ou em um agente que não pode abrir o navegador, exporte
`RAPADURA_TOKEN` com um token válido em vez de usar o arquivo de credenciais.
Nunca coloque o token em repositório, chat ou log.