> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sirenspec.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install SirenSpec and run your first workflow in under five minutes.

## Installation

The fastest way to install SirenSpec is the one-line install script:

```bash theme={null}
curl -fsSL https://sirenspec.dev/install.sh | sh
```

This detects your environment and uses the best available installer (uv → pipx → pip). Python 3.11 or later is required.

<Tabs>
  <Tab title="curl (recommended)">
    ```bash theme={null}
    curl -fsSL https://sirenspec.dev/install.sh | sh
    ```

    Detects your environment and picks the best available installer (uv → pipx → pip).
  </Tab>

  <Tab title="uv">
    ```bash theme={null}
    uv tool install sirenspec
    ```
  </Tab>

  <Tab title="pipx">
    ```bash theme={null}
    pipx install sirenspec
    ```
  </Tab>

  <Tab title="pip">
    ```bash theme={null}
    pip install sirenspec
    ```
  </Tab>
</Tabs>

## Set Your API Key

SirenSpec reads provider credentials from environment variables. Set at least one:

```bash theme={null}
export OPENAI_API_KEY=sk-...
# or
export ANTHROPIC_API_KEY=sk-ant-...
```

## Initialize Your Project

Run `sirenspec init` to scaffold a workflow interactively. It asks you to pick a template and a provider, then writes a `workflow.yaml` and a `.env.example` ready to run:

```bash theme={null}
sirenspec init
```

```
Welcome to SirenSpec! Let's scaffold a new workflow.

Choose a template:
  1. simple-agent          — Single agent that answers a question
  2. sequential-pipeline   — Two agents in sequence
  ...

Template [1]: 1

Choose a provider:
  1. openai
  2. anthropic

Provider [1]: 1

Enable guardrails? (injection + length) [Y/n]: Y

✓ workflow.yaml created
✓ .env.example created

Next steps:
  Copy .env.example → .env and add your API key
  sirenspec validate workflow.yaml
  sirenspec run workflow.yaml
```

## Run It

```bash theme={null}
sirenspec run workflow.yaml
```

By default, SirenSpec displays a streaming view of node execution:

```
╭─ answer ──────────────────────────────╮
│ Paris is the capital of France.       │
╰────────────────────────────────────────╯
  ↓ output.reply

Run complete  │  1 node  │  24 tokens  │  cost unavailable (pricing not configured)
```

To see the full JSON execution trace, use the `--trace` flag:

```bash theme={null}
sirenspec run workflow.yaml --trace
```

## Start from Scratch

Prefer writing YAML yourself? Create a file named `hello.yaml`:

```yaml hello.yaml theme={null}
version: "0.1"

agents:
  assistant:
    model: "openai:gpt-4o-mini"
    system: "You are a helpful assistant. Answer questions clearly and concisely."

nodes:
  answer:
    agent: assistant
    writes: output.reply

input:
  message: "What is the capital of France?"
```

Then run it:

```bash theme={null}
sirenspec run hello.yaml
```

## Override the Input at Runtime

Use `--input` (or `-i`) to pass a message from the command line, overriding any `input.message` defined in the YAML:

```bash theme={null}
sirenspec run hello.yaml --input "What is the speed of light?"
```

## Validate Without Running

Check that your workflow is valid without making any API calls:

```bash theme={null}
sirenspec validate hello.yaml
# ✓ hello.yaml is valid (1 agent, 1 node)
```

## Try a Multi-Agent Pipeline

The Cookbook includes ready-to-run workflows. Clone the repo and try:

```bash theme={null}
git clone https://github.com/sirenspec/sirenspec.git
cd sirenspec

# Sequential pipeline: classify → reply
sirenspec run docs/cookbook/sequential-pipeline/workflow.yaml --input "I need help with my order"

# Conditional branching: triage → handle_refund or handle_general
sirenspec run docs/cookbook/conditional-pipeline/workflow.yaml --input "I want a refund"
```

## Next Steps

<CardGroup cols={2}>
  <Card title="YAML Reference" icon="book" href="/yaml-reference">
    Learn every field available in a workflow file.
  </Card>

  <Card title="Providers" icon="server" href="/providers">
    Configure OpenAI, Anthropic, and Ollama.
  </Card>

  <Card title="Guardrails" icon="shield" href="/guardrails">
    Understand the built-in guardrail system.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli-reference">
    Full CLI command documentation.
  </Card>
</CardGroup>