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.

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:

rm -f ~/.local/bin/swirls
rm -rf ~/.config/swirls

npm uninstall -g @swirls/cli

Commands

auth

Authentication commands for Swirls Cloud.

swirls auth login

Log in with an existing account using a browser-based OAuth flow. The CLI opens your default browser to the Swirls sign-in page. After you sign in, the browser redirects to a local callback server that exchanges the authorization code for session tokens and stores them locally.

Run this command before any command that communicates with the API.

swirls auth login

swirls auth logout

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

swirls auth logout

deploy

swirls deploy

Compile every .swirls file in the workspace and deploy the resulting workflow definitions to the project linked in swirls.config.ts. This is the only command you need to ship a workflow to production.

swirls deploy

Run this command to push your current workspace to Swirls Cloud. No CI/CD pipeline required. You can also deploy with git push from a linked GitHub repository.

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.

Alias: swirls project ls

swirls project list

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:

doctor

swirls doctor

Validate all .swirls files in the current workspace. The command parses each file, runs the validator, and reports parse errors, validator diagnostics, and unresolved references.

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 [path]

Pass an optional path to validate a specific file or directory instead of the entire workspace.

Example output:

Workspace: /my-project
Files: 4 .swirls files found

  contacts/workflow.swirls
    ✓ workflow process_contact
    ✓ trigger on_contact

  shared/secrets.swirls
    ✓ secret stripe_creds

  billing/workflow.swirls
    ✗ node charge (type: http): Node references undefined auth block "stripe_auth"

  billing/auth.swirls
    ✓ auth stripe_auth

Summary: 3 workflows, 1 trigger, 2 secrets, 2 auth blocks
Errors: 1

What it reports:

When the summary counts do not match the number of declarations you wrote, a parser bug is silently dropping content. See Common mistakes for the full list of causes and fixes.

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.

workflow

swirls workflow execute

Execute a workflow by name in a hosted project that has workflow execution enabled. 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:

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

secret

The secret commands manage the project vault: the encrypted, project-scoped store that hosted executions read at runtime. Use these for model and API vendor keys (OPENROUTER_API_KEY, RESEND_API_KEY, ...) and for values declared by secret blocks in your .swirls files.

When a deploy reports missing vendor keys, executions for the affected nodes are held until the keys are set. Storing them with swirls secret set releases new runs.

swirls secret set

Store a secret value in the project vault. The kind is detected automatically: keys declared by a secret block are stored as block vars, everything else as vendor keys. Override with --kind vendor or --kind block.

swirls secret set OPENROUTER_API_KEY=sk-or-...
swirls secret set SMTP_PASSWORD=... --kind block
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 with their kind 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

worker (removed)

The local CLI worker (swirls worker start, swirls worker stop, swirls worker status) has been removed. Workflow execution and agent chat are hosted capabilities, not local runtime features.

Use the CLI locally to author, validate, generate types, and deploy .swirls files. Hosted execution commands require a project where that capability is enabled.

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:

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:

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:

swirls chat rm

Delete a session and its messages.

swirls chat rm <sessionId>

upgrade

swirls upgrade

Update the CLI to the latest version. Works with both the install-script and package-manager installations.

swirls upgrade

Next steps

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