CLI Reference — OpenCastle

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

npx opencastle <command> [options]

Commands:
  (none)      Show project status and what to do next
  init        Set up this project (detects your stack and existing config)
  sync        Recompile the generated config for every target
  add         Add an integration, e.g. "add supabase"
  doctor      Diagnose setup problems
  remove      Remove OpenCastle from this project

Experimental:
  convoy      Run multi-step work through the convoy engine

Options:
  --dry-run        Preview changes without writing files
  --yes            Skip confirmation prompts
  --json           Machine-readable output where supported
  --help, -h       Show help for a command
  --version, -v    Show version number

Setup

opencastle (no command)

Show project status and what to run next

Running opencastle with no arguments reports which assistants it compiles for, whether the generated files are current, which assistants are configured in the repo but not being compiled, and the single command that resolves whatever it found. It is the one command worth remembering.

Usage

npx opencastle

Options

Flag	Description
`--json`	Machine-readable output
`--help, -h`	Show help

Why no flags

The tool can see whether a target is missing files, whether sources are newer than what was generated, and whether a run was interrupted. Asking you to restate that on the command line is what produced the old --status, --resume, and --retry-failed flag families. Those are gone; the state is read instead.

Examples

npx opencastle

Status and the next step

npx opencastle --json

Same, for scripts

opencastle init

Set up this project

Reads the repository, proposes a complete setup, and asks once. Detects which assistants already have config, which framework, database, and test runner the project uses, then compiles the config for every assistant it found.

Usage

npx opencastle init [options]

Options

Flag	Description
`--customize`	Choose IDEs and integrations manually instead of accepting detection
`--yes`	Accept the detected setup without the confirmation
`--dry-run`	Preview what would be created without writing anything
`--help, -h`	Show help

What it does

Finds your assistants — any of CLAUDE.md, .cursor/rules, .github/copilot-instructions.md, .windsurfrules, GEMINI.md, AGENTS.md, .codex, or opencode.json makes that assistant a compile target
Scans the stack — frameworks, databases, CMSes, deployment targets, test runners, monorepo tools
Shows the plan — what it found and what it will write
Asks once — then compiles agents, skills, instructions, and MCP config for each target
Leaves your files alone — existing config is never overwritten, and the summary names what it skipped

If you would rather choose

--customize restores the full selection: an IDE picker followed by a screen per plugin category. Most people do not need it — detection is pre-checked from the same signals you would be confirming by hand.

Examples

npx opencastle init

Detect, show the plan, confirm once

npx opencastle init --yes

No prompts, for CI or scripted setup

npx opencastle init --customize

Pick IDEs and integrations by hand

Lifecycle

opencastle sync

Recompile every target from source

Compiles the framework sources into each configured assistant format, preserving everything under .opencastle/. Run it after upgrading the package, or when opencastle reports that generated files are older than their sources.

Usage

npx opencastle sync [options]

Options

Flag	Description
`--dry-run`	Preview what would change
`--force`	Sync even when versions match
`--reconfigure`	Re-run IDE and integration selection
`--help, -h`	Show help

What is preserved

Your customizations in .opencastle/ are never overwritten. Framework directories are regenerated wholesale so renamed or removed sources do not leave stale files behind.

Previously called update

opencastle update still works as an alias. The operation is a compile-and-sync rather than a version bump, so the name follows what it does.

Examples

npx opencastle sync

Recompile all targets

npx opencastle sync --dry-run

See what would change

opencastle add

Adopt an integration and recompile

Adds one or more packs — a framework, database, CMS, deployment target, or team tool — to the project and recompiles so its skills and MCP configuration reach every target.

Usage

npx opencastle add <pack>...

Options

Flag	Description
`--list`	Show every available pack
`--dry-run`	Preview without writing
`--help, -h`	Show help

Why this exists

Adopting a tool after setup used to mean re-running the whole selection. This edits the stored stack and recompiles, so it is one command.

Examples

npx opencastle add supabase

Add one integration

npx opencastle add nextjs vercel sentry

Add several at once

npx opencastle add --list

See what is available

opencastle remove

Remove OpenCastle from this project

Asks whether to keep the generated files — making them standalone so you can uninstall the package — or delete everything it created. Always previews before touching anything.

Usage

npx opencastle remove [options]

Options

Flag	Description
`--keep-files`	Keep generated files; drop only the manifest
`--all`	Delete every generated file
`--dry-run`	Preview without changing anything
`--yes`	Skip the confirmation
`--help, -h`	Show help

Replaces eject and destroy

Those two names gave no hint which one deleted your files. This asks, and the flags spell out the answer when you already know it: --keep-files is the old eject, --all is the old destroy.

Examples

npx opencastle remove

Ask, then remove

npx opencastle remove --keep-files

Make the files standalone

npx opencastle remove --all --dry-run

See exactly what a full delete would remove

Runtime

opencastle convoy

Experimental: plan and run multi-step work

Runs long multi-step work in dependency order across isolated git worktrees, with SQLite persistence so an interrupted run resumes rather than restarting. Give it a task description and it plans, executes, and runs your gates.

Usage

npx opencastle convoy [task] [options]

Options

Flag	Description
`--dry-run`	Plan only; do not execute
`--verbose`	Stream agent output
`--json`	Machine-readable status
`--help, -h`	Show help

Subcommands

opencastle convoy — where the last run got to, and the verb that fits its state
opencastle convoy "<task>" — plan and execute a task
opencastle convoy resume — continue an interrupted run
opencastle convoy retry — re-run only the failed tasks
opencastle convoy plan --prd <path> — resume from a PRD the planner wrote earlier
opencastle convoy run --file <spec> — execute a spec you wrote by hand
opencastle convoy dashboard — open the run viewer

Experimental

This namespace may change or be removed. The compiler does not depend on it. Native background and cloud agents now cover much of what it was built for, so treat it as a research surface rather than a stable one.

Examples

npx opencastle convoy "Add user reviews to the place detail page"

Plan and run

npx opencastle convoy

Status of the last run

npx opencastle convoy resume

Continue after an interruption

Diagnostics

opencastle doctor

Diagnose setup problems

Checks the manifest, per-assistant generated files, the skill matrix, MCP configuration, and required environment variables, and pairs each finding with the command that fixes it.

Usage

npx opencastle doctor [options]

Options

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

When to run it

After upgrading, after a merge that touched generated files, or whenever an assistant does not seem to be picking up the config. For a quick "is anything stale" answer, plain opencastle is faster.

Examples

npx opencastle doctor

Run all checks

Exit codes

0All checks passed (may have warnings)

1One or more checks failed