Skip to main content

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

​
swarm login

Authenticate with your Swarm account via browser. 
swarm login [options]
OptionDescription
--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 test

Run an AI-powered UX test against a URL. 
swarm test [options]

​
Target & goal

OptionDescription
--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

OptionDescription
--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

OptionDescription
--no-tunnelSkip tunnel setup (URL must be publicly accessible)
--tunnel-provider <provider>Tunnel provider: cloudflare, ngrok, or auto (default: auto)

​
Backend proxy

OptionDescription
--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

OptionDescription
--login-url <url>Login page URL for authenticated testing
--username <username>Username or email
--password <password>Password (prefer interactive prompt or --password-stdin)
--password-stdinRead password from stdin for scripting

​
Advanced

OptionDescription
--max-steps <n>Maximum steps per agent (default: 30)
--provider <provider>AI provider: openai or anthropic
--model <model>Model name override
-y, --yesSkip 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: 
swarm test --url localhost:3000 --goal "Edit profile settings" \
  --login-url localhost:3000/login \
  --username test@example.com
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>.