CLI Reference — OpenCastle

All commands are run via npx opencastle <command>. Every command supports --help for quick reference.

npx opencastle <command> [options]

Project Commands:
  init        Set up OpenCastle in your project
  update      Update framework files (preserves customizations)
  eject       Remove dependency, keep all files standalone
  destroy     Remove ALL OpenCastle files (reverse of init)
  doctor      Validate your OpenCastle setup

Convoy Commands:
  start        Go from idea to convoy spec in one command (recommended)
  plan        Run a single prompt template step
  validate    Validate a convoy YAML spec file
  run         Run convoy specs — deterministic, crash-recoverable agent orchestration
  dispute     Manage convoy dispute resolution

Observability:
  dashboard   View agent observability dashboard in your browser
  agents      Manage persistent agent identities
  baselines   Manage visual regression baselines
  log         Append a structured event to the observability log
  lesson      Append a structured lesson to LESSONS-LEARNED.md

Global options:
  --help, -h       Show help
  --version, -v    Show version number

Setup

opencastle init

Set up OpenCastle in your project

Interactive setup wizard that scans your repository, detects your tech stack, and generates all configuration files — agent definitions, skills, instruction files, MCP configs, and IDE-specific settings.

Usage

npx opencastle init [options]

Options

Flag	Description
`--dry-run`	Preview what files would be created without writing anything
`--help, -h`	Show help

What it does

Scans your repo — detects frameworks (Next.js, Astro), databases (Supabase, Prisma), monorepo tools (NX, Turborepo), deployment targets, and more
Prompts for IDEs — select VS Code, Cursor, Claude Code, OpenCode, Windsurf, Codex, and/or Antigravity
Prompts for tech & team tools — pick from 25 plugins (CMS, database, testing, notifications, etc.)
Generates files — instruction files, agent definitions, skills, MCP configs, skill matrix, and .opencastle.json manifest
Updates .gitignore — adds entries for framework-managed files
Creates .env template — if any selected plugins require API keys, offers to create a .env with placeholders

Re-initialization

Running init again on an existing installation will prompt you to re-initialize. It cleans up old framework files before writing new ones, but preserves your customization files.

Examples

npx opencastle init

Interactive setup

npx opencastle init --dry-run

Preview without writing files

Lifecycle

opencastle update

Update framework files while preserving customizations

Upgrades OpenCastle framework files to the latest version. Your customization files — agent prompts, lessons learned, known issues — are never touched. Also supports reconfiguring your tech stack without a full re-init.

Usage

npx opencastle update [options]

Options

Flag	Description
`--dry-run`	Preview changes without writing files
`--force`	Force update even if versions match
`--reconfigure`	Change tech/team tool selections without waiting for a version bump
`--help, -h`	Show help

How updates work

Framework files (instructions, agent definitions, skills, workflow templates) are overwritten with the latest versions
Customization files (lessons learned, known issues, project config, session logs) are preserved
Skill matrix is updated when stack changes — new plugin skills are added, removed plugins are cleaned up
MCP configs are rebuilt when the tool selection changes

Reconfigure mode

Use --reconfigure to add or remove tools without waiting for a new OpenCastle release. This re-shows the tech/team tool selection prompts and updates skill matrix + MCP configs accordingly.

Examples

npx opencastle update

Update to latest version

npx opencastle update --reconfigure

Change stack selections

npx opencastle update --dry-run

Preview what would change

npx opencastle update --force

Re-apply even if already up to date

opencastle eject

Remove dependency, keep all files standalone

Removes the OpenCastle manifest (.opencastle.json) while keeping all generated files in place. After ejecting, the files become standalone and you can uninstall the opencastle package.

Usage

npx opencastle eject [options]

Options

Flag	Description
`--dry-run`	Preview without removing the manifest
`--help, -h`	Show help

What stays

All instruction files (.github/instructions/)
All agent definitions and skills
All customization files
All MCP configs
All IDE-specific configs

What gets removed

.opencastle.json — the manifest file that tracks what OpenCastle manages

After ejecting, update and doctor will no longer work since they depend on the manifest. You own the files outright.

Examples

npx opencastle eject

Eject and keep all files

npx opencastle eject --dry-run

Preview the eject process

opencastle destroy

Remove ALL OpenCastle files (reverse of init)

