CLI Reference — OpenCastle

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

npx opencastle <command> [options]

Commands:
  init        Set up OpenCastle in your project
  update      Update framework files (preserves customizations)
  eject       Remove dependency, keep all files standalone
  run         Process a task queue from a spec file autonomously
  dashboard   View agent observability dashboard in your browser
  doctor      Validate your OpenCastle setup

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, and/or OpenCode
Prompts for tech & team tools — pick from 23 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

Runtime

opencastle run

Process a task queue from a spec file autonomously

Reads a YAML task specification file, builds an execution plan with dependency-aware phases, and delegates each task to an AI agent CLI. Tasks in the same phase run in parallel up to the concurrency limit.

Usage

npx opencastle run [options]

Options

Flag	Description
`--file, -f <path>`	Task spec file (default: opencastle.tasks.yml)
`--dry-run`	Show execution plan without running tasks
`--concurrency, -c <n>`	Override max parallel tasks
`--adapter, -a <name>`	Override agent runtime adapter (claude-code, copilot, cursor)
`--report-dir <path>`	Where to write run reports (default: .opencastle/runs)
`--verbose`	Show full agent output
`--help, -h`	Show help

Task spec format

The task spec is a YAML file (opencastle.tasks.yml by default) that defines:

name — run name for reports
adapter — which AI CLI to use (claude-code, copilot, cursor)
concurrency — max parallel tasks (default: 3)
tasks — array of task objects with id, prompt, dependsOn, timeout, etc.

Execution model

Phase-based: Tasks are sorted into phases by dependency graph. Tasks in the same phase run in parallel.
Adapter-based: Each task is executed by the configured AI agent CLI (Claude Code, GitHub Copilot, Cursor).
Reporting: Results are written to the report directory as JSON for post-run analysis.

Adapters

The --adapter flag selects which AI CLI to delegate work to:

Adapter	CLI Required	Install
`claude-code`	`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)

Examples

npx opencastle run

Run the default task spec

npx opencastle run -f tasks/migration.yml

Run a specific task file

npx opencastle run --dry-run

Preview execution plan

npx opencastle run -c 5 -a claude-code

Run with 5 parallel tasks using Claude Code

npx opencastle run --verbose

Show full agent output during execution

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
`--help, -h`	Show help

Data sources

The dashboard reads NDJSON log files from .github/customizations/logs/:

sessions.ndjson — agent session records (task, outcome, duration, files changed)
delegations.ndjson — Team Lead delegation records (agent, model, mechanism)
reviews.ndjson — fast review results (verdict, issues found)
panels.ndjson — panel majority vote results (pass/block count)

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