> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useswarm.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Commands

> Complete reference for all Swarm CLI commands and options.

# CLI Commands

## `swarm`

Run without arguments to launch the interactive menu.

```bash theme={null}
swarm
```

The menu adapts based on your login state — offering login if unauthenticated, or test/swarm options if logged in.

***

## `swarm login`

Authenticate with your Swarm account via browser.

```bash theme={null}
swarm login [options]
```

| Option            | Description          |
| ----------------- | -------------------- |
| `--api-url <url>` | Override the API URL |

The CLI initiates a device authorization flow — a code is displayed in your terminal and a browser window opens for confirmation.

***

## `swarm logout`

Remove stored credentials.

```bash theme={null}
swarm logout
```

***

## `swarm setup-tunnel`

Retry or revoke your persistent localhost tunnel.

```bash theme={null}
swarm setup-tunnel [options]
```

| Option     | Description                                                              |
| ---------- | ------------------------------------------------------------------------ |
| `--revoke` | Revoke the current persistent tunnel and remove local tunnel credentials |

Persistent tunnels are normally provisioned automatically during `swarm login`. Use this command when provisioning failed during login, when you need to rotate the tunnel token, or when a stale tunnel should be cleared.

Learn more in [Persistent Tunnels](/guides/persistent-tunnels).

***

## `swarm test`

Run an AI-powered UX test against a URL.

```bash theme={null}
swarm test [options]
```

### Target & goal

| Option                 | Description                                               |
| ---------------------- | --------------------------------------------------------- |
| `--url <url>`          | Target URL (e.g. `localhost:3000` or `https://myapp.com`) |
| `--goal <goal>`        | What the AI personas should try to accomplish             |
| `--description <desc>` | Describe your target audience                             |

### Personas

| Option              | Description                                    |
| ------------------- | ---------------------------------------------- |
| `--swarm <id>`      | Use personas from a saved swarm                |
| `--agents <count>`  | Number of AI personas to generate (default: 3) |
| `--audience <desc>` | Audience description for persona generation    |

### Tunneling

| Option                         | Description                                                         |
| ------------------------------ | ------------------------------------------------------------------- |
| `--no-tunnel`                  | Skip tunnel setup (URL must be publicly accessible)                 |
| `--tunnel-provider <provider>` | Tunnel provider: `cloudflare`, `ngrok`, or `auto` (default: `auto`) |

### Backend proxy

| Option                    | Description                                                    |
| ------------------------- | -------------------------------------------------------------- |
| `--backend <url>`         | Local backend URL to proxy (e.g. `localhost:8080`)             |
| `--backend-paths <paths>` | Additional path prefixes for backend routing (comma-separated) |

When `--backend` is provided, Swarm starts a reverse proxy that routes API paths (`/api/*`, `/auth/*`, `/graphql`, `/trpc/*`) to your backend and everything else to your frontend — all through a single tunnel.

### Authentication

Three modes:

* **Login** — agents perform a username/password login against an existing account.
* **Sign-up** — no account exists yet; you supply one base email and each persona registers with a unique sub-aliased address (`local+<hash>@domain`) so all confirmations land in your one inbox.
* **Cookies** — inject session cookies and skip the login flow entirely.

All three accept `--start-url` to land the agent on a specific page after auth (or to pre-navigate to the sign-up form).

When you run `swarm test` interactively without any auth flags, the prompt offers all three. The CLI auto-suggests **Sign-up** when your goal text mentions "sign up", "register", "create account", or "onboard".

#### Login mode

| Option                  | Description                                                |
| ----------------------- | ---------------------------------------------------------- |
| `--login-url <url>`     | Login page URL for authenticated testing                   |
| `--username <username>` | Username or email                                          |
| `--password <password>` | Password (prefer interactive prompt or `--password-stdin`) |
| `--password-stdin`      | Read password from stdin for scripting                     |

#### Sign-up mode

