CLI Commands

`swarm`

Run without arguments to launch the interactive menu.

swarm

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

Authenticate with your Swarm account via browser.

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.

swarm logout

`swarm setup-tunnel`

Retry or revoke your persistent localhost tunnel.

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.

`swarm test`

Run an AI-powered UX test against a URL.

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”.

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

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.

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 browser extension — Export → JSON.

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.

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:

swarm test --url localhost:3000 --goal "Sign up for an account"

With a saved swarm:

swarm test --url https://myapp.com --goal "Complete checkout" --swarm abc123

Split frontend/backend:

swarm test --url localhost:3000 --backend localhost:8080 --goal "Create a project"

Authenticated test (login mode):

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):

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):

swarm test --url localhost:3000 --goal "Explore settings" \
  --cookies ./cookies.json \
  --start-url http://localhost:3000/dashboard

Non-interactive (CI/CD):

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.

swarm list-swarms

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

Getting Started

MCP

CLI

Concepts

Commands

CLI Commands

`swarm`

`swarm logout`

`swarm setup-tunnel`

`swarm test`

Target & goal

Personas

Tunneling

Backend proxy

Authentication

Shared

Advanced

Examples

`swarm list-swarms`

​CLI Commands

​swarm

​swarm login

​swarm logout

​swarm setup-tunnel

​swarm test

​Target & goal

​Personas

​Tunneling

​Backend proxy

​Authentication

​Login mode

​Sign-up mode

​Cookie injection mode

​Shared

​Advanced

​Examples

​swarm list-swarms

CLI Commands

`swarm`

`swarm login`

`swarm logout`

`swarm setup-tunnel`

`swarm test`

Target & goal

Personas

Tunneling

Backend proxy

Authentication

Login mode

Sign-up mode

Cookie injection mode

Shared

Advanced

Examples

`swarm list-swarms`