Completely removes every file and directory that OpenCastle created — framework files, customization files, the .opencastle/ directory, and the managed block in .gitignore. Use this when you want a clean slate.

Usage

npx opencastle destroy [options]

Options

Flag	Description
`--dry-run`	Preview what would be removed without deleting anything
`--help, -h`	Show help

What gets removed

All framework-managed paths (instructions, agents, skills, workflows)
All customizable paths (lessons, known issues, project config, logs)
The .opencastle/ directory (including the manifest)
Legacy .opencastle.json manifest (if present)
The OpenCastle managed block in .gitignore

Difference from eject

eject keeps all generated files and only removes the manifest — you own the files outright. destroy removes everything, restoring the project to its pre-OpenCastle state.

Examples

npx opencastle destroy

Remove all OpenCastle files

npx opencastle destroy --dry-run

Preview what would be removed

Runtime

opencastle start

Go from idea to convoy spec in one command

The easiest way to create a convoy spec. Describe your goal in plain text and the start command generates a PRD, validates it (with auto-fix), assesses complexity, generates a task plan, validates the convoy spec, and auto-fixes any issues — all in one command.

Usage

npx opencastle start [options]

Options

Flag	Description
`--text, -t <text>`	Your feature or task description in plain text (required, unless --prd is set)
`--prd <path>`	Skip PRD generation — use an existing PRD file as input
`--output-prd <path>`	Override output path for the generated PRD
`--output-spec <path>`	Override output path for the generated convoy spec
`--complexity <path>`	Skip complexity assessment — use an existing complexity assessment file
`--adapter, -a <name>`	Override agent runtime adapter (claude, copilot, cursor, opencode, windsurf, codex, antigravity)
`--verbose`	Show full agent output for each step
`--dry-run`	Generate and print the PRD prompt only, then stop
`--skip-validation`	Skip PRD and convoy validation (steps 2, 3, 6, 7)
`--help, -h`	Show help

Start command steps

Generate PRD — converts your text into a structured Product Requirements Document
Validate PRD — checks the PRD for completeness and correctness
Fix PRD — if validation fails, attempts to auto-fix the PRD (up to 2 retries)
Assess complexity — analyzes the PRD to determine whether to use a single convoy or a chain of convoys for complex multi-domain projects
Generate task plan — converts the PRD into a structured task plan (JSON), then builds a .convoy.yml spec with tasks, dependencies, file partitions, and gates
Validate convoy spec — runs both schema validation and semantic validation against the spec
Fix convoy spec — if validation fails, applies patch-based fixes automatically (up to 2 retries)

After the start command completes

The start command outputs two files:

A PRD (.prd.md) in .opencastle/prds/
A convoy spec (.convoy.yml) in .opencastle/convoys/

Review the generated spec, then execute it:

npx opencastle run -f .opencastle/convoys/your-spec.convoy.yml

Complexity assessment and chain strategy

After validating the PRD, the start command assesses the project's complexity to decide the optimal execution strategy:

Single convoy (default) — all tasks run in one .convoy.yml spec. Used for low and medium complexity projects.
Chain strategy — for high-complexity, multi-domain projects, the start command splits the work into multiple convoy groups (e.g., database setup → API integration → frontend/testing). Each group gets its own .convoy.yml file, plus a master pipeline spec that chains them with depends_on_convoy dependencies.

Chain convoy files and the master pipeline spec are written to .opencastle/convoys/. Use --complexity <path> to skip the assessment and provide your own complexity file.

Examples

npx opencastle start -t "Add user authentication with login and signup pages"

Generate a convoy spec from a text description

npx opencastle start -t "Fix the broken search feature" --adapter claude

Use a specific adapter

npx opencastle start --prd existing-prd.md

Skip PRD generation, use an existing PRD

npx opencastle start -t "Refactor the API layer" --skip-validation

Skip validation steps for faster generation

npx opencastle start -t "Build a contact form" --dry-run

Preview the assembled prompt without executing

opencastle run

Run convoy specs — deterministic, crash-recoverable agent orchestration

Reads a YAML convoy spec (convoy.yml), builds a dependency-aware execution plan, and runs tasks in isolated git worktrees. Each worker operates in its own worktree with SQLite-backed state persistence. Legacy opencastle.tasks.yml specs without version: 1 still work via the legacy executor.

