CLI

Bootstrap

vibecompass init --guided

Guided init detects the current Git repo when it can, asks a friendly setup-goal question, scaffolds workflow files, and can chain straight into the first builder session. If you run it inside a subfolder of a repo that already has VibeCompass, guided init walks up and offers to reuse that existing memory root instead of creating a duplicate one in the wrong place.

Without --guided, name everything up front: handy for scripts, or for the same setup on several machines. Hosted sync stays off until you run login. Init can also store close-session defaults in project.yaml, such as a Git publish step and its remote (--close-session-git-publish, --close-session-git-remote).

npx -y @vibecompass/vibecompass@latest init --guided

# Or skip the prompts. This folder isn't a Git repo, so it is a local source;
# for a Git repo, use --repo app=<git-remote> instead.
npx -y @vibecompass/vibecompass@latest init \
  --root .compass \
  --name "Acme Platform" \
  --mode local-primary \
  --repo-local app=.

Which version?

vibecompass version

Prints the package version, such as 0.17.5. vibecompass --version does the same. Compare it with the newest release on the Upgrade page.

See what's new

# The version your global install runs
vibecompass version

# The newest published release
npx -y @vibecompass/vibecompass@latest --version

Check in

vibecompass status

Read-only health check that points you at the safest next command. Full upgrade and compatibility-warning story lives on the Upgrade page.

See Upgrade for the full walkthrough

npx -y @vibecompass/vibecompass@latest status --root .compass
npx -y @vibecompass/vibecompass@latest status --root .compass --json

Recommended: add hosting

vibecompass login

The easiest way to connect a local .compass folder to the hosted app. It prints a short code and opens vibecompass.dev; you log in, confirm the code, and pick the project. The package receives a sync token, stores it in your OS keychain (or a private file under ~/.config/vibecompass), and writes only the hosted URL, project id, and env-var name to project.yaml. Nothing to copy, nothing to paste into chat, and it keeps working in every new terminal and in agents launched from a desktop app.

Run it again any time to sign in from another machine; each machine gets its own token, listed on the project's Setup page where you can revoke it. Already have a hosted project? Add --project-id <id> so the approval page pre-selects it.

# From the folder that contains .compass:
npx -y @vibecompass/vibecompass@latest login --root .compass

# Your browser opens (or a link is printed). Confirm the code, pick the project, done.
# Then push your local baseline:
npx -y @vibecompass/vibecompass@latest push --root .compass

# See where your token lives (never the value):
npx -y @vibecompass/vibecompass@latest sync-credential list --root .compass

Advanced: CI and scripts

vibecompass connect-hosted

Adds the non-secret hosted binding to project.yaml and, on a normal terminal, asks for the sync token at a hidden prompt and stores it in your OS keychain or ~/.config/vibecompass. Create the token on the project's Setup page (it is shown once). For CI, keep it in a secret named VIBECOMPASS_SYNC_TOKEN: the environment variable always wins over the stored token, so runners need nothing else. Push once so hosted VibeCompass has the local baseline before hosted docs-review creates proposals.

If more than one local root can push to the same hosted project, run vibecompass pull-preview before pushing from a different machine or checkout. If the hosted baseline moved ahead, push will stop with a rebase warning instead of overwriting newer hosted state.

# Website path:
# Log in -> Connect local project -> Setup -> Create sync token (shown once)

npx -y @vibecompass/vibecompass@latest connect-hosted \
  --root .compass \
  --sync-api-url https://vibecompass.dev \
  --sync-project-id <project-id> \
  --sync-credential-env-var VIBECOMPASS_SYNC_TOKEN
# -> "Paste the sync token from the dashboard (input hidden)"

# CI or scripts: pipe the token in, or just set VIBECOMPASS_SYNC_TOKEN in the environment
printf '%s' "$VIBECOMPASS_SYNC_TOKEN" | npx -y @vibecompass/vibecompass@latest connect-hosted \
  --root .compass --sync-api-url https://vibecompass.dev --sync-project-id <project-id> \
  --sync-credential-env-var VIBECOMPASS_SYNC_TOKEN --token-stdin

npx -y @vibecompass/vibecompass@latest pull-preview --root .compass
npx -y @vibecompass/vibecompass@latest push --root .compass

Advanced: stored tokens

vibecompass sync-credential

login stores your sync token for you, so most people never need this. list shows which tokens this machine keeps and where, never the token itself. set stores a token you created on the Setup page: it asks for it at a hidden prompt, reads it with --token-stdin, or copies the value already in the project's environment variable with --from-env. remove forgets this project's token.

