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

Management Commands

Reference for vibecrafted management commands: init, status, doctor, receipt, settlements, update, resume, fork, version, uninstall, help.

Canonical source — docs/public/cli/commands.md

Management Commands

Management commands operate on the installation, the current repository, and past runs. They launch no workflows themselves — that is the job of the skill launchers.

Reference table

CommandPurpose
vibecrafted init [agent]Orient an agent in this repo
vibecrafted statusToday’s agent activity
vibecrafted doctorInstallation health — pass/fail
vibecrafted receipt [--json]Delivery/runtime receipt (source ↔ installed)
vibecrafted settlements <action>Read-only f/x/n ledger query
vibecrafted updateUpdate to the latest release
vibecrafted resume <agent>Continue a stopped run or a provider session
vibecrafted fork <agent>Branch a provider session into a new one (claude, codex, grok)
vibecrafted resume-session <agent>Continue an exact provider session as a tracked run
vibecrafted versionPrint version
vibecrafted uninstallReverse the install
vibecrafted help [topic|--all]Command deck · full reference

Selecting the repository: --repo

Every repository-aware command takes --repo <path> and works from any working directory, including one that is not inside Git:

cd ~/Downloads
vibecrafted workflow claude --repo ~/Projects/app --prompt "Ship it"
vibecrafted fork claude --run-id work-260908-194325-30219 --repo ~/Projects/app
vibecrafted start --repo ~/Projects/app
vibecrafted resume codex --repo ~/Projects/app --session <provider-uuid>

--root <path> is the legacy spelling with identical semantics. Passing both with different paths is an error (conflicting --repo … and --root …), never a silent pick; a missing path fails with the flag that carried it. Commands that do not need a repository (version, help, doctor, receipt, settlements, fork-source) never require Git to run.

Skill launchers add --worktree [true|false]: the worker runs in a fresh linked checkout of --repo (branch cut/<agent>-<run_id> at the selected HEAD, under ~/.vibecrafted/worktrees/). The selected repository must be a clean Git work-tree root; the launch receipt reports worktree_path, worktree_branch, worktree_baseline_sha and parent_root.

vibecrafted workflow claude --model claude-fable-5-1 --worktree true \
  --repo ~/Projects/app --prompt "Ujednolić polecenie fork"

The Rust cockpit accepts the same selector: vibecrafted tui --repo <path> (voc --repo <path>), with --root as the legacy spelling and the same conflict rule.

Execution controls: --permissions, --sandbox

Skill launchers also take --permissions <bypass|auto|accept-edits|read-only> and --sandbox [true|false]. Both are real execution contracts, resolved against the installed provider CLI before any process starts: the launcher maps a control only where the provider can enforce it, and refuses the launch (exit 2, no run record) with the exact supported alternative otherwise. --permissions auto is never downgraded to bypassPermissions; --sandbox true is never downgraded to an unsandboxed run. Omitting both keeps the historical default (bypass; auto for junie; sandbox left to the provider).

vibecrafted workflow claude --model claude-fable-5-1 --worktree true \
  --permissions auto --sandbox true --repo ~/Projects/app --prompt "Ship it"

--sandbox means the provider’s own command sandbox: the boundary the agent CLI draws around the shell commands it runs. It is not whole-agent or VM isolation. For Claude that boundary is the Bash-tool sandbox (macOS Seatbelt, Linux bubblewrap) around Bash commands and their child processes; file tools, WebFetch and MCP servers run outside it. sandbox_effective reports what the launcher configured through the provider’s supported interface; the launcher does not observe OS enforcement and never says it did.

The launch receipt (--json, the human receipt, meta.json, the launch event) carries execution_controls with permissions_requested / permissions_effective, sandbox_requested / sandbox_effective, the exact provider flags, a boundary line naming what that provider’s sandbox confines, and the evidence line. Provider mapping as probed on 2026-09-08 (read-only --help, binary settings schema and the Claude Code sandbox documentation):

