CLI Reference

July 21, 2026 · View on GitHub

Complete command-line reference for Conductor.

Root-Level Options
conductor run
conductor stop
conductor gate respond
conductor checkpoint list
conductor validate
conductor doctor
conductor registry
Deprecated command aliases

Root-Level Options

The following root-level options must appear before the subcommand name:

conductor [ROOT OPTIONS] <command> [ARGS] [OPTIONS]

Option	Short	Description
`--quiet`	`-q`	Minimal output (agent lifecycle and routing only)
`--silent`	`-s`	No progress output (JSON result only)
`--version`	`-v`	Show version and exit

--quiet and --silent are mutually exclusive. They control workflow progress output (run / resume); other commands may not be affected.

# Correct: root-level option before the subcommand
conductor --quiet run workflow.yaml

# Incorrect: rejected with "No such option: --quiet"
conductor run workflow.yaml --quiet

`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
`--metadata KEY=VALUE`	`-m`	Workflow metadata (repeatable). Merged on top of YAML `metadata:` and surfaced in the `workflow_started` event.
`--workspace-instructions`		Auto-discover convention files (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, and `.github/instructions/*/.instructions.md`) by walking from CWD up to the git root. Concatenated and prepended to every agent's prompt. See Workspace Instructions below for details on the `.github/instructions/` directory convention.
`--instructions PATH`		Explicit path to an instructions file (repeatable). Combines with auto-discovered files when both flags are used.
`--provider PROVIDER`	`-p`	Override provider (copilot, claude, claude-agent-sdk, hermes)
`--dry-run`		Show execution plan without running
`--skip-gates`		Auto-select first option at human gates
`--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

Note: Output verbosity (--quiet/-q, --silent/-s) is controlled by root-level options, which must appear before the run subcommand: conductor --quiet run workflow.yaml.

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) — note: --quiet is a root-level option
# and must come before the run subcommand
conductor --quiet run workflow.yaml --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.

--web-bg and human_gate — background runs support human gates through the dashboard. When the workflow reaches a human_gate, the detached process waits for a response from the web dashboard (the gate modal) or the conductor gate respond CLI, rather than trying to prompt on the (absent) stdin. At launch, when the workflow contains a human_gate (and --skip-gates is not set), Conductor prints a notice with the dashboard URL and the conductor gate respond command so a parked run doesn't look stuck:

Resolve each gate from the dashboard's decision modal, or
Run conductor gate respond --port <port> --choice <value> (optionally --agent <name> and --input "<text>"), or
Pass --skip-gates to auto-select the first option at every gate.

The same behavior applies to conductor resume --web-bg.

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
# (--silent is a root-level option and must come before the run subcommand)
conductor --silent run workflow.yaml --log-file auto --skip-gates --input question="Automated test"

Metadata and Instructions

# Inject runtime metadata (visible in the workflow_started event)
conductor run twig-sdlc.yaml --metadata work_item_id=1814 --metadata env=staging

# Auto-discover and inject convention instruction files (see "Workspace Instructions" below)
conductor run workflow.yaml --workspace-instructions

# Combine auto-discovery with an explicit extra file
conductor run workflow.yaml --workspace-instructions --instructions ./style-guide.md

Workspace Instructions

When --workspace-instructions is set, conductor walks from the current working directory up to the git root and discovers four conventions, in this order:

Convention	Type	Discovery
`AGENTS.md`	File	Closest-to-CWD wins
`.github/copilot-instructions.md`	File	Closest-to-CWD wins
`CLAUDE.md`	File	Closest-to-CWD wins
`.github/instructions/*/.instructions.md`	Directory (recursive)	Closest-to-CWD wins per relative path within the directory

The directory convention follows GitHub Copilot's documented format (GitHub docs, VS Code docs):

Files must use the double *.instructions.md extension.

A YAML frontmatter block with applyTo controls activation:

---
description: 'Coding conventions for the API layer'
applyTo: '**'
---
Use four-space indentation.

applyTo: "**" → loaded as always-on (matches Copilot's "always applied").
applyTo: "<other glob>" → skipped (the convention scopes these per-file in the chat; conductor has no equivalent per-agent file scoping).
applyTo absent → skipped (the convention says these are manual-attach only, never auto-applied).

This conservative interpretation matches the documented semantics exactly. To include unscoped instructions today, use the explicit --instructions PATH flag.

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 exposes terminate controls that always preserve progress:

Stop (POST /api/stop) interrupts the current agent and pauses it, then offers Resume (re-run the agent) or Kill. If clicked during the brief startup window before the engine is ready, the Stop is queued and honored as soon as the engine binds its interrupt event (rather than hard-cancelling).
Kill (POST /api/kill) stops the workflow entirely. A best-effort checkpoint is written so you can conductor resume later, and the dashboard shows a "Workflow Stopped" banner with the checkpoint path (or a clear explanation if no checkpoint could be saved).

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 gate respond`