Add --sync-target <name> for a named target, or --api-url <url> --project-id <id> to reach a hosted project from a folder that isn't connected to it. --credential-store keychain or file picks where the token is kept; by default it prefers your OS keychain. Lost a token? Run login again, or create a new one on Setup and revoke the old one there.

npx -y @vibecompass/vibecompass@latest sync-credential list --root .compass
npx -y @vibecompass/vibecompass@latest sync-credential set --root .compass      # hidden prompt
npx -y @vibecompass/vibecompass@latest sync-credential remove --root .compass

More than one environment

vibecompass sync-target

Most people only ever need one hosted binding and can skip this. But if your project syncs to two places — say a local dev server and vibecompass.dev — give each one a name with connect-hosted --target <name> instead of rebinding back and forth. The first named target becomes your default. After that, sync-target shows your targets and switches the default, and any sync command takes --sync-target <name> for a one-off against the other environment.

Each target keeps its own stored token (keyed by hosted URL and project id), its own override env var, and its own sync history, so pushing to dev never confuses what production thinks your latest version is. Sign in per target with login --sync-target <name>. Already have a regular (unnamed) binding? Add it as your first named target using the same URL and project id — your sync history carries over automatically.

# name your environments once
npx -y @vibecompass/vibecompass@latest connect-hosted --root .compass --target dev \
  --sync-api-url http://localhost:3000 --sync-project-id <dev-project-id> \
  --sync-credential-env-var VIBECOMPASS_SYNC_TOKEN
npx -y @vibecompass/vibecompass@latest connect-hosted --root .compass --target prod \
  --sync-api-url https://vibecompass.dev --sync-project-id <prod-project-id> \
  --sync-credential-env-var VIBECOMPASS_SYNC_TOKEN_PROD

# see your targets (* marks the default)
npx -y @vibecompass/vibecompass@latest sync-target --root .compass

# one-off push to production
npx -y @vibecompass/vibecompass@latest push --root .compass --sync-target prod

# or make production the default for a while
npx -y @vibecompass/vibecompass@latest sync-target prod --root .compass

Move memory between local and hosted

vibecompass push / pull-preview / pull-export / apply-export

push sends your local project memory to the hosted dashboard. pull-preview shows hosted proposals and remote state before anything touches your files. pull-export downloads accepted proposal content, and apply-export writes that exported bundle into your local .compass root.

Most vibe coders only need push at first. Use the pull commands when the dashboard or hosted docs-review has proposals you intentionally want to bring back into local files.

# Update the hosted dashboard from local files.
npx -y @vibecompass/vibecompass@latest push --root .compass

# Preview hosted proposals before touching local files.
npx -y @vibecompass/vibecompass@latest pull-preview --root .compass

# Bring back accepted proposal content on purpose.
npx -y @vibecompass/vibecompass@latest pull-export --root .compass --proposal <proposal-id>
npx -y @vibecompass/vibecompass@latest apply-export --root .compass

Change your source of truth

vibecompass promote-hosted / demote-hosted

Your project memory has one source of truth at a time: your local files (local-primary) or the hosted app (hosted-only). promote-hosted hands the crown to the hosted app; demote-hosted hands it back to your local files. Both run a safe two-step handoff — it pushes a fresh baseline, tells you exactly what carries over, then flips the local and hosted records together so they never disagree. If anything interrupts it, re-run with --resume to finish or --abort to back out. After promoting, your old local folder becomes a read-only copy so you can't accidentally edit a stale version.

Never hand-edit the mode: line in project.yaml — mode lives in two places (your files and the hosted project) and these commands are what keep them in sync. Promoting is reversible: demote-hosted brings canonical control back to a local root.

# Make the hosted app your source of truth (run from your project root)
npx -y @vibecompass/vibecompass@latest promote-hosted --root .compass

# Interrupted? Finish it, or back it out:
npx -y @vibecompass/vibecompass@latest promote-hosted --root .compass --resume
npx -y @vibecompass/vibecompass@latest promote-hosted --root .compass --abort

# Hand canonical control back to local files (rebuild the folder with bootstrap first)
npx -y @vibecompass/vibecompass@latest demote-hosted --root .compass

Get your memory out

vibecompass bootstrap

Download the bootstrap bundle from your project's Setup page ("Export project memory"), then bootstrap rebuilds a complete local .compass folder from it — every document, exactly as the hosted app has it. It checks each file against its fingerprint before writing anything, so a corrupted download fails safely instead of leaving you half a project. Your memory is never locked inside the hosted app.

Moving a hosted-only project fully back to local? Follow bootstrap with connect-hosted and then demote-hosted — the Setup page prints the exact copy-paste sequence with your project's values already filled in.

