Quickstart

Install the CLI

curl -fsSL https://swirls.ai/install | bash

npm install -g @swirls/cli

After installation, verify the CLI is available by running:

swirls --version

Write your first workflow

Create a file called workflow.swirls:

form contact {
  label: "Contact"
  enabled: true
  schema: @json {
    {
      "type": "object",
      "required": ["name", "email", "message"],
      "properties": {
        "name": { "type": "string" },
        "email": { "type": "string" },
        "message": { "type": "string" }
      },
      "additionalProperties": false
    }
  }
}

graph process_contact {
  label: "Process Contact"

  root {
    type: code
    label: "Normalize"
    inputSchema: @json {
      {
        "type": "object",
        "required": ["name", "email", "message"],
        "properties": {
          "name": { "type": "string" },
          "email": { "type": "string" },
          "message": { "type": "string" }
        },
        "additionalProperties": false
      }
    }
    outputSchema: @json {
      {
        "type": "object",
        "required": ["name", "email", "message"],
        "properties": {
          "name": { "type": "string" },
          "email": { "type": "string" },
          "message": { "type": "string" }
        },
        "additionalProperties": false
      }
    }
    code: @ts {
      const { name, email, message } = context.nodes.root.input
      return {
        name: name.trim(),
        email: email.toLowerCase().trim(),
        message: message.trim(),
      }
    }
  }

  node summarize {
    type: ai
    label: "Summarize"
    kind: object
    model: "anthropic/claude-3.5-sonnet"
    prompt: @ts {
      return `Summarize this contact submission in one sentence: ${context.nodes.root.output.message}`
    }
    schema: @json {
      {
        "type": "object",
        "required": ["summary"],
        "properties": { "summary": { "type": "string" } }
      }
    }
  }

  flow {
    root -> summarize
  }
}

trigger on_contact {
  form:contact -> process_contact
  enabled: true
}

Set environment variables

We use OpenRouter to execute your ai nodes. Create an account, generate an API key, and run the following:

swirls env set OPENROUTER_API_KEY=...

Set any API keys your nodes need.

Start the worker

swirls worker start

Starts a local SQLite-backed execution engine.

Run your graph

swirls graph execute

Deploy to Swirls Cloud

swirls deploy

What's next

Language reference - Master the .swirls file format
Node types - All 12 node types
Platform - Local development workflow
Deploy to Swirls Cloud - Run in production

What you can build

AI content generation with human review gates
Lead scoring and enrichment pipelines
Automated support ticket triage
Scheduled data reports from persistent streams
Form-driven workflows with email notifications

Quickstart

On this page