Resolve a parked human_gate step from the command line without opening a browser. Sends a gate response to a running workflow's web dashboard via HTTP — useful for SSH sessions or headless environments where the dashboard UI is unreachable.

conductor gate respond [OPTIONS]

Options

Option	Short	Description
`--port PORT`	`-p`	Dashboard port of the running workflow (required)
`--choice VALUE`	`-c`	Selected gate option value (required)
`--agent NAME`	`-a`	Gate agent name (auto-discovered via `/api/gate-status` when omitted)
`--input TEXT`		Additional free-text input for the gate response
`--token SECRET`		Auth token (also reads from `CONDUCTOR_GATE_TOKEN` env var)

Authentication

If the running workflow was launched with a gate token configured, requests without a matching token are rejected with HTTP 403. Supply the token via --token or set the CONDUCTOR_GATE_TOKEN environment variable (the flag takes precedence when both are present).

Auto-Discovery

When --agent is omitted, conductor gate respond queries GET /api/gate-status on the specified port. If a gate is currently waiting, its agent name is used automatically and printed to the console. If no gate is waiting, the command exits with code 1.

Examples

# Resolve the only waiting gate (agent auto-discovered)
conductor gate respond --port 8080 --choice approve

# Resolve a specific named gate
conductor gate respond -p 8080 -c reject --agent review-gate

# Pass additional free-text input
conductor gate respond -p 8080 -c approve --input "Looks good, ship it"

# Provide auth token via flag
conductor gate respond -p 8080 -c approve --token my-secret

# Provide auth token via environment variable
CONDUCTOR_GATE_TOKEN=my-secret conductor gate respond -p 8080 -c approve

Deprecated alias: conductor gate-respond still works but prints a deprecation warning and will be removed in a future release. Use conductor gate respond instead.

Exit Codes

Code	Meaning
0	Gate resolved successfully
1	Connection error, auth failure, validation error, or no gate waiting

`conductor checkpoint list`

List saved workflow checkpoints (failure and periodic), newest first. Each row shows the workflow name, timestamp, trigger, the agent that was running (or about to run), the error type for failure checkpoints, and the checkpoint file path.

conductor checkpoint list [WORKFLOW]

Arguments

Argument	Description
`WORKFLOW`	Optional workflow YAML path; filters the list to that workflow only

Examples

# List all checkpoints across every workflow
conductor checkpoint list

# List checkpoints for a single workflow
conductor checkpoint list workflow.yaml

Resume a failed run from its latest checkpoint with conductor resume.

Deprecated alias: conductor checkpoints still works but prints a deprecation warning and will be removed in a future release. Use conductor checkpoint list instead.

`conductor validate`

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

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

Errors (validation fails):

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
Stale agent references in templates — {{ old_agent.output.field }} where old_agent doesn't exist
Missing workflow input references — {{ workflow.input.x }} where x isn't declared in input:
Stale references checked across prompt, system_prompt, command, args, working_dir, input_mapping, parallel-group inputs, and workflow output: templates

Warnings (validation passes with notes):

Undeclared dependencies in explicit mode — agent prompt references {{ a.output.val }} but doesn't declare a.output in its input: list

`conductor doctor`

Report provider and environment diagnostics — a safe, read-only health check for your Conductor setup. Answers "is my setup healthy?" without running a workflow: which providers are installed, their stability tier, which credential environment variables are detected, plus Conductor version / update status and configured registries.

conductor doctor [SECTION] [OPTIONS]

SECTION (optional positional) limits output to one of providers, registries, or env. When omitted, all three sections are shown.

Offline by default — no providers are instantiated and no credentials are required. The only default network access is the GitHub-releases update check in the env section (cache-first, short timeout, silent, and skipped when CONDUCTOR_NO_UPDATE_CHECK is set).

Options

Option	Short	Description
`--check`		Instantiate each provider and test its connection via `validate_connection()` (performs network I/O).
`--models`		List each provider's available models (implies `--check`).
`--provider NAME`	`-p`	Scope the providers section to a single provider.
`--json`		Emit machine-readable JSON instead of Rich tables (for CI).

Sections

env — Conductor version, Python version, OS/platform, and update availability.
providers — for each known provider (copilot, claude, claude-agent-sdk, hermes, openai-agents): whether the SDK is installed, the capability tier (stable / experimental), which credential environment variables are present (presence only — values are never printed), and — with --check / --models — connection status and a model count. openai-agents is surfaced as "not yet implemented".
registries — configured workflow registries and which is the default (see conductor registry).

Per-model capabilities (`--models`)

Beyond a model count in the Providers table, --models renders a separate Models detail table per provider with each model's reasoning-effort support and context-window limits:

Column	Description
Model	The model identifier.
Reasoning efforts	`reasoning.effort` levels the model accepts (e.g. `low, medium, high, xhigh`), `none` when the model definitively supports none (e.g. a non-thinking Claude model), or `n/a` when the provider can't determine support.
Default	The model's default reasoning-effort level, or `—` when unknown/not applicable.
Prompt / Output / Context	Maximum prompt (input), output (completion), and total context-window tokens, or `—` when the provider doesn't expose that limit.

