CLI Reference¶

Yagra provides command-line tools for workflow management, validation, and visualization.

Command Overview¶

yagra <command> [options]

Available commands:

init: Initialize from template
schema: Export JSON Schema
validate: Validate workflow YAML
golden: Manage golden regression test cases
studio: Launch visual editor WebUI
handlers: Display params schema for built-in handlers
explain: Statically analyze workflow YAML
prompt: Manage and inspect prompt YAML files
mcp: Start MCP server in stdio mode

`yagra init`¶

Initialize a workflow from a template.

Usage¶

yagra init --template <template_name> --output <directory> [--force]
yagra init --list

Options¶

Option	Description	Default
`--template`	Template name to use (`branch`, `chat`, `human-review`, `loop`, `multi-agent`, `parallel`, `rag`, `subgraph`, `tool-use`)	Required (unless `--list`)
`--output`	Output directory	Current directory (`.`)
`--force`	Overwrite existing files	`False`
`--list`	List available templates	N/A

Examples¶

List templates:

yagra init --list

Output:

Available templates:
  - branch
  - chat
  - human-review
  - loop
  - multi-agent
  - parallel
  - rag
  - subgraph
  - tool-use

Initialize from template:

yagra init --template branch --output my-workflow

Overwrite existing files:

yagra init --template loop --output existing-dir --force

Behavior¶

Copies template files to output directory
Creates workflow.yaml (and prompts/<template>_prompts.yaml if the template uses prompts)
Validates the generated workflow
Reports success or validation errors

`yagra schema`¶

Export JSON Schema for workflow YAML. Useful for coding agents and IDE autocomplete.

Usage¶

yagra schema [--output <file>]

Options¶

Option	Description	Default
`--output`	Output file path	Print to stdout

Examples¶

Print to stdout:

yagra schema

Save to file:

yagra schema --output workflow-schema.json

Behavior¶

Exports GraphSpec Pydantic model as JSON Schema
Includes all field definitions, validation rules, and descriptions
Compatible with JSON Schema Draft 7

Use Cases¶

Coding agents: Let agents generate valid workflows
IDE support: Enable autocomplete in editors (e.g., VS Code with YAML extension)
Documentation: Generate schema documentation automatically

`yagra validate`¶

Validate a workflow YAML file and report issues.

Usage¶

yagra validate --workflow <file> [--bundle-root <dir>] [--format <text|json>]

Options¶

Option	Description	Default
`--workflow`	Path to workflow YAML	Required
`--bundle-root`	Base directory for reference resolution	Workflow parent directory
`--format`	Output format (`text` or `json`)	`text`

Examples¶

Basic validation:

yagra validate --workflow workflows/support.yaml

JSON output (for agent consumption):

yagra validate --workflow workflows/support.yaml --format json

Custom bundle root:

yagra validate --workflow workflows/support.yaml --bundle-root /path/to/project

Output Formats¶

Text Format (Default)¶

Human-readable output:

✓ ワークフローは valid です。

Or if invalid:

✗ ワークフローに問題があります:

[ERROR] nodes.0.id: field required
[ERROR] edges.0.source: node 'unknown_node' does not exist

JSON Format¶

Structured output for agents:

{
  "is_valid": false,
  "issues": [
    {
      "severity": "error",
      "category": "schema",
      "message": "field required",
      "location": "nodes.0.id"
    },
    {
      "severity": "error",
      "category": "reference",
      "message": "node 'unknown_node' does not exist",
      "location": "edges.0.source"
    }
  ]
}

Exit Codes¶

0: Valid workflow
1: Invalid workflow

Validation Steps¶

Yagra validates:

Schema compliance: YAML matches GraphSpec Pydantic model
Node ID uniqueness: No duplicate node IDs
Edge references: All source/target nodes exist
Start/End validity: start_at and end_at nodes exist
Prompt references: prompt_ref paths resolve to valid files
Fallback references: fallback node IDs exist and are not self-referencing
Prompt-state consistency (warning): {variable} in prompts should exist in state_schema or upstream output_key; output_key should be declared in state_schema

Note: is_valid is determined by error-severity issues only. Warning and info-level issues (such as prompt-state consistency hints) are reported but do not cause is_valid to be false.

`yagra golden`¶

Manage golden cases for workflow regression testing.

Usage¶

yagra golden save --trace <trace.json> --name <case-name> [--description <text>] \
  [--strategy <node_id:strategy>]... [--golden-dir <dir>]
