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.

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

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

Add hosting later

vibecompass connect-hosted

Adds the non-secret hosted binding to project.yaml. First create a hosted project from the dashboard's Connect local project path, then create a one-time sync token on that project's Setup page. You do not download VIBECOMPASS_SYNC_TOKEN; the website shows a raw token once, and VIBECOMPASS_SYNC_TOKEN is the local environment variable name you store it in. Keep the raw token out of chat and Git. 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
#
# Then store the one-time token in your terminal:
export VIBECOMPASS_SYNC_TOKEN='your-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

npx -y @vibecompass/vibecompass@latest pull-preview --root .compass
npx -y @vibecompass/vibecompass@latest push --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 token env var and its own sync history, so pushing to dev never confuses what production thinks your latest version is. 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.

Optional overlap-warning flags: add --feature, --repo, or --claim only when more than one active lane could touch the same feature, repo, or path.

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

See active lanes

vibecompass list-sessions

Lists active feature lanes with their working-on summary and marks which lane is current. Run this before resuming if you are not sure which scratchpad the next builder or reviewer pass should use.

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

Change lanes

vibecompass switch-session

Changes the current-lane pointer before a builder or reviewer resumes. The switch also re-syncs CLAUDE.md and other generated agent files so the next AI session loads the selected lane's context.

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

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.

# 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. Since 0.13.0 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

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