Quickstart

Two ways to start. Hand the init prompt to your AI agent and it does everything below for you: registration, your first .swirls files, validation, and the deploy. Or set up manually and walk the same path yourself.

Paste this into your agent (Claude Code, Cursor, or any agent that can run commands). It registers you with Swirls, asks what you want to build, writes the .swirls files, and deploys. You approve one email and read one 6-digit code back to the agent.

init prompt

Set me up with Swirls (swirls.ai) and deploy my first agentic workflow. Follow these steps in order.

1. Register an account for me. Fetch https://swirls.ai/auth.md and follow it exactly, including where to store the credential for the CLI. Use the email flow: ask me for my email address, register, and tell me to open the approval email from Swirls. I will click the link, approve, and read you a 6-digit code from the approval page. The code is only on that page, never in the email. While I am getting the code, ask me what I want to build (what the workflow or agent should do, what triggers it: a form, a webhook, a schedule, or chat, and what it should produce) and where on my machine the project should live. If I do not know what to build, offer to set me up with a starter so I can get a feel for Swirls: fetch https://swirls.ai/starters/index.json, describe each starter in one line, let me pick or pick for me, and download its files into the project directory. Starters are validated ahead of time; use their files as written. Create the project directory and work inside it. Do not continue past registration until you have exchanged my code for a credential.

2. Install the Swirls CLI. Ask my permission, then run:
curl -fsSL https://swirls.ai/install | bash

3. Learn the language before writing any files. Fetch https://swirls.ai/.well-known/agent-skills/swirls-lang/SKILL.md and the rules it tells you to read first; rule links resolve relative to that URL. Use only syntax the spec explicitly allows. Never invent keywords, node types, or fields.

4. Write the .swirls files for what I described, or use the starter's files as downloaded. Projects can span multiple files. Validate with swirls doctor and fix every finding before deploying.

5. Deploy without prompts, exactly as auth.md documents:
swirls deploy --project <project-name> --create --name initial
Pick a short project name from what I am building.

6. If the deploy output warns about missing vendor keys, executions are held until those keys exist. Ask me for each key value (for example my OpenRouter or Anthropic API key) and store it with the exact command the deploy output prints, like: swirls secret set OPENROUTER_API_KEY=<value>. Never guess or invent key values.

7. Tell me the deployment id and remind me I can watch executions at https://swirls.ai/app. The approval step already signed me in there.

If any request returns an error code, the Errors table in auth.md says what to do. If swirls doctor keeps failing on syntax, re-read the spec rules instead of guessing.

When it finishes, your project is live in the Portal and the approval step already signed you in there.

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:

schema contact_payload {
  label: "Contact submission"
  schema: @json {
    {
      "type": "object",
      "required": ["name", "email", "message"],
      "properties": {
        "name": { "type": "string" },
        "email": { "type": "string" },
        "message": { "type": "string" }
      },
      "additionalProperties": false
    }
  }
}

form contact {
  label: "Contact"
  enabled: true
  schema: contact_payload
}

workflow process_contact {
  label: "Process Contact"

  root {
    type: code
    label: "Normalize"
    inputSchema: contact_payload
    outputSchema: contact_payload
    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
}

Validate locally

Check that Swirls can parse and validate your files:

swirls doctor

Authenticate and deploy

swirls auth login
swirls deploy

This uploads your .swirls files to Swirls Cloud so you can inspect the compiled project in the Portal.

Inspect the project

Open the Portal and verify the compiled workflow, form, trigger, and schemas. Free deploys are for authoring and inspection; they do not execute workflows or start agent chats.

What's next

Language reference: master the .swirls file format
Node types: all node types and their fields
Platform: local authoring workflow
Deploy to Swirls Cloud: hosted runtime and deployment

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