CLI

Overview

The Swirls CLI ships as a single, dependency-free executable. You can install it via script or package manager across Linux and macOS.

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

npm install -g @swirls/cli

After installation, verify the CLI is available by running:

swirls --version

Upgrade

Once installed, the CLI can upgrade itself:

swirls upgrade

This 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/swirls

npm uninstall -g @swirls/cli

Command 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 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 openapi

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

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 login

`swirls 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 whoami

`swirls auth logout`

Log out of the current account and delete locally stored credentials.

swirls auth logout

org

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 list

`swirls 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 list

The 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 deploy

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

migrate

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 create

`swirls project list`

List every project in your account, including its active, disabling, or disabled status.

Alias: swirls project ls

swirls project list

`swirls 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 configure

The 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 doctor

What 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 --strict

See 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 timeout override in seconds.
`--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-project

The 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 list

`swirls secret remove`

Remove a stored secret value from the project vault.

Alias: swirls secret rm

swirls secret remove OPENROUTER_API_KEY

workflow

`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 list

form

`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 generate

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

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

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 upgrade

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

On this page