yagra golden test --workflow <workflow.yaml> [--name <case-name>] [--golden-dir <dir>] \
  [--bundle-root <dir>] [--format <text|json>]
yagra golden list [--workflow <workflow-name>] [--golden-dir <dir>] [--format <text|json>]

`yagra golden save`¶

Create a golden case from a trace JSON file.

Options¶

Option	Description	Default
`--trace`	Path to trace JSON file	Required
`--name`	Golden case name (kebab-case)	Required
`--description`	Human-readable case description	`""`
`--strategy`	Per-node comparison override. Repeatable. Format: `node_id:strategy` (`exact`, `structural`, `skip`, `auto`)	None
`--golden-dir`	Golden case base directory	`.yagra/golden`

Examples¶

# Basic save
yagra golden save --trace .yagra/traces/translate/run.json --name happy-path

# Save with per-node strategy overrides
yagra golden save \
  --trace .yagra/traces/translate/run.json \
  --name strict-format-check \
  --strategy translate:structural \
  --strategy format:exact

`yagra golden test`¶

Run saved golden cases against a workflow YAML.

Options¶

Option	Description	Default
`--workflow`	Path to workflow YAML file	Required
`--name`	Specific case name (runs all cases if omitted)	None
`--golden-dir`	Golden case base directory	`.yagra/golden`
`--bundle-root`	Base directory for split-reference resolution	Workflow parent
`--format`	Output format (`text` or `json`)	`text`

Examples¶

# Run all cases for a workflow
yagra golden test --workflow workflows/translate.yaml

# Run one case
yagra golden test --workflow workflows/translate.yaml --name happy-path

# Machine-readable output
yagra golden test --workflow workflows/translate.yaml --format json

`yagra golden list`¶

List saved golden cases.

Options¶

Option	Description	Default
`--workflow`	Filter by workflow name	None
`--golden-dir`	Golden case base directory	`.yagra/golden`
`--format`	Output format (`text` or `json`)	`text`

Example¶

yagra golden list

`yagra studio`¶

Launch an interactive WebUI for visual workflow editing.

Usage¶

yagra studio [--workflow <file>] [--bundle-root <dir>] [--ui-state <file>] \
  [--workspace-root <dir>] [--backup-dir <dir>] [--host <host>] [--port <port>]

Options¶

Option	Description	Default
`--workflow`	Workflow YAML to edit	None (launcher mode)
`--bundle-root`	Base directory for reference resolution	Workflow parent
`--ui-state`	UI sidecar JSON path	`<workflow>.workflow-ui.json`
`--workspace-root`	Workspace root for launcher	Current directory
`--backup-dir`	Backup directory	`.yagra/backups`
`--host`	Bind host	`127.0.0.1`
`--port`	Bind port	`8787`

Examples¶

Launcher mode (recommended):

yagra studio --port 8787

Opens a launcher UI where you can:

Select existing workflows
Create new workflows

Direct workflow editing:

yagra studio --workflow workflows/support.yaml --port 8787

Custom workspace:

yagra studio --workspace-root /path/to/project --port 8787

Features¶

Visual Editing¶

Node Properties: Handler input uses a type selector with automatic form adaptation:
- Handler type selector: choose llm, structured_llm, streaming_llm, or custom
  - Predefined types auto-fill the handler name (no manual typing required)
  - custom type enables free-text input for user-defined handlers
- llm / structured_llm / streaming_llm → Prompt Settings and Model Settings displayed
- structured_llm → Additional Schema Settings section (edit schema_yaml as YAML text)
- streaming_llm → Additional Streaming Settings section (stream: false checkbox)
- custom → LLM-specific sections hidden (free-text handler name input visible)
Drag & Drop: Add nodes, connect edges, adjust layout
Re-wiring: Drag edge endpoints to change connections

Workflow Settings (Right Panel)¶

The Workflow Settings panel on the right side of the canvas controls global workflow configuration:

Field	Description
`version`	Workflow schema version (default: `1.0`)
`start_at`	Entry node selected from a dropdown
`end_at`	Exit nodes selected via checkboxes
`interrupt_before`	Nodes to pause before (HITL) selected via checkboxes
`interrupt_after`	Nodes to pause after (HITL) selected via checkboxes
`state_schema`	Typed state field definitions (table editor)

Setting Up `state_schema` in Studio¶

The state_schema section lets you define typed fields for the workflow state directly in the UI:

