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

cloud

The cloud route groups every command that talks to Swirls Cloud: authentication, project management, and deployment.

swirls cloud 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 cloud auth login

swirls cloud auth logout

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

swirls cloud auth logout

swirls cloud 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 cloud deploy

Add this command to your deploy step alongside whatever runs on push.

swirls cloud project create

Create a new project in your account. The CLI prompts you for a project name.

swirls cloud project create

swirls cloud project list

List every project in your account.

Alias: swirls cloud project ls

swirls cloud 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 graphs are missing, when swirls graph list shows fewer graphs 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/graph.swirls
    ✓ graph process_contact
    ✓ trigger on_contact

  shared/secrets.swirls
    ✓ secret stripe_creds

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

  billing/auth.swirls
    ✓ auth stripe_auth

Summary: 3 graphs, 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.

graph

swirls graph execute

Execute a graph by name. If graph_name is omitted, the CLI prompts you to select from available graphs. If --input is omitted, the CLI prompts for input based on the graph's schema.

Alias: (none)

swirls graph execute [graph_name]

Flags:

Example:

swirls graph execute my-graph --input '{"query": "hello world"}'

swirls graph list

List available graphs in the current project.

Alias: swirls graph ls

swirls graph list

env

The env commands manage environment variables used during graph execution. Use these to store API keys and other secrets that graphs need at runtime.

swirls env set

Set one or more environment variables for graph execution.

swirls env set KEY=VALUE
swirls env set OPENAI_API_KEY=sk-... ANOTHER_KEY=value

swirls env list

List environment variables stored for graph execution.

Alias: swirls env ls

swirls env list

swirls env remove

Remove one or more environment variables.

Alias: swirls env rm

swirls env remove KEY

worker

The worker runs graph executions locally using a SQLite-backed queue. Start it during local development to process graph jobs triggered by your application.

swirls worker start

Start the graph execution worker. By default, the worker starts in the background.

swirls worker start

Flags:

Example (foreground):

swirls worker start --foreground

swirls worker status

Show the current status of the worker.

swirls worker status

swirls worker stop

Stop the background worker.

swirls worker stop

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.