Provider--permissions--sandbox true--sandbox false
claude 2.1.263--permission-mode bypassPermissions|auto|acceptEdits|plan--settings '{"sandbox":{"enabled":true,"failIfUnavailable":true,"allowUnsandboxedCommands":false}}' — the documented hard gate: a missing backend fails the run, no dangerouslyDisableSandbox retry--settings '{"sandbox":{"enabled":false}}'
codex 0.154 (codex exec)bypass → --dangerously-bypass-approvals-and-sandbox; auto → --approve-for-me; read-only → --sandbox read-only; accept-edits refusedbypass → --sandbox workspace-write (bypass flag dropped, approvals never prompted); auto/read-only already sandboxedbypass only; auto/read-only refused (their sandbox enforces the policy)
grok 1.0.21--permission-mode …--sandbox workspace (read-only profile under read-only)--sandbox off
cursor-agent 2026.09.08--force --trust / --trust / --mode ask --trust; accept-edits refused--sandbox enabled (verified against --help)--sandbox disabled
agy 1.1.27--dangerously-skip-permissions / default / --mode accept-edits / --mode plan--sandbox (opt-in terminal restrictions)refused: only an opt-in flag exists and agy keeps persistent terminal-sandbox settings, so “no flag” is not “disabled”; omit --sandbox
junie 26.8.31auto only in headless runsrefused (no sandbox surface)refused
kimi 0.42.0headless bypass uses its never-ask print default; auto/read-only are interactive only; accept-edits refusedrefused (no sandbox surface)refused
copilot 1.0.89-7bypass → --allow-all; headless read-only → --available-tools=read --no-ask-user; auto/accept-edits are interactive onlyrefused (no explicit sandbox control)refused

Copilot headless launches pipe the private prompt to stdin and request JSONL with --output-format json; -p would ignore stdin. The final result.sessionId supplies native resume identity. --model and --reasoning-effort pass through to the CLI. Usage telemetry reads the provider’s session events only when the whole native session belongs to the run; resumed sessions stay unknown rather than inheriting cumulative totals. vibecrafted message delivers to Copilot’s durable run inbox, and vc_launch / vc_run_launch in Vibecrafted MCP accept agent=copilot.

Claude’s --settings document sits at the command-line level: its scalar keys override the same keys in user, project and local settings and keep every key it omits, while managed settings still outrank it. Array keys merge across scopes, so commands listed in an inherited sandbox.excludedCommands keep running outside the sandbox; the receipt says so.

research and marbles run under a supervised runtime that does not carry these controls yet; passing them there is refused, not ignored. The shell skill helpers and the interactive init / operator / partner sessions refuse --sandbox for the same reason.

init

vibecrafted init claude

The interactive first context handoff: loads repository context (history, structural perception, verification) and opens an oriented agent session. Run it once per repository session before dispatching work.

Resume rides along. Init also computes this checkout’s resume payload and carries it into the session — you never have to remember to look. If any run here settled n (needs attention), init names it, says who owns it, and prints the exact command that continues it. Runs the Guardian already owns are reported without a command, because each holds a single automatic attempt that a hand resume would burn. A checkout with nothing unfinished adds nothing to the prompt; an unreadable ledger says so rather than implying “clean”.

The same payload is attached to the init step of every pipeline launch (vibecrafted <skill> <agent>), so a worker opens with unfinished work already in view. Full inventory on demand: vibecrafted settlements list --bucket n --revalidatable.

A declaration opens its workspace. init, operator and partner owe you the oriented agent on a surface you can see. The repository’s own vc-frame session (bound through the workspace catalog, --repo <path> to declare another one) is created detached when absent and reused when live; the agent tab is hung on it first, and only then is your terminal attached. When the command runs with no controlling terminal — an agent tool with pipes for stdio — and no attached frame that the engine confirms as watched, it opens the Vibecrafted terminal on that repository and re-enters there with the same arguments (budget, prompt, file), exactly once. Inherited VC_FRAME_SESSION_NAME / VIBECRAFTED_OPERATOR_SESSION values are checked against the engine: a session that is dead, missing or has no attached client is ambient context, never a target. A terminal launch the host rejects is reported as a failure, never as “launched”.