In the Workflow Settings panel, scroll to the state_schema section
Click + Add Field to add a new row
Fill in each column:
- field name: The key used in state (e.g., messages, results, query)
- type: One of str, int, float, bool, list, dict, messages
- reducer: Leave empty for default overwrite behavior, or select add for fan-in merging of list fields
Click ✕ on a row to remove it
Click Preview Diff to review the generated YAML, then Save

Example configurations:

Use Case	field name	type	reducer
Chat history	`messages`	`messages`	(none)
Parallel fan-in	`results`	`list`	`add`
Query string	`query`	`str`	(none)

The generated YAML will look like:

state_schema:
  messages:
    type: messages
  results:
    type: list
    reducer: add
  query:
    type: str

Note: fan_out edges and subgraph nodes require YAML direct editing — the Studio currently supports state_schema only as a table editor.

Resilience Settings (Node Properties)¶

The Resilience Settings section in the Node Properties panel allows configuration of retry, timeout, and fallback behavior per node. Available for all handler types.

Field	Description
Enable retry	Toggle to activate retry behavior
max attempts	Maximum retry attempts (1–10). Default: 3
backoff	Strategy: `exponential` (delays double each attempt) or `fixed` (constant delay)
base delay (s)	Initial delay in seconds between retries (0–60). Default: 2
timeout (seconds)	Maximum execution time for the node (1–600). Leave empty for no timeout
fallback node	Dropdown to select a fallback node (executes if the node fails after retries)

These settings map directly to the YAML retry, timeout_seconds, and fallback fields on the node. See Workflow YAML Reference — Resilience for details.

Diff Preview¶

View exact YAML diff before saving
Validation results inline with diff
Reject or accept changes

Backup & Rollback¶

Automatic backup on save
List available backups
Rollback to previous version by backup ID

Live Validation¶

Studio validates your workflow automatically as you edit:

Debounced auto-validation: Every form change (node edits, edge edits, metadata changes, connections) triggers a validation request after a 400ms debounce delay via POST /api/workflow/validate
Severity-aware display: Issues are shown with color-coded severity badges — error (red), warning (yellow), info (blue)
Canvas node highlights: Nodes with validation errors are highlighted with a red border; nodes with warnings get a yellow border
Warning-aware pass state: When is_valid is true but warnings/info exist, displays “Validation passed (with warnings)” alongside the issue list
Prevents saving invalid workflows: Save is blocked when error-level issues exist

Accessing Studio¶

After starting the server:

yagra studio --port 8787

Output:

workflow studio started: http://127.0.0.1:8787
press Ctrl+C to stop

Open http://127.0.0.1:8787/ in your browser.

Studio UI Overview¶

Graph Canvas: Visual workflow editor (drag, drop, connect)
Node Properties: Form for editing selected node
Edge Properties: Form for editing selected edge
Diff Panel: Preview changes before saving
Backup Panel: Manage backups and rollback

Studio Workflow¶

Select/Create Workflow: Choose from launcher or load directly
Edit Visually:
- Click node to edit properties
- Drag from output port to input port to connect
- Drag edge endpoint to rewire
Preview Changes: Click “Preview Diff”
Save: Click “Save” to persist changes
Rollback (if needed): Select backup and restore

`yagra handlers`¶

Display the params schema for each built-in handler.

Usage¶

yagra handlers [--format <text|json>]

Options¶

Option	Description	Default
`--format`	Output format (`text` or `json`)	`text`

Built-in Handlers¶

Handler	Description
`llm`	Standard LLM call with prompt rendering
`structured_llm`	LLM call that returns structured (schema-constrained) output
`streaming_llm`	LLM call with server-sent event streaming support

Examples¶

Text output (human-readable):

yagra handlers

Output:

llm
  model        (str, required)   LLM model name to use.
  temperature  (float, optional) Sampling temperature. Default: 0.0
  ...

structured_llm
  model        (str, required)   LLM model name to use.
  schema_yaml  (str, required)   YAML string defining the output schema.
  ...

streaming_llm
  model        (str, required)   LLM model name to use.
  stream       (bool, optional)  Enable streaming mode. Default: true
  ...

JSON output (for agent consumption):

yagra handlers --format json

Output:

{
  "llm": { ... },
  "structured_llm": { ... },
  "streaming_llm": { ... }
}

`yagra explain`¶

Statically analyze a workflow YAML and report its structure: entry point, exit points, execution paths, required handlers, and variable flow.

Usage¶

yagra explain --workflow <file|-> [--bundle-root <dir>] [--format <text|json>]

Options¶

