CLI
Reference for the Swirls command line application.
Overview
The Swirls CLI ships as a single, dependency-free executable. You can install it with a script, a package manager, or a direct download across Linux, macOS, and Windows.
The CLI is the authoring and management surface for Swirls Cloud: validate .swirls files, deploy projects, run hosted playbooks, manage secrets and managed-database migrations, install registry integrations, generate TypeScript from project forms, and drive hosted workflow executions and agent chat sessions. Execution is hosted. Every runtime command is a client of the Swirls Cloud API.
Installation
curl -fsSL https://swirls.ai/install | bashRun this in PowerShell:
irm https://swirls.ai/install.ps1 | iexnpm install -g @swirls/cliAfter installation, verify the CLI is available by running:
swirls --versionWindows
The PowerShell installer detects your architecture, places swirls.exe in %USERPROFILE%\.local\bin, and adds that folder to your user PATH. Open a new terminal once it finishes so swirls is available in every window. To skip the upgrade prompt in a script, set $env:SWIRLS_YES = '1' before you run it.
Run the installer from PowerShell rather than Git Bash. Inside WSL, use the macOS & Linux command, which installs the Linux binary.
To install by hand, pick the binary that matches your machine. Running $env:PROCESSOR_ARCHITECTURE in PowerShell prints AMD64 for x64 or ARM64 for Arm.
| Architecture | Download |
|---|---|
| x64 | swirls-windows-x64.exe |
| Arm64 | swirls-windows-arm64.exe |
Save it as swirls.exe in a folder on your PATH. These commands do that for x64 in the same folder the installer uses:
New-Item -ItemType Directory -Force "$HOME\.local\bin" | Out-Null
Invoke-WebRequest https://releases.swirls.ai/cli/latest/swirls-windows-x64.exe -OutFile "$HOME\.local\bin\swirls.exe"If that folder is not on your PATH yet, add it under Edit environment variables for your account in Windows Settings, then open a new terminal.
To pin a release, replace latest in the URL with a version such as v0.1.143.
The Windows binaries are not code signed yet, so SmartScreen may warn you about a file downloaded in a browser. Installing from PowerShell is the simplest way to avoid that prompt.
Upgrade
Once installed, the CLI can upgrade itself:
swirls upgradeThis command fetches the latest version, compares it to your current install, and prompts you before upgrading.
Uninstall
To remove the CLI from your system:
Remove the binary and, if desired, stored credentials:
rm -f ~/.local/bin/swirls
rm -rf ~/.config/swirlsRemove the binary and, if desired, stored credentials:
Remove-Item "$HOME\.local\bin\swirls.exe"
Remove-Item -Recurse "$HOME\.config\swirls"The installer also added %USERPROFILE%\.local\bin to your user PATH. Remove that entry under Edit environment variables for your account in Windows Settings if nothing else uses the folder.
npm uninstall -g @swirls/cliCommand map
All commands are top-level. There is no cloud prefix.
| Command | Subcommands | What it does |
|---|---|---|
swirls add | Add registry integrations or import workflows from an API spec | |
swirls auth | login, logout, whoami | Authenticate and inspect your identity |
swirls org | list, switch | Inspect and switch organization context |
swirls deploy | Deploy the project to Swirls Cloud | |
swirls device | list, run, runs, result, cancel, tag, revoke, token | Enroll machines and run scripts on them |
swirls migrate | status, apply, new | Managed-database migrations |
swirls db | connections, connection | Managed-database named connections and connection strings |
swirls project | list, create, disable, enable | Manage projects in your account |
swirls configure | Write swirls.config.ts | |
swirls doctor | Validate and diagnose .swirls files | |
swirls test | Run hosted playbooks from the local workspace | |
swirls outdated | Check installed registry items for updates | |
swirls secret | set, list, remove | Manage the project vault |
swirls workflow | execute, list | Run and list deployed workflows |
swirls form | generate | Generate TypeScript from project forms |
swirls chat | start, resume, send, list, show, rm | Hosted agent chat sessions |
swirls update | Update installed registry items | |
swirls upgrade | Upgrade the CLI binary |
Commands
add
swirls add
Add integration action blocks from the Swirls registry by provider key, or generate the same action artifacts from an OpenAPI or GraphQL spec URL.
swirls add slack
swirls add linear create_issue
swirls add https://api.linear.app/graphql --only viewer,mutation_issueCreate
swirls add https://api.example.com/openapi.json --type openapiRegistry installs are tracked in lockfile.items. URL imports write actions under swirls/integrations/<provider>/ (plus a one-time connection scaffold) and record lockfile.imports.
Flags:
| Flag | Type | Description |
|---|---|---|
--registry | string | Registry base URL or local path. Defaults to the Swirls registry. |
--force | boolean | Overwrite existing registry item or import files. |
--type | string | Spec type for URL imports: openapi or graphql. |
--name | string | Provider / import name for URL imports. Defaults to a catalog match or a name derived from the URL. |
--tag | string | Filter URL import operations by OpenAPI tag. |
--only | string | Comma-separated operation or registry item ids for non-interactive selection. |
--all | boolean | Add or import all operations or items without prompting. |
--header | string | HTTP header for the spec fetch, as Name:Value. |
--yes | boolean | Skip confirmation prompts for URL imports. |
auth
Authentication commands for Swirls Cloud.
swirls auth login
Log in with a device authorization flow. The CLI requests a device code, opens the verification page in your browser, and shows a short user code in the terminal. Confirm the code in the browser to approve the login. The CLI polls until you approve, stores the access token locally, and prompts you to select an active organization in an interactive terminal. Without a terminal, use swirls auth whoami to inspect the session and swirls org switch <id-or-slug> to select an organization.
Run this command before any command that communicates with the API.
swirls auth loginswirls auth whoami
Show your logged-in name, email, user ID, and active organization’s name, slug, and ID. If no accessible organization is selected, the output tells you how to select one.
swirls auth whoamiswirls auth logout
Log out of the current account and delete locally stored credentials.
swirls auth logoutorg
Inspect and switch organizations using your existing login session.
swirls org list
List the organizations you belong to with their names, slugs, and IDs. An asterisk (*) marks the active organization.
Alias: swirls org ls
swirls org listswirls org switch
Select an organization interactively, or pass its exact slug or ID. Scripts and other non-interactive runs must pass a target.
swirls org switch
swirls org switch my-team
swirls auth whoami
swirls project listThe selected organization applies to subsequent CLI commands without logging in again. Commands in other terminals using the same stored login session share this context. Cancelling the picker leaves the context unchanged.
Switching organizations leaves the project ID in swirls.config.ts unchanged. Use the intended project’s directory/configuration or the command’s --project option to target another project.
deploy
swirls deploy
Compile every .swirls file in the project, validate the merged definition, and deploy it to Swirls Cloud as an immutable snapshot. On success the new deployment becomes the project's active deployment.
swirls deployThe target project comes from swirls.config.ts in the working directory. The deploy output includes the deployment name and ID, plus warnings for any missing vendor keys (with ready-to-run swirls secret set commands) and pending managed-database migrations.
Flags:
| Flag | Type | Description |
|---|---|---|
--name | string | Deployment name. Defaults to a fingerprint of the .swirls source files. |
--project | string | Project id or exact project name. Overrides swirls.config.ts. |
--create | boolean | Create the named project if it does not exist. |
You can also deploy with git push from a GitHub repository linked in the dashboard. See Swirls Cloud for both paths.
device
The device commands manage the machines enrolled into a project and run scripts on them. They cover the same ground as the Devices page in the dashboard, and they need the organization owner or admin role for anything that changes a device. See Devices for how enrollment and signed runs work.
Every command takes the project from swirls.config.ts in the working directory; pass --project <id-or-name> to target another project. A device is named by its name or its id. Names are hostnames, so when two devices share one, use the id from swirls device list.
swirls device token create
Create an enrollment token and print the commands to run on a machine. The token is printed once and is not stored, so it cannot be shown again.
swirls device token create --name "Front office rollout" --max-uses 25 --expires 7dFlags:
| Flag | Type | Description |
|---|---|---|
--name | string | Name for the token, such as the rollout it is for. Required. |
--max-uses | number | How many machines it can enroll, up to 10,000. Defaults to 1. |
--tag | string | Tag every device that enrolls with this token. Repeat for several. |
--expires | duration | How long it stays valid, from 1m to 30d. Defaults to 1d. |
The token alone is written to standard output, and the commands to run are written to standard error, so a script can capture the token:
TOKEN=$(swirls device token create --name "Imaging pipeline" --max-uses 100)swirls device token list
List enrollment tokens with their status and how many machines each has enrolled. Token values are never shown.
Alias: swirls device token ls
swirls device token revoke
Stop a token from enrolling any more machines. Devices that already enrolled with it stay enrolled. Pass the token id from swirls device token list, and --yes to skip the confirmation.
swirls device token revoke 0199f6a0-0000-7000-8000-000000000001 --yesswirls device list
List the devices in the project: name, whether each is online, its tags, its system, when it last checked in, and its id.
Alias: swirls device ls
swirls device list --tag front-office --os windowsFlags:
| Flag | Type | Description |
|---|---|---|
--tag | string | Only devices with this tag. Repeat for several; a device must have all of them. |
--os | windows, linux or macos | Only devices running this system. |
swirls device tag
Add, remove or replace the tags on a device. Tags group devices so swirls device run --tag can reach all of them.
swirls device tag WAREHOUSE-KIOSK --add kiosk --add site:aurora
swirls device tag WAREHOUSE-KIOSK --remove site:aurora
swirls device tag WAREHOUSE-KIOSK --set "kiosk, site:denver"Flags:
| Flag | Type | Description |
|---|---|---|
--add | string | Tag to add. Repeat for several. |
--remove | string | Tag to remove. Repeat for several. |
--set | string | Replace every tag with this comma-separated list. An empty value clears them. Cannot be combined with --add or --remove. |
swirls device run
Run a script on a device. The command waits for the device to collect the script and finish it, prints the script's output and errors, and exits with the script's exit code, so it behaves in a shell the way the script itself would.
swirls device run FRONT-DESK-01 --script ./collect-outlook-logs.ps1Leave the device out and pass --tag, --os or both to run on every active device that matches. The command waits for all of them, prints one line per device with its status and run id, and exits with code 0 only when the script succeeded on every device.
swirls device run --tag front-office --os windows --script ./restart-spooler.ps1Flags:
| Flag | Type | Description |
|---|---|---|
--script | string | Path of the script to run. Required. |
--name | string | Name for this run. Defaults to the script file name. |
--interpreter | powershell or sh | Defaults to the script's extension (.ps1 or .sh), then to what the device's system runs. A group with no --os and a script with neither extension needs this flag. |
--timeout | duration | How long the script may run, up to 1h. Defaults to 5m. |
--expires | duration | How long to wait for the device to check in, from 30s to 1d. Defaults to 1h. |
--detach | boolean | Print the run id and return without waiting for the result. For a group, prints one run id per device. |
--tag | string | Run on every device with this tag. Repeat for several; a device must have all of them. |
--os | windows, linux or macos | Run on every device running this system. |
When the script does not finish (the device refused it, never checked in, or the script timed out), the command says why and exits with code 1. Stopping the command with Ctrl-C does not cancel the run. Use swirls device cancel for a run the device has not collected.
A duration is a number with a unit: 90s, 10m, 6h or 2d. A bare number is seconds.
swirls device runs
List recent runs, newest first, with status, exit code and run id.
swirls device runs --device FRONT-DESK-01 --limit 50Flags:
| Flag | Type | Description |
|---|---|---|
--device | string | Only runs on this device. |
--limit | number | How many runs to list, up to 200. Defaults to 20. |
swirls device result
Print one run. The status goes to standard error and the script's output goes to standard output, so the output can be piped on its own.
swirls device result 0199f6a0-0000-7000-8000-000000000002 > outlook-logs.jsonswirls device cancel
Cancel a run the device has not collected yet. A run that has reached the device cannot be recalled.
swirls device revoke
Cut a device off. It stops receiving scripts on its next check-in and the runs it has not collected are canceled. To bring the machine back, enroll it again with a new token. Pass --yes to skip the confirmation.
swirls device revoke WAREHOUSE-KIOSKmigrate
Manage schema and data migrations for the managed databases your project declares.
swirls migrate status
Show migration status for each managed database in the active deployment.
swirls migrate status [--project <id-or-name>]swirls migrate apply
Approve gated managed-database migrations.
swirls migrate apply [--database <name>] [--yes]Flags:
| Flag | Type | Description |
|---|---|---|
--database | string | Approve only this database. Defaults to every gated migration. |
--yes | boolean | Approve without prompting. Required in non-interactive runs. |
--project | string | Project id or exact project name. |
swirls migrate new
Scaffold a migration block for a managed database.
swirls migrate new <migration_name> --database <name> [--file <path>]Flags:
| Flag | Type | Description |
|---|---|---|
--database | string | Name of the database block the migration targets. |
--file | string | File to append the block to. Defaults to migrations.swirls. |
db
List and reveal the named connections declared inside database blocks: see Database.
swirls db connections
List the named connections provisioned for the project's managed databases.
swirls db connections [--database <name>] [--project <id-or-name>]Flags:
| Flag | Type | Description |
|---|---|---|
--database | string | Filter to one managed database block. Defaults to every database in the project. |
--project | string | Project id or exact project name. |
swirls db connection
Print the connection string for a named connection. The direct URL goes to stdout, and a pooled URL is shown when the database offers one. Treat the output like a password.
swirls db connection <connection_name> --database <name> [--rotate] [--project <id-or-name>]Flags:
| Flag | Type | Description |
|---|---|---|
--database | string | Managed database block name. Required. |
--rotate | boolean | Rotate credentials before printing, invalidating the previous connection string. |
--project | string | Project id or exact project name. |
project
Project management commands for your Swirls Cloud account.
swirls project create
Create a new project in your account. The CLI prompts you for a project name.
swirls project createswirls project list
List every project in your account, including its active, disabling, or disabled status.
Alias: swirls project ls
swirls project listswirls project disable
Disable a project without deleting its resources. New executions stop immediately, live workflow and agent work is cancelled, and schedules pause without backfilling missed occurrences.
swirls project disable [--project <id-or-name>] [--yes]swirls project enable
Enable a fully disabled project. The command fails if the project is still disabling or if the organization's active-project allowance is full.
swirls project enable [--project <id-or-name>] [--yes]Both commands use the project pinned in swirls.config.ts when --project is omitted. --yes skips confirmation and is required for non-interactive use.
configure
swirls configure
Configure an application powered by Swirls. Creates a swirls.config.ts file in the current directory. The CLI prompts you to select a project. If a config file already exists, the command exits without overwriting it.
Alias: swirls config
swirls configureThe generated config file:
import { defineConfig } from '@swirls/sdk/config'
export default defineConfig({
projectId: '<your-project-id>',
genPath: 'src/swirls.gen.ts',
})Configuration options:
| Option | Type | Description |
|---|---|---|
projectId | string | UUID of the Swirls project. |
genPath | string | File path for generated TypeScript code. Defaults to src/swirls.gen.ts. |
doctor
swirls doctor
Validate every .swirls file under the working directory. The command parses each file, builds a workspace-wide resource index, and reports errors, warnings, and summary counts.
Use swirls doctor as your primary troubleshooting tool when workflows are missing, when swirls workflow list shows fewer workflows than you expect, or when you see validation errors in the editor.
swirls doctorWhat it reports:
| Category | Examples |
|---|---|
| Errors (exit 1) | Parse failures. Duplicate resource names anywhere in the workspace, with peer locations. Skill blocks with an empty name, a missing or invalid tree, or executable content. Mock action: / workflow: / node: references to unknown targets. Node mocks missing workflow:. Review formData or action output that fails JSON Schema validation. |
| Warnings | Registry drift on installed items, with the swirls update command to run. SKILL.md frontmatter names that do not match the directory slug. Unbound review mocks (no workflow: / node:). |
| Summary counts | Per-primitive totals: workflows, triggers, forms, secrets, agents, skills, streams, playbooks, mocks, and the rest. |
When the summary counts do not match the number of declarations you wrote, content is being silently dropped. See Common mistakes for the full list of causes and fixes.
Doctor checks local syntax and semantics. Deployment also checks server-side constraints, so a clean doctor run does not guarantee a successful deploy.
test
swirls test
Run playbooks declared in your local .swirls workspace on Swirls Cloud. The CLI compiles the workspace, creates a non-activating environment: test deployment, creates a PlaybookRun record, executes each matching case and eval, and prints results.
Requires swirls auth login and a configured project.
swirls test
swirls test --playbook smoke --tag ci --exclude-tag slow
swirls test --list
swirls test --reporter junit --strictSee Testing for supported assertions and current limitations. External-call stubs are not applied by the hosted runner, and review automation can act on other pending reviews in the same project.
Flags:
| Flag | Type | Description |
|---|---|---|
--project | string | Project id or exact project name. |
--playbook | string | Run only this playbook. |
--case | string | Run only this case. |
--eval | string | Run only this eval. |
--tag | string | Include cases/evals with this tag. |
--exclude-tag | string | Exclude cases/evals with this tag. |
--reporter | string | pretty (default), json, or junit. |
--strict | boolean | Fail on soft assertions and soft judge scores. |
--fail-fast | boolean | Stop scheduling new cases after the first gate failure. |
--mock-mode | string | Override review automation mode: all, off, or selective. Does not stub external calls. |
--list | boolean | List discovered tests without running. |
--timeout | number | Per-case wait in seconds. Overrides case timeout: and the 120 second default. The failure names the limit that fired. |
--verbose | boolean | Print the text each passing includes or matches compared, plus scores, reasons, execution IDs, and durations. |
--artifacts | string | Directory for results.json artifact output. |
--keep-deployment | boolean | Recorded in artifacts; current CLI retains test deployments in either mode. |
outdated
swirls outdated
List installed registry items and whether local copies are up to date. Pass a provider key and item ids to narrow the check.
swirls outdated [provider] [items...]Flags:
| Flag | Type | Description |
|---|---|---|
--registry | string | Registry base URL or local path. Defaults to the Swirls registry. |
--check | boolean | Exit with code 1 when any installed item is outdated or missing. |
secret
The secret commands manage the project vault: the encrypted, project-scoped store that hosted executions read at runtime. Keys must be declared in a DSL secret block (including vendor API keys like OPENROUTER_API_KEY). Use type: managed in the DSL for Enterprise platform-supplied keys — those cannot be set via the CLI.
When a deploy reports missing vendor keys, executions for the affected nodes are held until the keys are declared and satisfiable.
swirls secret set
Store a secret value in the project vault for a declared (non-managed) secret block var. Values are stored as block::VAR.
swirls secret set OPENROUTER_API_KEY=sk-or-...
swirls secret set SMTP_PASSWORD=...
swirls secret set RESEND_API_KEY=re_... --project my-projectThe project comes from swirls.config.ts in the working directory; pass --project <id-or-name> to target another project.
swirls secret list
List the project's secret keys and whether a value is set. Values are never displayed.
Alias: swirls secret ls
swirls secret listswirls secret remove
Remove a stored secret value from the project vault.
Alias: swirls secret rm
swirls secret remove OPENROUTER_API_KEYworkflow
swirls workflow execute
Execute a deployed workflow by name in your hosted project. This requires a paid plan and is not available on the free inspection-only tier. If workflow_name is omitted, the CLI prompts you to select from available workflows. If --input is omitted, the CLI prompts for input based on the workflow's schema.
Alias: swirls workflow exec
swirls workflow execute [workflow_name]Flags:
| Flag | Type | Description |
|---|---|---|
--input | string | JSON object to pass as root input to the workflow. Omit to be prompted from the schema. |
--verbose | boolean | Print detailed execution output. |
Example:
swirls workflow execute my_workflow --input '{"query": "hello world"}'swirls workflow list
List available workflows in the current project.
Alias: swirls workflow ls
swirls workflow listform
swirls form generate
Generate application code and types from project forms. Reads swirls.config.ts, fetches all forms with schemas from the API, and writes the generated output to the path specified by genPath.
Alias: swirls form gen
swirls form generateThe generated file includes Zod schemas, a form registry, a registerForms() function, and module augmentation for full type safety. See TypeScript generation for details.
chat
The chat commands manage persistent hosted agent sessions when agent chat is enabled for your Swirls Cloud project. Sessions keep a full transcript between runs.
swirls chat start
Start a new hosted agent session. If agent_name is omitted, the CLI prompts you to select an agent from your project.
swirls chat start [agent_name] [--title <title>] [--input <json>] [--detached]Flags:
| Flag | Type | Description |
|---|---|---|
--title | string | Optional label for the session. |
--input | string | Initial JSON input to pass to the agent. |
--detached | boolean | Start the session without attaching to it interactively. |
swirls chat resume
Resume an existing interactive session by ID.
Alias: swirls chat talk
swirls chat resume <sessionId>swirls chat send
Send a single message to a session without entering interactive mode.
swirls chat send <sessionId> --message <text>Flags:
| Flag | Type | Description |
|---|---|---|
--message | string | The message text to send. Required. |
The command waits until the turn completes, fails, or is cancelled, then prints the reply. If the live connection drops or misses the final update, it reads that run's stored turn and still exits once the turn is finished. It reconnects while the turn is running. After 15 minutes it stops and tells you to run swirls chat show <sessionId>. A failed or cancelled turn exits with an error.
swirls chat list
List recent CLI chat sessions. Filter by agent name with --agent.
Alias: swirls chat ls
swirls chat list [--agent <name>]swirls chat show
Show the persisted transcript for a session. Failed turns print as agent: [turn failed] <error> and cancelled turns print as agent: [turn cancelled], immediately after the user message for that run. Completed turns stay as their messages. A turn that cannot be placed is printed at the end. Those errors are not part of messages. --json prints the session, including turns (runId, status, and error when one was recorded).
swirls chat show <sessionId> [--json]Flags:
| Flag | Type | Description |
|---|---|---|
--json | boolean | Output the transcript as JSON. |
swirls chat rm
Delete a session and its messages.
swirls chat rm <sessionId>update
swirls update
Update installed registry items from the remote registry. Without arguments, everything outdated is updated. Pass a provider key and item ids to narrow the update.
swirls update [provider] [items...]Flags:
| Flag | Type | Description |
|---|---|---|
--registry | string | Registry base URL or local path. Defaults to the Swirls registry. |
--force | boolean | Overwrite locally modified files without confirmation. |
upgrade
swirls upgrade
Update the CLI to the latest version. Works with both the install-script and package-manager installations.
swirls upgradeNext steps
- Testing: declare playbooks and run
swirls test. - TypeScript generation: Learn what code is generated and how to use it with the SDK.
- API reference: Interact with the Swirls API programmatically.
- SDK reference: Typed TypeScript client for the Swirls API.