status

vibecrafted status

Today’s runs at a glance: which agents ran, which runs are live, which delivered reports. The run — not a terminal tab — is the unit of truth.

doctor

vibecrafted doctor

Installation health check with a pass/fail verdict: summary line first, then failures and warnings. Passing checks are reported as a count. Exit code is non-zero when a check fails.

receipt

vibecrafted receipt --json

One delivery/runtime receipt for the fleet tools (vc-frame, vibecrafted, scaffold-doctor, loct, aicx). Each row binds owner/repo → branch → checkout SHA → dirty state → installed SHA → ahead/behind → index generation, and labels the drift:

SOURCE_AHEAD_OF_INSTALLED | INSTALLED_NOT_ON_PATH | UNPUSHED
| DIRTY_BUILD_PROVENANCE | INDEX_STALE | CLEAN

Receipt never uses the process working directory to identify a tool source. When auto-discovery fails, point it explicitly with VIBECRAFTED_SOURCE, VC_FRAME_SOURCE, LOCTREE_SOURCE, AICX_SOURCE, or VIBECRAFTED_FLEET_ROOT.

This is the fastest way to catch the push ≠ install trap: a git checkout can be ahead of the staged tools your daily CLI actually executes. git pull alone does not refresh the installed runtime — vibecrafted update does.

settlements

Read-only query over the settlement ledger — the append-only source of f · x · n (finalized / failed / needs-attention) verdicts:

vibecrafted settlements summary [--json]
vibecrafted settlements list [--bucket f|x|n] [--revalidatable] \
  [--group agent,skill,reason,root] [--limit N] [--json]
vibecrafted settlements inspect <run_id> [--json]

Counters come from the ledger, never from open terminal tabs or bare control-plane completion rows.

update

vibecrafted update

Pulls the latest release and reinstalls, refreshing the staged tools the CLI executes. Verify afterwards with vibecrafted version and vibecrafted receipt.

resume and resume-session

# After stop: continue the control-plane run (new tracked job; the old PGID is dead)
vibecrafted resume claude --run-id work-260816-213657-08420
vibecrafted resume claude --run-id work-260816-213657-08420 --prompt "continue"
vibecrafted resume claude --last

# Provider-native session (Claude/Codex UUID — never a work-* id, never VIBECRAFTED_SESSION_ID)
vibecrafted resume claude --session <provider-uuid> --prompt "Continue the fix"

stop kills the launcher process group. There is no same-process restart. --run-id starts a new tracked job that continues the stopped work: if the run recorded a provider session, that session is resumed natively; otherwise the original prompt is replayed as resume-new-session.

--session takes the provider UUID only. work-… is a control-plane run. 01a00… / VIBECRAFTED_SESSION_ID is the Vibecrafted runtime session, not Claude or Codex.

Bare vibecrafted resume <agent> (optional --repo) opens a new interactive session and attaches an AICX continuity pack. It never native-attaches the last same-agent candidate. --repo (legacy --root) selects the repository from any directory and narrows AICX; it is not a session picker. The catalog in the pack is evidence, not a swipe list.

--repo <path> (or --root <path>) on an interactive resume is a workspace declaration: the agent is resumed inside that repository’s own vc-frame session, bound through the workspace catalog. The session is created when absent and reused when live — never duplicated, and never replaced by whatever session the calling shell happens to be attached to (a stale or foreign VC_FRAME_SESSION_NAME is ambient context, not a target). Entering it follows the caller: an attached client on a watched session is switched onto the workspace, a plain terminal attaches to it, and a caller with neither — no TTY, a stale or unwatched marker — has the Vibecrafted terminal opened on the declared repository, where the resume re-enters with the same native id and absolute root and attaches. It is never downgraded to a headless run and never left with an attach command to type. Other sessions are left untouched.