# Download the bundle from Setup -> Export project memory, then:
npx -y @vibecompass/vibecompass@latest bootstrap --bundle <downloaded-bundle.json> --root .compass

Second machine or fresh clone

vibecompass sync-adopt

Your local root remembers where it left off with the hosted app in a small state file that isn't committed to Git. On a fresh clone or a second computer that file is missing, so push stops with a rebase warning instead of risking a clobber of hosted work. sync-adopt re-points this machine at the current hosted version — after showing you any differences first — so your next push just works.

It always previews divergence before adopting. If there are pending proposals or conflicts it stops and asks you to look; add --accept-divergence once you've reviewed and still want to adopt the hosted head.

npx -y @vibecompass/vibecompass@latest sync-adopt --root .compass

# after reviewing pending proposals/conflicts, adopt anyway:
npx -y @vibecompass/vibecompass@latest sync-adopt --root .compass --accept-divergence

Open a lane

vibecompass start-session

Creates the lane-local scratch files (session.yaml, wip.md, handoff.md), records the lane in the active-sessions index, and refreshes the current-lane pointer plus generated agent files. --id is required: a short lowercase name for the workstream, such as billing-plans. Generic names such as default or new are rejected.

Optional overlap-warning flags: add --feature, --repo, --claim, --architecture-doc, or --decision-domain-file only when more than one active lane could touch the same feature, repo, path, doc, or decision file. To give the lane its own Git branch, add --branch <name> --repo <id>; add --worktree for a separate checkout of each repo (see Worktrees and ports on the Protocol page). If you turned on the session brief, it also writes the lane's brief.md; add --no-brief to skip that once. If you didn't, the output says Brief: off (opt-in; …), and that's expected.

npx -y @vibecompass/vibecompass@latest start-session \
  --id billing-plans \
  --working-on "Wire Stripe checkout into onboarding"

# Its own branch, in its own worktree of the app repo:
npx -y @vibecompass/vibecompass@latest start-session \
  --id billing-plans \
  --working-on "Wire Stripe checkout into onboarding" \
  --branch feature/billing-plans --repo app --worktree

# Session brief turned on, but you don't want one for this lane right now:
npx -y @vibecompass/vibecompass@latest start-session \
  --id billing-plans \
  --working-on "Wire Stripe checkout into onboarding" \
  --no-brief

See active lanes

vibecompass list-sessions

Lists every open lane: what it is working on, when it opened, how many times it has been resumed, its branch or worktree, its dev-server port, and the last line of its log. The lane the tools last used is marked as a hint. Add --json when a script or an AI needs the same inventory as data.

npx -y @vibecompass/vibecompass@latest list-sessions
npx -y @vibecompass/vibecompass@latest list-sessions --json

Pick up where you left off

vibecompass continue-session

Resumes an open lane instead of opening a duplicate. The lane keeps its opening date and session number; the command adds a dated Resumed line to wip.md, bumps a resume counter in session.yaml, points the tools at the lane, and prints the files to read next plus any staleness warnings (new decisions since the lane opened, newer session notes that touch its scope). With one open lane you can omit the id. With two or more it stops and prints the lane list so you choose on purpose.

start-session --id <existing-lane> refuses and points here. Add --working-on "..." to refresh the lane's summary when its scope has drifted, or --json for the resume result as data. With the session brief turned on, resuming keeps an up-to-date brief.md and rebuilds one that is missing or stale; --no-brief leaves it as it is.

# One open lane: no id needed
npx -y @vibecompass/vibecompass@latest continue-session

# Several open lanes: name the one you mean
npx -y @vibecompass/vibecompass@latest continue-session billing-plans

# Resume and refresh the summary at the same time
npx -y @vibecompass/vibecompass@latest continue-session billing-plans --working-on "Stripe checkout, phase 2"

# Resume without touching the lane's brief.md
npx -y @vibecompass/vibecompass@latest continue-session billing-plans --no-brief

Change lanes

vibecompass switch-session

Moves the current-lane pointer and re-syncs CLAUDE.md and the other generated agent files so the next AI session loads the selected lane's context. It records no resume; when you are actually sitting down to work on a lane, continue-session is the better fit.

npx -y @vibecompass/vibecompass@latest switch-session billing-plans

One port per lane

vibecompass lane-env

Every lane gets its own port and temp folder when it opens, so two lanes running side by side never fight over the same port. lane-env prints them as shell exports: PORT and TMPDIR, which most dev servers and build tools already read, plus VIBECOMPASS_LANE_PORT, VIBECOMPASS_LANE_TMPDIR, and VIBECOMPASS_LANE_ID. Wrap it in eval to load them into your shell.

