Local Development

Authenticate

Open a browser-based OAuth flow and store credentials locally:

swirls auth login

Create or select a project

Create a new project interactively:

swirls project create

To see existing projects:

swirls project list

Configure the project

Generate a swirls.config.ts in your working directory:

swirls configure

The command prompts for your project ID and writes the config file:

import { defineConfig } from '@swirls/sdk/config'

export default defineConfig({
  projectId: '<your-project-id>',
  genPath: 'src/swirls.gen.ts',
})

The CLI reads swirls.config.ts to determine which project all commands apply to. You can also run swirls config as an alias.

Set environment variables

Set API keys and other secrets your graph nodes need at runtime:

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

List all configured variables:

swirls env list

Remove a variable:

swirls env remove OPENAI_API_KEY

These variables are available to nodes during local graph execution.

Write .swirls files

Write your graph definitions in .swirls files. See the Swirls Language reference for syntax and available node types.

Generate TypeScript types

Generate TypeScript types and Zod schemas from your project's form definitions:

swirls form gen

The CLI writes generated code to the path set in genPath. Import these types in your application to get end-to-end type safety when triggering graphs.

Start the local worker

The worker is a SQLite-backed process that executes graphs on your machine. Start it in the background:

swirls worker start

To keep the process in the foreground (useful for seeing logs directly):

swirls worker start --foreground

Check worker status or stop it:

swirls worker status
swirls worker stop

The worker must be running for local graph execution to work.

Execute graphs

List available graphs in your project:

swirls graph list

Execute a graph by name:

swirls graph execute my-graph

Pass input as JSON:

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

After execution, open the Portal to inspect node outputs, trace execution steps, and debug errors.