DOCS · CLI
ALL DOCS FIG. 15 · DWG VC-015

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:

FlagMeaning
-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:

AliasCanonical
statsstatus
checkdoctor
removeuninstall
startdashboard

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.