Usage

npx opencastle run [options]

Options

Flag	Description
`--file, -f <path>`	Convoy spec file (default: convoy.yml if present)
`--formula <path>`	Use a formula template (alternative to --file)
`--set key=value`	Set a formula variable (repeatable)
`--dry-run`	Show execution plan without running tasks
`--concurrency, -c <n>`	Override max parallel tasks
`--adapter, -a <name>`	Override agent runtime adapter (claude, copilot, cursor, opencode, windsurf, codex, antigravity)
`--resume`	Resume the last interrupted convoy from SQLite state
`--retry-failed [task-id]`	Retry failed/gate-failed/timed-out tasks (optionally a specific task)
`--status`	Print convoy state summary from SQLite (branch, task breakdown)
`--dlq-list`	List dead letter queue entries
`--dlq-resolve <id>`	Resolve a DLQ entry (requires --resolution)
`--dlq-retry <id>`	Reset a DLQ task to pending for retry
`--convoy <id>`	Filter by convoy ID (used with --dlq-list)
`--resolution <text>`	Resolution text (used with --dlq-resolve)
`--report-dir <path>`	Where to write run reports (default: .opencastle/runs)
`--verbose`	Show full agent output
`--watch`	Keep running, re-triggering on file changes, cron, or git push
`--watch-config <path>`	Path to watch configuration file (overrides spec watch config)
`--clear-scratchpad`	Clear scratchpad data at watch start
`--help, -h`	Show help

Convoy spec format

The convoy spec is a YAML file (convoy.yml by default, falling back to opencastle.tasks.yml) that supports:

version: 1 — enables the Convoy Engine with full feature set
name — convoy name for reports and state tracking
adapter — which AI CLI to use (claude, copilot, cursor, opencode, or auto)
concurrency — max parallel workers (default: 3)
branch — base branch for worktree isolation
defaults — default timeout, model, and max_retries for all tasks
tasks — array of task objects with id, prompt, dependsOn, per-task adapter, etc.
gates — validation gates that run between phases

Legacy specs without version: 1 are still supported via the legacy executor for backward compatibility.

Execution model

Convoy Engine: version: 1 specs use the Convoy Engine — a deterministic orchestrator with phase-based execution and crash recovery.
SQLite persistence: State is stored in WAL-mode SQLite, enabling reliable crash recovery via --resume.
Worktree isolation: Each worker runs in its own git worktree, preventing cross-task interference.
Health monitoring: A background health monitor detects stuck and zombie workers and recovers automatically.
Merge queue: Completed worktrees are merged back to the base branch via a serialized merge queue.
Validation gates: Gates run between phases and can block promotion if checks fail.

Adapters

The --adapter flag selects which AI CLI to delegate work to. Convoys also support per-task adapter overrides and adapter: auto for auto-detection:

Adapter	CLI Required	Install
`claude`	`claude`	`npm i -g @anthropic-ai/claude-code`
`copilot`	`copilot`	Ships with GitHub Copilot CLI
`cursor`	`cursor`	Ships with Cursor editor (Install CLI from menu)
`opencode`	`opencode`	See opencode.ai

Examples

npx opencastle run

Run the default convoy spec

npx opencastle run -f auth.convoy.yml

Run a specific convoy spec

npx opencastle run --dry-run

Preview execution plan

npx opencastle run --resume

Resume last interrupted convoy

npx opencastle run --status

Check convoy state

npx opencastle run -c 5 -a claude

Run with 5 parallel tasks using Claude Code

opencastle plan

Run a single prompt template step

Lower-level command that runs a single prompt template step via an AI adapter. Use start instead for the full automated workflow. The plan command is useful when you want to run individual steps (generate a PRD, generate a convoy spec, validate, or fix) with full control over inputs and outputs.

Usage

npx opencastle plan [options]

Options

Flag	Description
`--file, -f <path>`	Path to a text file (fills the {{goal}} placeholder in the template)
`--text, -t <text>`	Inline text to use as {{goal}} (alternative to --file)
`--template <name>`	Prompt template to use (default: generate-convoy). Built-in: generate-prd, validate-prd, fix-prd, assess-complexity, generate-convoy, validate-convoy, fix-convoy
`--context <path>`	Path to an additional context file (fills {{context}})
`--context-text <text>`	Inline text to fill {{context}} (alternative to --context)
`--output, -o <path>`	Output path for the generated file
`--adapter, -a <name>`	Override agent runtime adapter (claude, copilot, cursor, opencode)
`--verbose`	Show full agent output
`--dry-run`	Print the assembled prompt without executing
`--help, -h`	Show help

