Skip to content

cli-reference.md

Latest commit

 

History

History
284 lines (199 loc) · 7.94 KB

cli-reference.md

File metadata and controls

284 lines (199 loc) · 7.94 KB

CLI Reference

Complete command-line reference for Conductor.

Table of Contents

conductor run

Execute a workflow from a YAML file.

conductor run <workflow.yaml> [OPTIONS]

Options

Option Short Description
--input NAME=VALUE -i Workflow input (repeatable)
--input.NAME=VALUE Alternative input syntax
--provider PROVIDER -p Override provider (copilot, claude)
--dry-run Show execution plan without running
--skip-gates Auto-select first option at human gates
--quiet -q Minimal output (agent lifecycle and routing only)
--silent -s No progress output (JSON result only)
--log-file <auto|PATH> -l Write full debug output to a file
--web Start a real-time web dashboard
--web-bg Run in background, print dashboard URL, exit
--web-port PORT Port for web dashboard (0 = auto-select)
--no-interactive Disable Esc-to-interrupt capability

Examples

Basic Execution

# Run with a single input
conductor run workflow.yaml --input question="What is AI?"

# Run with multiple inputs
conductor run workflow.yaml -i question="Hello" -i context="Greeting"

# Alternative input syntax
conductor run workflow.yaml --input.question="What is AI?"

Provider Override

# Override the workflow's default provider
conductor run workflow.yaml --provider claude

# Use Copilot instead of Claude
conductor run workflow.yaml -p copilot

Dry Run and Debugging

# Preview execution plan without running
conductor run workflow.yaml --dry-run

# Quiet output (agent lifecycle only)
conductor run workflow.yaml --quiet --input question="Test"

# Write full debug log to a file
conductor run workflow.yaml --log-file debug.log

Web Dashboard

# Start dashboard in foreground (keeps running after workflow completes)
conductor run workflow.yaml --web --input question="Test"

# Start dashboard on a specific port
conductor run workflow.yaml --web --web-port 8080 --input question="Test"

# Background mode: prints URL and exits immediately
conductor run workflow.yaml --web-bg --input question="Test"
# Dashboard auto-shuts down after workflow completes and clients disconnect

The --web flag starts a real-time browser dashboard showing:

  • DAG visualization of the workflow graph with live node state updates
  • Agent detail panel with rendered prompt, reasoning, tool calls, and output
  • Streaming activity as agents execute (reasoning chunks, tool invocations)

The --web-bg flag is a convenience shortcut: it forks a background process running the workflow with the dashboard, prints the URL, and exits the CLI immediately. The background process shuts down automatically after the workflow completes and all browser clients disconnect.

--web and --web-bg are mutually exclusive.

Background workflows can be stopped with conductor stop (see below) or via the stop button in the web dashboard.

Automation Mode

# Skip human gates (auto-select first option)
conductor run workflow.yaml --skip-gates

# CI/CD pattern: silent console + full file log
conductor run workflow.yaml --silent --log-file auto --skip-gates --input question="Automated test"

Complex Inputs

# JSON array input
conductor run workflow.yaml --input items='["item1", "item2", "item3"]'

# JSON object input
conductor run workflow.yaml --input config='{"key": "value", "count": 5}'

# Multi-line input (use quotes)
conductor run workflow.yaml --input text="Line 1
Line 2
Line 3"

conductor stop

Stop background workflow processes launched with --web-bg.

conductor stop [OPTIONS]

Options

Option Description
--port PORT Stop the workflow running on this specific port
--all Stop all background conductor workflows

With no options, conductor stop lists running background workflows. If exactly one is found, it stops automatically. If multiple are running, it prints the list and asks you to specify --port.

How It Works

When a workflow is launched with --web-bg, Conductor writes a PID file to ~/.conductor/runs/ tracking the background process. The stop command reads these PID files, sends SIGTERM to the process, and cleans up the file. PID files are also automatically cleaned up when a background workflow completes normally.

The web dashboard also has a stop button that cancels the running workflow directly via POST /api/stop.

Examples

# Stop the only running background workflow
conductor stop

# Stop a specific workflow by port
conductor stop --port 8080

# Stop all running background workflows
conductor stop --all

conductor validate

Validate a workflow file without executing it. Checks YAML syntax, schema compliance, and cross-references (agent names, routes, parallel groups).

conductor validate <workflow.yaml>

Examples

# Validate a single workflow
conductor validate my-workflow.yaml

# Validate with full path
conductor validate ./workflows/production/main.yaml

# Validate all examples (using shell expansion)
for f in examples/*.yaml; do conductor validate "$f"; done

Validation Checks

  • YAML syntax errors
  • Schema compliance (required fields, types)
  • Agent name references in routes
  • Parallel group agent references
  • For-each source references
  • Circular dependency detection
  • Input/output schema validation

conductor registry

Manage workflow registries — named sources (GitHub repos or local directories) for shared workflows.

conductor registry <subcommand> [OPTIONS]

Subcommands

Subcommand Description
list [NAME] List registries, or list workflows in a specific registry
add <NAME> <SOURCE> Add a new registry (GitHub owner/repo or local path)
remove <NAME> Remove a registry
set-default <NAME> Set the default registry
update [NAME] Update cached registry index (all or specific)
show <NAME> Show registry details and status

Options

Option Description
--default Mark as the default registry (with add)

Examples

# Add a GitHub-hosted registry and set it as default
conductor registry add official myorg/conductor-workflows --default

# Add a local directory registry
conductor registry add local ./my-workflows

# List all configured registries
conductor registry list

# List workflows in a specific registry
conductor registry list official

# Show registry details
conductor registry show official

# Set a different default
conductor registry set-default local

# Update cached registry index
conductor registry update

# Remove a registry
conductor registry remove local

Running Workflows from a Registry

Once a registry is configured, conductor run accepts short workflow names:

# Run from default registry (latest version)
conductor run qa-bot

# Run from a specific registry
conductor run qa-bot@official

# Run a specific version
conductor run qa-bot@official@1.2.3

See design/registry.md for the full design.

Environment Variables

Variable Description
ANTHROPIC_API_KEY API key for Claude provider
GITHUB_TOKEN Token for Copilot provider (if not using GitHub CLI auth)
CONDUCTOR_LOG_LEVEL Logging level: DEBUG, INFO, WARNING, ERROR

Exit Codes

Code Meaning
0 Success
1 Workflow execution error
2 Validation error
3 Configuration error
130 User interrupt (Ctrl+C)

See Also