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 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 status
npx -y @vibecompass/vibecompass status --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. Keep the raw token out of chat; put it in your shell or password manager. 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.

# Dashboard -> Connect local project -> Setup -> Create sync token
export VIBECOMPASS_SYNC_TOKEN='your-sync-token'

npx -y @vibecompass/vibecompass 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 pull-preview --root .compass
npx -y @vibecompass/vibecompass 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 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 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 sync-target --root .compass

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

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

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 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 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 switch-session billing-plans

Close a lane

vibecompass close-session

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). 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 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" \
  --next-step "Run the package publish dry-run"

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 sync-agents --dry-run
npx -y @vibecompass/vibecompass sync-agents --format claude_md
npx -y @vibecompass/vibecompass 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 refresh-workflow --dry-run

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