Built-in templates

Template	Description	Output
`generate-prd`	Write a PRD from a feature prompt	`.prd.md`
`validate-prd`	Check a PRD for completeness	VALID / INVALID verdict
`fix-prd`	Fix validation errors in a PRD	`.prd.md`
`assess-complexity`	Assess PRD complexity for single vs chain strategy	JSON
`generate-convoy`	Generate a convoy spec from a PRD (default)	`.convoy.yml`
`validate-convoy`	Check a convoy spec for correctness	VALID / INVALID verdict
`fix-convoy`	Fix validation errors in a convoy spec	`.convoy.yml`

How it works

Loads the template — reads the prompt template specified by --template
Fills placeholders — substitutes {{goal}} from --file or --text, and {{context}} from --context or --context-text
Runs the AI adapter — sends the assembled prompt to the detected (or specified) AI CLI
Extracts output — parses the response and writes to .opencastle/convoys/ or the path specified by --output

Examples

npx opencastle plan -t "Add user reviews" --template generate-prd

Generate a PRD from inline text

npx opencastle plan -f my-prd.md

Generate a convoy spec from a PRD file (default template)

npx opencastle plan -f spec.convoy.yml --template validate-convoy

Validate an existing convoy spec

npx opencastle plan -f task.txt --context architecture.md

Include additional context

npx opencastle plan -t "Fix the auth bug" --dry-run

Preview the assembled prompt

opencastle validate

Validate a convoy YAML spec file

Validates a convoy spec file against the schema without executing it. Checks for required fields, valid task IDs, dependency cycles, file partition conflicts, and other structural issues.

Usage

npx opencastle validate <file>

Options

Flag	Description
`<file>`	Path to the convoy YAML spec file (required)
`--help, -h`	Show help

What it checks

YAML syntax is valid
Required fields are present (name, version, tasks)
Each task has id and prompt
depends_on references point to existing task IDs
No dependency cycles exist
File partitions don't conflict between parallel tasks

Examples

npx opencastle validate convoy.yml

Validate a convoy spec

npx opencastle validate .opencastle/convoys/auth.convoy.yml

Validate a generated spec

opencastle dashboard

View agent observability dashboard in your browser

Starts a local HTTP server that serves the OpenCastle dashboard — a visual overview of agent sessions, delegations, reviews, and panel votes from your project's NDJSON log files.

Usage

npx opencastle dashboard [options]

Options

Flag	Description
`--port <number>`	Port to listen on (default: 4300, auto-increments if busy)
`--no-open`	Don't auto-open the browser
`--seed`	Show demo data instead of project logs
`--convoy <id>`	Filter dashboard to a specific convoy
`--help, -h`	Show help

Data sources

The dashboard reads data from two locations:

.opencastle/logs/ (primary) — events.ndjson (unified event log with sessions, delegations, reviews, panels), convoys.ndjson, pipelines.ndjson
.opencastle/convoy.db — SQLite database with convoy execution state, task results, and token usage

If no log files exist, the dashboard shows empty charts. Use --seed to preview with demo data.

Auto-port

If port 4300 is already in use, the dashboard automatically tries the next port (4301, 4302, etc.) up to 10 attempts.

Examples

npx opencastle dashboard

Start dashboard and open browser

npx opencastle dashboard --seed

Preview with demo data

npx opencastle dashboard --port 8080

Start on a custom port

npx opencastle dashboard --no-open

Start without opening browser

Diagnostics

opencastle doctor

Validate your OpenCastle setup

Runs a comprehensive health check on your OpenCastle installation. Verifies the manifest, instruction files, agent definitions, skills, logs, IDE configs, MCP configs, and environment variables.

Usage

npx opencastle doctor

Options

Flag	Description
`--help, -h`	Show help

Examples

npx opencastle doctor

Run all health checks

Exit codes

0All checks passed (may have warnings)

1One or more checks failed