# From any shell, including one attached to another project's frame:
vibecrafted resume codex --session <provider-uuid> --repo ~/Projects/other-repo
printf '%s' "continue safely" | vibecrafted resume-session codex \
  --agent-session-id <provider-session-id> --prompt-stdin

resume-session continues one exact provider-owned session as a tracked, detached headless run. The prompt comes from -p <text>, -f <path>, or --prompt-stdin (keeps the prompt out of argv). Optional flags: --repo <path> (legacy --root), --model <name>, --json for a machine-readable launch receipt. This command is always headless; it does not pretend to be an interactive session.

fork

vibecrafted fork claude --run-id work-260908-194325-30219 --repo ~/Projects/app
vibecrafted fork claude --session <provider-uuid> --model claude-fable-5-1
vibecrafted fork grok --session <provider-uuid> --placement floating
vibecrafted fork codex --session current --runtime visible
vibecrafted fork codex --session previous --placement floating

fork branches a provider session into a new session and leaves the source untouched. One identity per call:

  • --session <provider-session-id> names the source directly. current and previous (AICX discovery for the caller’s repository) stay available.
  • --run-id <work-…> names a control-plane run; the provider session that run recorded is the source, and its recorded repository is the default --repo. A run that recorded no provider session is refused — the prompt is never replayed and presented as a fork.

The two shapes are never confused: a work-… id in --session or a provider UUID in --run-id fails with the corrected command. Identity resolution and the provider capability verdict are owned by vibecrafted fork-source <agent> (--session | --run-id) [--json], which the deck consults.

Provider coverage (verified on the installed CLIs):

ProviderNative forkvibecrafted fork
codexcodex fork <id> [prompt]supported
claudeclaude --resume <id> --fork-sessionsupported
grokgrok --resume <id> --fork-session (never --restore-code / --worktree)supported
kimikimi fork <id> [-y]supported
copilotnone (--resume <id> continues the same session)refused: use vibecrafted resume copilot --session <id>
cursornone (--resume [chatId] only)refused: vibecrafted resume cursor --session <id> continues the original (a resume, not a fork)
agynone (--conversation <id> only)refused, same hint
junienone (--session-id … --resume only)refused, same hint

Inside a watched vc-frame pane, --runtime visible|terminal opens a pane in the current tab (break-right by default, --placement floating otherwise); in a plain TTY, --runtime terminal execs the provider directly. Anywhere else, fork is a workspace declaration: the source session is resolved first (current / previous read the calling process’s own context), then the repository’s own vc-frame session hosts the fork as a tab and the terminal is attached to it — and when there is no terminal at all (an agent tool with pipes for stdio, a marker whose host is gone) the Vibecrafted terminal is opened on that repository and the fork re-enters there with the exact provider id, absolute --repo, runtime, placement, model, permissions and prompt. The prompt stays interactive. --runtime headless is refused for every provider: codex fork is an interactive TUI, and a headless tracked fork for claude/grok is not wired in this release (resume-session continues the original headlessly, which is a resume, not a fork). --permissions bypass|auto|accept-edits|read-only maps onto each provider’s own permission contract (codex has no accept-edits cell); --model passes through unchanged. fork has no --worktree: a fork reuses the source session’s checkout; use a launcher with --worktree true for an isolated cut.

The pane title is <agent> fork @<owner>/<repo> <source-session-id>.

version, uninstall, help

vibecrafted version        # print version (X.Y.Z+g<shortsha>)
vibecrafted uninstall      # reverse the install
vibecrafted help           # compact command deck
vibecrafted help --all     # full reference
vibecrafted help marbles   # per-topic help

The version’s +g<shortsha> suffix identifies the exact staged build — compare it with your source checkout when diagnosing drift.