CLI Overview
Command anatomy of the vibecrafted CLI: management commands, skill launchers, agent modes, uniform flags, and aliases.
Canonical source — docs/public/cli/cli-overview.md
CLI Overview
The vibecrafted CLI has one grammar with two shapes: management commands
(vibecrafted <command>) and skill launchers (vibecrafted <skill> <agent>).
Every launcher dispatches a tracked run for one of the fleet agents —
claude · codex · agy · junie · grok · cursor — and every run leaves a report,
a transcript, and control-plane state you can query afterwards.
Command anatomy
vibecrafted <command> [args]
vibecrafted <skill> <agent> [-p <prompt> | -f <file>]
Examples of both shapes:
vibecrafted doctor # management command
vibecrafted implement codex -p "Ship dark mode" # skill launcher
vibecrafted marbles claude -p "Loop until clean" # skill launcher
The main deck (vibecrafted help) shows the management commands and the ship
cycle. The full reference, including operator surfaces and additional skills,
lives behind vibecrafted help --all. Per-topic help is
vibecrafted help <topic>.
Skill launchers
Skills are workflow launchers. The ship cycle is the canonical order:
scaffold → implement → review → workflow → followup → marbles
→ audit → polarize → dou → hydrate → release
See Workflow launchers for the full catalogue and Lifecycle overview for running all stages as one supervised run.
Uniform skill flags
Every skill launcher accepts the same flag contract:
| Flag | Meaning |
|---|---|
-p, --prompt <text> | Inline prompt |
-f, --file <path.md> | Input file as prompt context |
--repo <path> | Repository to work in, from any directory (--root: legacy) |
--worktree [true|false] | Run in a fresh linked checkout of --repo (clean Git root) |
--permissions <policy> | bypass|auto|accept-edits|read-only, enforced by the agent CLI (default: durable per-agent/global config, else auto) |
--sandbox [true|false] | Agent CLI sandbox on/off; refused before launch when it cannot be enforced |
--model <name> | Agent model override (passed through exactly, e.g. claude-fable-5-1) |
--count <n> | Marbles / Polarize loop count (default: 3) |
--depth <n> | Marbles plan crawl depth (default: 3) |
--session <id> | Session ID for vibecrafted resume / vibecrafted fork |
--verbose is a global option for detailed output. --repo and the legacy
--root go through one selector everywhere: passing both with different
paths is an error, never a silent pick. Model overrides exist for claude
(--model), codex (-m), grok (-m) and cursor (--model); other agents
run their defaults.
cd ~/Downloads # not a Git checkout
vibecrafted workflow claude --model claude-fable-5-1 --worktree true \
--permissions auto --sandbox true \
--repo ~/Projects/app --prompt "Ship it in an isolated, sandboxed checkout"
--permissions and --sandbox are resolved against the installed provider
CLI before launch and refused with a supported alternative when the provider
cannot enforce them — never a silent downgrade. See
Commands → Execution controls
for the per-provider mapping.
Action-first agent modes
The same action-first grammar executes prepared plan files directly:
vibecrafted implement <agent> <plan.md> # execute a plan file
vibecrafted research <agent> <plan.md> # single-agent research mode
vibecrafted review <agent> <plan.md> # review bounded code artifacts
vibecrafted plan <agent> <plan.md> # generate an implementation plan
vibecrafted prompt <agent> <plan.md> # free-form prompt with context
vibecrafted observe <agent> --last # check last agent report/transcript
All actions run through the same engine and produce the same run records. Agent-first commands are rejected with a migration hint.
vc-<skill> shortcuts
Every skill also installs a vc-<skill> shell shortcut, so these are
equivalent:
vibecrafted implement codex -p "Ship the feature"
vc-implement codex -p "Ship the feature"
The shortcut layer is convenience only; it forwards to the same launcher.
Aliases
Silent aliases exist for muscle memory. They work but are not the documented surface:
| Alias | Canonical |
|---|---|
stats | status |
check | doctor |
remove | uninstall |
start | dashboard |
justdo (and vc-justdo) is its own skill — a “take the task and deliver”
posture where the prompt defines the task type. It is not an alias of
implement.
First five minutes
cd ~/projects/my-app
vibecrafted doctor # install health — pass/fail
vibecrafted init claude # orient the agent in this repo
vibecrafted workflow claude --prompt "Plan and implement <task>"
vibecrafted implement codex --prompt "Ship <task>"
vibecrafted status # today's agent activity
From there, follow runs with observe and await, and read the management command reference in Commands.