Option	Description	Default
`--workflow`	Path to workflow YAML, or `-` to read from stdin	Required
`--bundle-root`	Base directory for reference resolution	Workflow parent directory
`--format`	Output format (`text` or `json`)	`json`

Examples¶

Analyze a workflow file:

yagra explain --workflow workflows/support.yaml

Read from stdin:

cat workflows/support.yaml | yagra explain --workflow -

Text output:

yagra explain --workflow workflows/support.yaml --format text

Pipe JSON output to jq:

yagra explain --workflow workflows/support.yaml | jq '.execution_paths'

JSON Output Structure¶

{
  "entry_point": "start_node",
  "exit_points": ["end_node_a", "end_node_b"],
  "execution_paths": [
    ["start_node", "branch_node", "end_node_a"],
    ["start_node", "branch_node", "end_node_b"]
  ],
  "required_handlers": ["llm", "structured_llm"],
  "variable_flow": {
    "start_node": {
      "inputs": [],
      "outputs": ["user_input"]
    },
    "branch_node": {
      "inputs": ["user_input"],
      "outputs": ["response"]
    }
  }
}

Field	Description
`entry_point`	ID of the node where execution begins
`exit_points`	IDs of nodes where execution terminates
`execution_paths`	All possible node sequences from entry to exit
`required_handlers`	Distinct handler names referenced by the workflow
`variable_flow`	Per-node mapping of input and output variable names

`yagra analyze`¶

Aggregate and summarize execution traces stored under .yagra/traces/. Useful for identifying slow nodes, high error rates, or patterns across multiple runs.

Usage¶

yagra analyze [--trace-dir <dir>] [--workflow <name>] [--limit <n>] [--format <text|json>]

Options¶

Option	Description	Default
`--trace-dir`	Root trace directory	`.yagra/traces`
`--workflow`	Filter by workflow name	All workflows
`--limit`	Limit to N most recent traces	No limit
`--format`	Output format (`text` or `json`)	`text`

Examples¶

Summarize all traces:

yagra analyze

Filter by workflow name:

yagra analyze --workflow my-workflow

Show the 10 most recent traces as JSON:

yagra analyze --workflow my-workflow --limit 10 --format json

Pipe JSON output to jq:

yagra analyze --format json | jq '.node_summaries[] | select(.error_rate > 0)'

JSON Output Structure¶

{
  "workflow_name": "my-workflow",
  "total_traces": 20,
  "node_summaries": [
    {
      "node_id": "classifier",
      "avg_latency_ms": 342,
      "error_rate": 0.0
    },
    {
      "node_id": "answer_faq",
      "avg_latency_ms": 1820,
      "error_rate": 0.05
    }
  ],
  "suggestions": [
    "answer_faq: high latency detected — consider prompt optimization"
  ]
}

`yagra prompt`¶

Manage and inspect prompt YAML files.

`yagra prompt info`¶

Display metadata and version information for a prompt YAML file.

yagra prompt info --file <path> [--format text|json]

Options:

--file (required): Path to the prompt YAML file
--format: Output format — text (default) or json

Output (text format):

File path
Version from _meta.version (or “(not set)” if absent)
Changelog entries from _meta.changelog (if present)
List of prompt keys (excluding _meta)

Example:

$ yagra prompt info --file prompts.yaml
File: /path/to/prompts.yaml
Version: 2.0
Changelog:
  - 2.0: Added persona variable to system prompt
  - 1.0: Initial version
Prompt keys: greeting, farewell

JSON output:

$ yagra prompt info --file prompts.yaml --format json
{
  "file": "/path/to/prompts.yaml",
  "version": "2.0",
  "changelog": ["2.0: Added persona variable", "1.0: Initial version"],
  "prompt_keys": ["greeting", "farewell"],
  "meta": {"version": "2.0", "changelog": ["..."]}
}

Prompt YAML `_meta` Section¶

Prompt YAML files can include an optional _meta section for version metadata:

_meta:
  version: "2.0"
  changelog:
    - "2.0: Added persona variable to system prompt"
    - "1.0: Initial version"

greeting:
  system: "You are {persona}."
  user: "Hello! My name is {user_name}."

The _meta.version value is checked against @version suffixes in prompt_ref references during validation. See Prompt Model for details.

`yagra mcp`¶

Start a Model Context Protocol (MCP) server in stdio mode, allowing AI agents and editors to interact with Yagra programmatically.

Installation¶

The MCP extra must be installed:

uv add 'yagra[mcp]'

