Deploy your first project

Install the CLI, validate a .swirls project, and inspect your first deployment in Swirls Cloud.

This walkthrough takes you from a local .swirls file to a deployment you can inspect in Swirls Cloud. The example declares a form, a workflow, and a trigger so you can see how several primitives compose into one project.

Prefer to work with a coding agent? Follow Set up with a coding agent for the copyable setup prompt. Both paths lead to a deployed project.

Before you start

You need a terminal and access to a Swirls account. The CLI runs locally; workflows and agent chats execute on Cloud. Free deployments support inspection. To run the example, your project also needs hosted execution access and the vendor credentials requested by the deployment.

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

Configure a project

mkdir my-swirls-project
cd my-swirls-project
swirls auth login
swirls project create
swirls configure

swirls configure writes swirls.config.ts. Select the project you just created, or an existing project you want to use.

Write your first workflow

Create workflow.swirls in this directory. It declares a credential requirement, an input schema, a public form, a workflow, and a trigger.

secret vendor_keys {
  vars: [OPENROUTER_API_KEY]
}

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"
  visibility: public
  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: "google/gemini-2.5-flash"
    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

Deploy to Cloud

swirls deploy

The CLI uploads the project definition and source, then reports the deployment. If it reports missing vendor keys, configure those values with the command it provides before trying to execute the workflow. Do not put credential values in .swirls files.

Inspect the project

Open Swirls Cloud, select your project, and open the deployment. Check that it contains:

The contact_payload input schema.
The contact form.
The process_contact workflow, with normalization and summarization steps.
The on_contact trigger connecting the form to the workflow.

You now have a deployed project. Free deployments support this inspection step; they do not execute workflows or start agent chats.

Run and verify

When hosted execution is enabled and the required credentials are configured, open the deployed form and submit a name, email, and message. In Traces, find the resulting workflow run and inspect the normalized input and the summarization node's output.

If no run starts, check the project's execution access, credential warnings, and trigger configuration. For a run that fails, open the failed span and use its error to identify the step that needs attention.

Continue learning

Platform overview — projects, deployments, and the managed runtime.
Infrastructure — where code runs and data lives.
Primitives — the building blocks available in a project.
Local development — authoring tools and type generation.
Testing — repeatable verification with playbooks.

Deploy your first project

On this page