With several lanes open, add --session <lane-id>, or run it from inside the lane's worktree. --json prints the same as data, and --no-conventional leaves out PORT and TMPDIR. The starting port and spacing come from runtime: in project.yaml, and close-session removes the lane's temp folder.

eval "$(npx -y @vibecompass/vibecompass@latest lane-env --session billing-plans)"
echo "$PORT"    # this lane's port, e.g. 3101
npm run dev     # a dev server that reads PORT uses the lane's port

Repair: lane marker

vibecompass write-lane-marker

A lane marker is a small .vibecompass-lane.yaml file that tells VibeCompass which lane and memory folder a directory belongs to, so commands run inside it need no --root or --session. start-session --worktree writes one for you. Use this to mark a folder you set up yourself; close-session removes the marker with the lane.

The lane must be open, and the folder must be outside your memory folder. Don't write or edit the marker file by hand.

npx -y @vibecompass/vibecompass@latest write-lane-marker \
  --root .compass --session billing-plans --dir ../billing-checkout

Repair: lane list

vibecompass rebuild-active-index

Rebuilds sessions/active/index.yaml, the list of open lanes, from the lane folders that actually exist. The lanes' own scratch files aren't touched.

If several lanes are open and the current-lane hint no longer points at one of them, choose one with --current <lane-id>.

npx -y @vibecompass/vibecompass@latest rebuild-active-index --root .compass
npx -y @vibecompass/vibecompass@latest rebuild-active-index --root .compass --current billing-plans

Opt-in experiment

vibecompass brief