Usage¶

yagra mcp

The server communicates over stdin/stdout using the MCP protocol. No additional options are required.

Provided Tools¶

Tool	Required params	Description
`validate_workflow`	`yaml_content` or `workflow_path`	Validate a workflow YAML and return structured issues. Pass `yaml_content` for inline YAML or `workflow_path` for file-based validation. Optional: `base_dir` to resolve relative `prompt_ref` paths.
`explain_workflow`	`yaml_content` or `workflow_path`	Statically analyze a workflow YAML and return execution paths, required handlers, and variable flow. Pass `yaml_content` or `workflow_path`.
`list_templates`	—	List available `yagra init` templates with name, description, and use_case.
`list_handlers`	—	List built-in handlers and their params schemas.
`get_template`	`name`	Return the file contents of a template (workflow.yaml + prompt files). Use `list_templates` first to get the name.
`get_traces`	—	Retrieve raw execution trace records from `.yagra/traces/`. Optional: `workflow_name`, `limit`, `trace_dir`.
`analyze_traces`	—	Aggregate execution traces and return per-node statistics (success rate, latency, token usage, cost). Optional: `workflow_name`, `limit`, `trace_dir`.
`propose_update`	`workflow_path`, `candidate_yaml`	Preview a YAML change as a diff with validation result. Optional: `reason`.
`apply_update`	`workflow_path`, `candidate_yaml`	Apply the candidate YAML with an automatic backup. Returns `backup_id`. Optional: `base_revision`, `backup_dir`.
`rollback_update`	`workflow_path`, `backup_id`	Restore the workflow to a previous backup. Optional: `backup_dir`.
`run_golden_tests`	`workflow_path`	Run golden regression tests against the workflow. Optional: `golden_dir`, `case_name`, `format`.

Example: Claude Desktop Integration¶

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "yagra": {
      "command": "yagra",
      "args": ["mcp"]
    }
  }
}

Example: VS Code / Cursor Integration¶

{
  "mcp": {
    "servers": {
      "yagra": {
        "command": "yagra",
        "args": ["mcp"]
      }
    }
  }
}

Once connected, the agent has access to all 11 tools listed in the table above. See the Optimization Cycle guide for end-to-end usage examples.

Environment Variables¶

Yagra does not currently use environment variables for CLI configuration. All options are passed via command-line flags.

Exit Codes¶

Code	Meaning
0	Success
1	Validation error or operation failed
2	Invalid command-line arguments

CLI Reference¶

Command Overview¶

yagra init¶

Usage¶

Options¶

Examples¶

Behavior¶

yagra schema¶

Usage¶

Options¶

Examples¶

Behavior¶

Use Cases¶

yagra validate¶

Usage¶

Options¶

Examples¶

Output Formats¶

Text Format (Default)¶

JSON Format¶

Exit Codes¶

Validation Steps¶

yagra golden¶

Usage¶

yagra golden save¶

Options¶

Examples¶

yagra golden test¶

Options¶

Examples¶

yagra golden list¶

Options¶

Example¶

yagra studio¶

Usage¶

Options¶

Examples¶

Features¶

Visual Editing¶

Workflow Settings (Right Panel)¶

Setting Up state_schema in Studio¶

Resilience Settings (Node Properties)¶

Diff Preview¶

Backup & Rollback¶

Live Validation¶

Accessing Studio¶

Studio UI Overview¶

Studio Workflow¶

yagra handlers¶

Usage¶

Options¶

Built-in Handlers¶

Examples¶

yagra explain¶

Usage¶

Options¶

Examples¶

JSON Output Structure¶

yagra analyze¶

Usage¶

Options¶

Examples¶

JSON Output Structure¶

See Also¶

yagra prompt¶

yagra prompt info¶

Prompt YAML _meta Section¶

yagra mcp¶

Installation¶

Usage¶

Provided Tools¶

Example: Claude Desktop Integration¶

Example: VS Code / Cursor Integration¶

Environment Variables¶

Exit Codes¶

Next Steps¶

`yagra init`¶

`yagra schema`¶

`yagra validate`¶

`yagra golden`¶

`yagra golden save`¶

`yagra golden test`¶

`yagra golden list`¶

`yagra studio`¶

Setting Up `state_schema` in Studio¶

`yagra handlers`¶

`yagra explain`¶

`yagra analyze`¶

`yagra prompt`¶

`yagra prompt info`¶

Prompt YAML `_meta` Section¶

`yagra mcp`¶