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:

Remove the binary and, if desired, stored credentials:

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

npm uninstall -g @swirls/cli

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

project

`swirls project create`

Create a new project. The CLI prompts you for a project name.

swirls project create

`swirls project list`

List all projects 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:

Option	Type	Description
`projectId`	`string`	UUID of the Swirls project.
`genPath`	`string`	File path for generated TypeScript code. Defaults to `src/swirls.gen.ts`.

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:

Flag	Type	Description
`--input`	`string`	JSON object to pass as root input to the graph. Omit to be prompted from the schema.

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:

Flag	Type	Description
`--foreground`	`boolean`	Run the worker in the foreground instead of the background.

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

key

`swirls key create`

Create a new API key bound to the current user. The secret is shown only once at creation time.

swirls key create

`swirls key list`

List API keys bound to the current user.

Alias: swirls key ls

swirls key list

Flags:

Flag	Type	Description
`--revoked`	`boolean`	Include revoked keys in the list.

`swirls key revoke`

Revoke an API key. This action cannot be undone.

swirls key revoke

storage

`swirls storage list`

List files in storage. Pass an optional path to list a specific directory.

Alias: swirls storage ls

swirls storage list [path]

`swirls storage upload`

Upload a file to storage. Specify the local file path and an optional destination path in storage.

swirls storage upload <file> [dest]

Example:

swirls storage upload ./report.pdf reports/report.pdf

`swirls storage download`

Download a file from storage to a local destination.

swirls storage download <path> <dest>

Example:

swirls storage download reports/report.pdf ./report.pdf

`swirls storage delete`

Delete a file from storage.

swirls storage delete <path>

`swirls storage url`

Create a signed URL for a file in storage.

swirls storage url <path>

Flags:

Flag	Type	Description
`--expires`	`number`	Expiration time in seconds. Defaults to `86400` (24 hours).

Example:

swirls storage url reports/report.pdf --expires 3600

billing

`swirls billing usage`

Show feature usage for your account.

swirls billing usage

`swirls billing plans`

Show available plans.

swirls billing plans

`swirls billing upgrade`

Upgrade or change your plan.

swirls billing upgrade

`swirls billing portal`

Open the billing portal in your browser.

swirls billing portal

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.

CLI

On this page