CLI

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

Run this in PowerShell:

irm https://swirls.ai/install.ps1 | iex
npm install -g @swirls/cli

After installation, verify the CLI is available by running:

swirls --version

Windows

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.

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

Remove 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/cli

Command map

All commands are top-level. There is no cloud prefix.

CommandSubcommandsWhat it does
swirls addAdd registry integrations or import workflows from an API spec
swirls authlogin, logout, whoamiAuthenticate and inspect your identity
swirls orglist, switchInspect and switch organization context
swirls deployDeploy the project to Swirls Cloud
swirls devicelist, run, runs, result, cancel, tag, revoke, tokenEnroll machines and run scripts on them
swirls migratestatus, apply, newManaged-database migrations
swirls dbconnections, connectionManaged-database named connections and connection strings
swirls projectlist, create, disable, enableManage projects in your account
swirls configureWrite swirls.config.ts
swirls doctorValidate and diagnose .swirls files
swirls testRun hosted playbooks from the local workspace
swirls outdatedCheck installed registry items for updates
swirls secretset, list, removeManage the project vault
swirls workflowexecute, listRun and list deployed workflows
swirls formgenerateGenerate TypeScript from project forms
swirls chatstart, resume, send, list, show, rmHosted agent chat sessions
swirls updateUpdate installed registry items
swirls upgradeUpgrade 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:

FlagTypeDescription
--registrystringRegistry base URL or local path. Defaults to the Swirls registry.
--forcebooleanOverwrite existing registry item or import files.
--typestringSpec type for URL imports: openapi or graphql.
--namestringProvider / import name for URL imports. Defaults to a catalog match or a name derived from the URL.
--tagstringFilter URL import operations by OpenAPI tag.
--onlystringComma-separated operation or registry item ids for non-interactive selection.
--allbooleanAdd or import all operations or items without prompting.
--headerstringHTTP header for the spec fetch, as Name:Value.
--yesbooleanSkip 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 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:

FlagTypeDescription
--namestringDeployment name. Defaults to a fingerprint of the .swirls source files.
--projectstringProject id or exact project name. Overrides swirls.config.ts.
--createbooleanCreate 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 7d

Flags:

FlagTypeDescription
--namestringName for the token, such as the rollout it is for. Required.
--max-usesnumberHow many machines it can enroll, up to 10,000. Defaults to 1.
--tagstringTag every device that enrolls with this token. Repeat for several.
--expiresdurationHow 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 --yes

swirls 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 windows

Flags:

FlagTypeDescription
--tagstringOnly devices with this tag. Repeat for several; a device must have all of them.
--oswindows, linux or macosOnly 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:

FlagTypeDescription
--addstringTag to add. Repeat for several.
--removestringTag to remove. Repeat for several.
--setstringReplace 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.ps1

Leave 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.ps1

Flags:

FlagTypeDescription
--scriptstringPath of the script to run. Required.
--namestringName for this run. Defaults to the script file name.
--interpreterpowershell or shDefaults 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.
--timeoutdurationHow long the script may run, up to 1h. Defaults to 5m.
--expiresdurationHow long to wait for the device to check in, from 30s to 1d. Defaults to 1h.
--detachbooleanPrint the run id and return without waiting for the result. For a group, prints one run id per device.
--tagstringRun on every device with this tag. Repeat for several; a device must have all of them.
--oswindows, linux or macosRun 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 50

Flags:

FlagTypeDescription
--devicestringOnly runs on this device.
--limitnumberHow 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.json

swirls 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-KIOSK

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:

FlagTypeDescription
--databasestringApprove only this database. Defaults to every gated migration.
--yesbooleanApprove without prompting. Required in non-interactive runs.
--projectstringProject 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:

FlagTypeDescription
--databasestringName of the database block the migration targets.
--filestringFile 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:

FlagTypeDescription
--databasestringFilter to one managed database block. Defaults to every database in the project.
--projectstringProject 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:

FlagTypeDescription
--databasestringManaged database block name. Required.
--rotatebooleanRotate credentials before printing, invalidating the previous connection string.
--projectstringProject 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:

OptionTypeDescription
projectIdstringUUID of the Swirls project.
genPathstringFile 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:

CategoryExamples
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.
WarningsRegistry 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 countsPer-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:

FlagTypeDescription
--projectstringProject id or exact project name.
--playbookstringRun only this playbook.
--casestringRun only this case.
--evalstringRun only this eval.
--tagstringInclude cases/evals with this tag.
--exclude-tagstringExclude cases/evals with this tag.
--reporterstringpretty (default), json, or junit.
--strictbooleanFail on soft assertions and soft judge scores.
--fail-fastbooleanStop scheduling new cases after the first gate failure.
--mock-modestringOverride review automation mode: all, off, or selective. Does not stub external calls.
--listbooleanList discovered tests without running.
--timeoutnumberPer-case wait in seconds. Overrides case timeout: and the 120 second default. The failure names the limit that fired.
--verbosebooleanPrint the text each passing includes or matches compared, plus scores, reasons, execution IDs, and durations.
--artifactsstringDirectory for results.json artifact output.
--keep-deploymentbooleanRecorded 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:

FlagTypeDescription
--registrystringRegistry base URL or local path. Defaults to the Swirls registry.
--checkbooleanExit 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:

FlagTypeDescription
--inputstringJSON object to pass as root input to the workflow. Omit to be prompted from the schema.
--verbosebooleanPrint 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:

FlagTypeDescription
--titlestringOptional label for the session.
--inputstringInitial JSON input to pass to the agent.
--detachedbooleanStart 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:

FlagTypeDescription
--messagestringThe 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:

FlagTypeDescription
--jsonbooleanOutput 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:

FlagTypeDescription
--registrystringRegistry base URL or local path. Defaults to the Swirls registry.
--forcebooleanOverwrite 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

On this page