| Option                         | Description                                                                                                                            |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `--signup-email <email>`       | Base email — each persona signs up with a unique `local+<hash>@domain` alias derived from this address                                 |
| `--signup-password <password>` | Optional shared password for the sign-up forms. If omitted, the runtime mints a strong random password per persona-run (not persisted) |

How the alias works:

* You supply `you@yourdomain.com`.
* For each persona-run, the runtime generates `you+<base36(timestamp)+random>@yourdomain.com` — a never-before-seen, never-replicates-in-the-future address.
* The agent is told to type that exact alias verbatim into the sign-up form. The login pre-fill flow and the `perform_login` tool are suppressed for sign-up runs (the agent fills the form itself).
* The generated alias is persisted to the run record so you can correlate inbox emails back to a persona later.

Use any provider that supports plus-addressing — Gmail, Fastmail, custom domains all work. Passwords are never persisted regardless of mode.

#### Cookie injection mode

| Option             | Description                                                                                          |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| `--cookies <file>` | Path to a JSON file with session cookies (skips the login flow — agent starts already authenticated) |
| `--cookies-stdin`  | Read cookies JSON from stdin for scripting                                                           |

The cookies file must be a JSON array. Required fields per cookie: `name`, `value`, `domain`. Optional: `path`, `secure`, `httpOnly`, `sameSite` (also accepts `null`). The easiest way to capture cookies is the [Cookie-Editor](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm) browser extension — Export → JSON.

<Note>
  When the test runs against a tunneled localhost URL, cookie domains captured from a different host are automatically rewritten to match the test URL. Cookie names, values, and other attributes are preserved unchanged.
</Note>

#### Shared

| Option              | Description                                                                                                                                                                                           |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--start-url <url>` | URL the agent lands on after auth — recommended with `--cookies` (the post-auth dashboard URL). For login mode, overrides the default post-login redirect. For sign-up, can pre-navigate to the form. |

### Advanced

| Option                  | Description                           |
| ----------------------- | ------------------------------------- |
| `--max-steps <n>`       | Maximum steps per agent (default: 30) |
| `--provider <provider>` | AI provider: `openai` or `anthropic`  |
| `--model <model>`       | Model name override                   |
| `-y, --yes`             | Skip confirmation prompts             |

### Examples

Basic test:

```bash theme={null}
swarm test --url localhost:3000 --goal "Sign up for an account"
```

With a saved swarm:

```bash theme={null}
swarm test --url https://myapp.com --goal "Complete checkout" --swarm abc123
```

Split frontend/backend:

```bash theme={null}
swarm test --url localhost:3000 --backend localhost:8080 --goal "Create a project"
```

Authenticated test (login mode):

```bash theme={null}
swarm test --url localhost:3000 --goal "Edit profile settings" \
  --login-url localhost:3000/login \
  --username test@example.com
```

Sign-up flow with sub-aliased emails (one base email, N unique inboxes):

```bash theme={null}
swarm test --url localhost:3000 --goal "Sign up for an account" \
  --signup-email you@yourdomain.com \
  --agents 5
# Each persona signs up as: you+lwk3a8x7@yourdomain.com,
# you+lwk3a902@yourdomain.com, you+lwk3a9f1@yourdomain.com, ...
# All confirmation emails arrive in your one inbox at you@yourdomain.com.
```

Cookie injection (skip login, go straight to the dashboard):

```bash theme={null}
swarm test --url localhost:3000 --goal "Explore settings" \
  --cookies ./cookies.json \
  --start-url http://localhost:3000/dashboard
```

Non-interactive (CI/CD):

```bash theme={null}
swarm test --url https://staging.myapp.com \
  --goal "Complete onboarding" \
  --agents 5 \
  --description "new SaaS users" \
  --yes
```

***

## `swarm list-swarms`

List your saved persona swarms.

```bash theme={null}
swarm list-swarms
```

Displays swarm IDs, names, and persona counts. Use the ID with `swarm test --swarm <id>`.