Coverage varies by provider — every field degrades independently to n/a / — rather than failing the command:

Copilot reports reasoning-effort levels + default, and prompt/context token limits, from the SDK's per-model metadata (Output is frequently — — the live API does not currently populate it for most models).
Claude derives reasoning-effort support from a static heuristic (Claude 3.7+ / 4.x models support all five levels; older models support none) and reports only Prompt (via the Anthropic API's max_input_tokens) — Output and Context are always — and Default is always — (Anthropic has no per-model default-effort concept).
claude-agent-sdk, hermes, and openai-agents don't implement model enumeration (list_models) at all, so --models shows n/a for them in the Providers table and they get no Models detail table — there is nothing to detail.

In --json, each provider's models field is a list of objects (not plain id strings):

{
  "id": "gpt-5.5",
  "supported_reasoning_efforts": ["low", "medium", "high", "xhigh"],
  "default_reasoning_effort": "medium",
  "max_prompt_tokens": 128000,
  "max_output_tokens": 64000,
  "max_context_window_tokens": 192000
}

Credential detection

Only the presence of credential environment variables is reported — values are never read or printed. Detected variables per provider:

Provider	Environment variables	Requirement
`copilot`	`GITHUB_TOKEN`, `GH_TOKEN`, `COPILOT_PROVIDER_API_KEY`, `COPILOT_PROVIDER_BEARER_TOKEN`, `COPILOT_PROVIDER_RUNTIME_TOKEN`	optional overrides — authenticates via the GitHub/Copilot CLI login on disk
`claude`	`ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`	required (direct Anthropic API)
`claude-agent-sdk`	`ANTHROPIC_API_KEY`	optional override — authenticates via `claude login`
`hermes`	(none — endpoint / API key are passed explicitly)	—
`openai-agents`	(none — not yet implemented)	—

For copilot and claude-agent-sdk, these env vars are optional overrides: both providers authenticate primarily via an on-disk CLI login (the GitHub/Copilot CLI and claude login, respectively), so an all-absent credentials cell for them is expected — not a misconfiguration. Each absent optional variable renders as a neutral ○ (with a short note in the Notes column) rather than the red ✗ used for a genuinely missing required credential. The offline view only ever reports env-var presence, never validity, for any provider — run a live connection probe with --check to confirm a provider is actually ready.

Exit codes

0 — success (the default for offline runs; missing credentials for an optional provider never fail the command).
1 — an invalid SECTION/--provider was given, or --check was set and the scoped provider failed to connect. The scoped provider is the one named by --provider, or copilot (the default) when --provider is omitted.

Examples

# Full offline report (all sections)
conductor doctor

# Just the providers section
conductor doctor providers

# Actually test provider connections (network)
conductor doctor --check

# List available models for a single provider
conductor doctor --models --provider claude

# Machine-readable output for CI
conductor doctor --json

`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 configured registries, or list workflows in a specific registry. For GitHub registries, the per-registry listing also prints a "Latest tags:" footer with up to 5 newest tags.
`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]`	Refresh the cached index for one or all registries. For GitHub registries, the index is re-fetched via a SHA-pinned raw URL that bypasses Fastly's CDN, so updates always reflect the current state of the registry repo.
`show <NAME>`	Show details for a single configured registry: type, source, default status, and (for GitHub registries) a "Latest tags:" footer listing up to 5 newest tags discovered on the registry repo. Use `list <NAME>` to inspect the workflows it contains.

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 of the form <workflow>[@<registry>][#<ref>]. @ selects the registry; # selects a git ref (tag, branch, or commit SHA). Quote the reference in shell commands so # isn't treated as a comment.

# Run from default registry (default-branch HEAD)
conductor run qa-bot

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

# Pin a specific tag
conductor run 'qa-bot@official#v1.2.3'

# Pin the default-branch HEAD or any other branch
conductor run 'qa-bot@official#main'

# Pin a specific commit SHA
conductor run 'qa-bot@official#a1b2c3d'

# Pin a tag in the default registry (empty registry segment)
conductor run 'qa-bot@#v1.2.3'

Path-type registries do not support #<ref> and will reject any reference that includes one.

See design/registry.md for the full design.

Deprecated command aliases

The command surface groups related subcommands under nouns (checkpoint, gate, registry). Two older flat commands are retained as deprecated aliases so existing scripts keep working. Each still runs, but prints a one-line deprecation warning to stderr and forwards to its replacement. They are hidden from --help and are slated for removal in a future release.

Deprecated alias	Use instead
`conductor checkpoints [WORKFLOW]`	`conductor checkpoint list [WORKFLOW]`
`conductor gate-respond [OPTIONS]`	`conductor gate respond [OPTIONS]`

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
`CONDUCTOR_GATE_TOKEN`	Auth token required by `conductor gate respond` (and checked by `POST /api/gate-respond`) when the workflow dashboard is started with a gate token

Exit Codes

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