Prints a short markdown brief of the architecture docs, decisions, and session notes a task should start from, with a status and a list of follow-up reads. Printing a brief writes nothing. It briefs what the open lane is working on. With several lanes open, name one with --session (or run it from that lane's worktree), even when you add --task to describe a different task.

--write saves the lane's brief to sessions/active/<lane-id>/brief.md (or rebuilds it), and --check says whether that file is current or stale, and why, without writing anything. Both work whether or not you turned the lane brief on. What a brief picks, its limits, and why it's off by default are on the Concepts page; what each status means is on the Protocol page.

Turn it on for every lane

# Print a brief for the open lane (writes nothing)
npx -y @vibecompass/vibecompass@latest brief

# ...or for a task you describe, plus a file it touches
# (with several lanes open, add --session <lane-id> here too)
npx -y @vibecompass/vibecompass@latest brief --task "Change the refresh denial message" --files app:src/lib/entitlements.ts

# The same result as data, for scripts (contract version 2)
npx -y @vibecompass/vibecompass@latest brief --session billing-plans --json

# Save or rebuild the lane's brief.md, then check it later
npx -y @vibecompass/vibecompass@latest brief --session billing-plans --write
npx -y @vibecompass/vibecompass@latest brief --session billing-plans --check

Write the first real docs

vibecompass docs-review

The easiest user gesture is still the prompt command docs review inside Claude Code, Codex, Cursor, or Copilot. The CLI command is the package mechanic underneath: it records the review marker, prints the review contract, applies accepted fenced output, and can submit or poll a hosted docs-review run.

Do not treat docs-review --guided as finished documentation. A review is only complete after accepted architecture output is applied locally or accepted hosted proposals are exported, applied, and pushed back. To have the package run the review instead of your AI session, --run-local --provider anthropic uses your own Anthropic key (Anthropic is the only provider so far). --complete marks a review done when you wrote the accepted docs by hand.

# Usually run by the AI after you type "docs review".
npx -y @vibecompass/vibecompass@latest docs-review --root .compass --guided --llm codex --model gpt-5-codex

# After you accept the generated fenced output:
npx -y @vibecompass/vibecompass@latest docs-review --root .compass --apply-output --output state/docs-review-output.md

# Hosted review path for connected local-primary roots:
npx -y @vibecompass/vibecompass@latest docs-review --root .compass --submit-hosted
npx -y @vibecompass/vibecompass@latest docs-review --root .compass --poll-hosted

Keep docs tied to the diff

vibecompass docs-update

Reads the selected active lane, changed files, lane claims, new decisions, and existing architecture docs to produce a session-delta documentation maintenance plan. It is intentionally narrower than docs-review: no broad repo review, no LLM call, and no semantic prose writes. Use it to decide which architecture/, decisions/, and session files need attention before close-session, especially when a build touched a feature whose docs are missing or only shallow.

Close-session prints this same plan before it asks for --architecture-docs, --decision-log, and --session-maintenance statuses. Use --changed repo:path when Git status is unavailable or you want to scope the plan manually. The plan also flags affected docs that read like changelogs (architecture-changelog-smell) and docs over the 12 KB soft size budget — both advisory nudges, never blockers.

npx -y @vibecompass/vibecompass@latest docs-update \
  --root .compass \
  --session billing-plans

npx -y @vibecompass/vibecompass@latest docs-update \
  --root .compass \
  --session billing-plans \
  --changed app:src/billing/checkout.ts

Close a lane

vibecompass close-session

Prints the same targeted docs-update plan, validates document-maintenance checkpoint statuses, finalizes the dated session note from the lane-local wip.md, removes the lane directory, and prints any configured close-session workflow guidance (e.g. a Git publish step plus hosted push/refresh guidance by project mode). If sibling lanes are still active, the current-lane pointer moves to one of them instead of going blank. vibecompass end-session is accepted as an alias.

npx -y @vibecompass/vibecompass@latest close-session \
  --session billing-plans \
  --title "Workflow Parity Commands" \
  --completed "Added package-owned session lifecycle helpers" \
  --decision "D-nnn — Logged the new workflow default." \
  --model "Codex (GPT-5) — implemented and verified the workflow commands" \
  --architecture-docs updated \
  --decision-log not-needed \
  --session-maintenance updated \
  --next-step "Run the package publish dry-run"

# If close-session says a connected local-primary hosted dashboard should catch up:
npx -y @vibecompass/vibecompass@latest push --root .compass

Add a decision

vibecompass append-decision

Decisions are append-only: you add new ones and never rewrite old ones. Write the new entry in a file of its own, starting with ### D-NEXT — <title>. append-decision gives it the next free number at the moment it writes, so two lanes can't take the same one, adds it to the end of the decision file you name, and adds it to decisions/INDEX.md under the open lane's group.

The decision file (such as billing.md) must already exist under decisions/. If it can't tell which lane the decision belongs to, for example with no lane open or several, it still records the decision and says the index wasn't updated: name the group with --group <label>, or run refresh-decision-index afterwards. Your AI usually runs this for you when it records a decision.

# 1. Write the entry in its own file, for example staged-entry.md:
#      ### D-NEXT — Checkout uses Stripe Checkout Sessions
#      **Timestamp:** 2026-10-19 09:30 PDT
#      **Decision:** ...
#      **Rationale:** ...

# 2. Append it. The number is assigned now:
npx -y @vibecompass/vibecompass@latest append-decision \
  --root .compass --target billing.md --entry staged-entry.md

Keep the decision index current

vibecompass refresh-decision-index

decisions/INDEX.md is generated from your decision files. This adds any entries the index is missing. Existing groups and rows stay exactly as they are, and if the index's layout is broken it stops instead of guessing. --check only reports whether the index matches, without writing.

New rows go under a group named after the open lane; --group <label> names it yourself.

npx -y @vibecompass/vibecompass@latest refresh-decision-index --root .compass
npx -y @vibecompass/vibecompass@latest refresh-decision-index --root .compass --check

Peek at the next number

vibecompass next-decision-id

Prints the next free decision number. It's only a hint: another lane could take that number before you write, which is why append-decision assigns the number when it writes.

npx -y @vibecompass/vibecompass@latest next-decision-id --root .compass

Regenerate agent files

vibecompass sync-agents

Regenerates the agent instruction files (CLAUDE.md, AGENTS.md, .cursorrules, Copilot instructions) from the current project memory. Lifecycle commands (start-session, switch-session, close-session) already sync them automatically; run this when you change agent-file metadata or want to preview a regenerate.

Useful flags: --dry-run previews planned writes, --format limits the run to one file type, and --adopt-existing appends a managed VibeCompass block to an existing unmarked file.

npx -y @vibecompass/vibecompass@latest sync-agents --dry-run
npx -y @vibecompass/vibecompass@latest sync-agents --format claude_md
npx -y @vibecompass/vibecompass@latest sync-agents --adopt-existing

Upgrade after a package bump

vibecompass refresh-workflow

Re-generates the helper files VibeCompass manages for you so they match the CLI you just installed. Defaults to --dry-run. Full upgrade story (compatibility warnings, sticky package-version stamp) lives on the Upgrade page.

See Upgrade for the full walkthrough

# Preview first (this is the default)
npx -y @vibecompass/vibecompass@latest refresh-workflow --root .compass --dry-run

# Apply when the plan looks right
npx -y @vibecompass/vibecompass@latest refresh-workflow --root .compass --apply