Skip to main content

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.

​
Installation

The sirenspec CLI is installed automatically when you add the package: 
uv add sirenspec
# or
pip install sirenspec
After installation, the sirenspec command is available on your PATH.

​
sirenspec run

Execute a workflow and print the JSON execution trace to stdout. 
sirenspec run <workflow-file> [OPTIONS]
Arguments:
ArgumentDescription
workflow-filePath to the workflow YAML file.
Options:
OptionShortDescription
--input TEXT-iUser input message. Overrides input.message in the YAML.
Exit codes:
CodeMeaning
0Workflow completed successfully.
1File not found, validation error, execution error, or guardrail violation.
Examples: 
# Run with input defined in the YAML file
sirenspec run workflow.yaml

# Override the input from the command line
sirenspec run workflow.yaml --input "What is the capital of France?"
sirenspec run workflow.yaml -i "What is the capital of France?"

# Pipe the JSON output to jq
sirenspec run workflow.yaml --input "Hello" | jq '.output'
Output format: The JSON trace is written to stdout. Errors and validation messages go to stderr. 
{
  "workflow": { "version": "0.1" },
  "input": { "message": "What is the capital of France?" },
  "nodes": [
    {
      "id": "answer",
      "agent": "assistant",
      "prompt_sent": "What is the capital of France?",
      "response_received": "Paris is the capital of France.",
      "writes": "output.reply",
      "guardrails_passed": [
        "InjectionGuardrail.check_input",
        "InjectionGuardrail.check_output"
      ],
      "tokens": 24,
      "duration_ms": 312.5,
      "error": null
    }
  ],
  "output": {
    "reply": "Paris is the capital of France."
  },
  "summary": {
    "total_tokens": 24,
    "total_duration_ms": 312.5,
    "status": "success"
  }
}
Trace fields:
FieldDescription
workflow.versionSchema version from the YAML file.
input.messageThe user input that was used.
nodesOrdered list of executed nodes.
nodes[].idNode identifier.
nodes[].agentAgent that executed this node.
nodes[].prompt_sentInput passed to the LLM (after input guardrails).
nodes[].response_receivedLLM output (after output guardrails).
nodes[].writesContext path where the output was written.
nodes[].guardrails_passedList of guardrail check methods that succeeded.
nodes[].tokensTotal tokens used by this node.
nodes[].duration_msWall-clock time for this node in milliseconds.
nodes[].errorError message if the node failed, otherwise null.
outputFinal output context (all output.* paths).
summary.total_tokensSum of tokens across all nodes.
summary.total_duration_msSum of durations across all nodes.
summary.status"success" or "failed".

​
sirenspec validate

Validate a workflow YAML file without executing it or making any API calls. 
sirenspec validate <workflow-file>
Arguments:
ArgumentDescription
workflow-filePath to the workflow YAML file.
Exit codes:
CodeMeaning
0File is valid.
1File not found or validation failed.
Examples: 
sirenspec validate workflow.yaml
# ✓ workflow.yaml is valid (2 agents, 3 nodes)

sirenspec validate broken.yaml
# ✗ Validation failed: agents.assistant.model: field required
What is validated:
  • YAML syntax (including duplicate key detection).
  • Required fields (version, agents, nodes).
  • Agent fields (model, system).
  • Node fields (agent, writes).
  • Edge references — all from and to values must refer to existing nodes.
  • Node agent references — all agent values must refer to existing agents.
Provider credentials and when: expressions are not evaluated during validation.

​
sirenspec render

Render a workflow as a diagram without executing it or making any API calls. 
sirenspec render <workflow-file> --target <format> [OPTIONS]
Arguments:
ArgumentDescription
workflow-filePath to the workflow YAML file.
Options:
OptionShortDescription
--target TEXTRender target format. Currently only mermaid is supported.
--output TEXT-oWrite output to a file instead of stdout.
Exit codes:
CodeMeaning
0Rendered successfully.
1File not found, validation error, or unsupported target.
Examples: 
# Print a Mermaid flowchart to stdout
sirenspec render workflow.yaml --target mermaid

# Save to a file
sirenspec render workflow.yaml --target mermaid --output diagram.md
sirenspec render workflow.yaml --target mermaid -o diagram.md
Output format: The mermaid target produces a graph TD flowchart. Unconditional edges are plain arrows; conditional edges are labeled with their when: expression. 
graph TD
    triage[triage]
    handle_refund[handle_refund]
    handle_general[handle_general]
    triage -->|"working.triage.intent == 'refund'"| handle_refund
    triage -->|"working.triage.intent == 'general'"| handle_general
Paste this into any Mermaid renderer (GitHub markdown, Mermaid Live Editor, etc.) to visualise the workflow graph.