# Getting started

This page takes you from nothing to a published hotsite in about five
minutes. If you would rather have your agent do everything, skip to
[Connecting your agent](agents-setup.md), but install the CLI anyway: it is
what the agent uses.

## 1. Ask for an invite

Access is by invitation. Send your **GitHub username** to the administrator,
who runs `rapadura admin invite <your-username>` (see
[Administration](admin.md)). Without an invite, `rapadura login` answers
`not_invited`.

## 2. Install the CLI

**macOS and Linux**

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

The installer puts the binary in `~/.local/bin/rapadura` and tells you if that
directory is not on your `PATH` yet. To confirm:

```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"
```

Then add `%LOCALAPPDATA%\rapadura` to your PATH, or call the executable by
its full path.

**Manual download.** All binaries and SHA-256 sums are at
<https://agents.rapadura.net/dl/>.

## 3. Sign in with GitHub

```sh
rapadura login
```

The CLI shows a code and the address `https://github.com/login/device`. Open
it, enter the code, authorize the **rapadura** app. The CLI notices by itself
and stores a token in `~/.config/rapadura/credentials.json` on macOS and
Linux, or `%AppData%\rapadura\credentials.json` on Windows (readable only by
your user). Every machine gets its own token; it lasts 90 days and can be
revoked at any time with `rapadura logout`.

Check who you are to the system:

```sh
rapadura whoami
```

## 4. Publish

Have a directory with the site's public files and an `index.html` at its
root. Hand-written HTML or the output of any generator (Astro, Hugo, Vite,
Jekyll, Stattic) both work. Publish **the output directory**, never the
repository root.

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

- `--site` names the hotsite. A bare name (`meetup-sobral`) becomes
  `meetup-sobral.rapadura.net`. For the other zone use the full name
  (`meetup-sobral.phpcomrapadura.org`) or `--zone phpcomrapadura.org`.
- `--create` creates the site if it does not exist yet.
- `--title` is only a friendly label shown in receipts.

The answer is a **receipt**: the address, the version number, how many files
went up, and next steps. The first HTTPS visit may take a few seconds while
the certificate is issued.

## 5. Update, roll back, inspect

```sh
rapadura publish ./dist --site meetup-sobral -m "footer fix"   # new version
rapadura versions meetup-sobral                                # history
rapadura rollback meetup-sobral 3                              # back to version 3
rapadura sites list                                            # your sites
rapadura sites show meetup-sobral                              # one site in detail
rapadura logs meetup-sobral -n 50                              # recent requests
```

To take a site offline:

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

The files are kept for a while and the administrator can restore them.

## 6. On another machine, or in CI

Run `rapadura login` again on the new machine. Each one gets its own token.
In CI, or for an agent that cannot open a browser, export `RAPADURA_TOKEN`
with a valid token instead of using the credentials file. Never commit a
token, paste it into chat, or write it to a log.