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.
CLI Commands
swarm
Run without arguments to launch the interactive menu.
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.
| Option | Description |
|---|
--api-url <url> | Override the API URL |
swarm logout
Remove stored credentials.
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 |
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.
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) |
--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) |
- 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 |
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"
swarm test --url https://myapp.com --goal "Complete checkout" --swarm abc123
swarm test --url localhost:3000 --backend localhost:8080 --goal "Create a project"
swarm test --url localhost:3000 --goal "Edit profile settings" \
--login-url localhost:3000/login \
--username test@example.com
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.
swarm test --url localhost:3000 --goal "Explore settings" \
--cookies ./cookies.json \
--start-url http://localhost:3000/dashboard
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.
Displays swarm IDs, names, and persona counts. Use the ID with swarm test --swarm <id>.
