Cockpit CLI
Cockpit watches how you and your AI agents work so Edward can coach from evidence instead of screenshots and status pings.
90-second speedrun
Run this on the Mac or Windows PC that should be collected:
npm i -g @bli-cockpit/cli && cockpit doctor
Doctor installs, repairs, and verifies the machine. Follow any sign-in or trust prompt it prints. It finishes with proof of collection or the remaining action.
Every command, what it does, and why it's called that
On a blank Mac or Windows PC, npm i -g @bli-cockpit/cli && cockpit doctor is enough to sign in, choose roots, and converge the machine. onboard remains the named setup subset, and the rest exist for recovery and maintenance.
Cockpit works the same way on an Apple Silicon Mac and on a normal Windows PC. Every Codex and Claude session in a folder you have approved is collected, stripped of anything sensitive before it leaves your machine, and then either uploaded with a receipt or listed with the exact reason it was not. If a session is missing, Cockpit says so — a green screen never hides one.
We only publish a version to npm after it has been tested end-to-end, as a normal user, on both macOS and Windows.
| Command | What it does | Why it exists / why this name |
|---|---|---|
cockpit onboard | The named setup subset: signs you in (email code), registers this machine, starts capture, uploads once, completes all-history Codex and Claude backfill for saved approved roots, installs the 15-min background sync, and only then prints proof you're live. | You are boarding the crew. doctor calls this flow when setup is missing; rerunning it directly is safe. Partial or failed backfill blocks readiness with an exact retry reason. |
cockpit doctor | Converges a Mac or Windows PC from blank or already-onboarded state: latest CLI, signed-in device token, saved roots, autostart, historical backfill, raw-evidence GC, and fresh sync. Interactive first runs prompt for email OTP and collection roots; headless/--json runs explain and exit instead of blocking. --dry-run previews without writing. | Edward can post one line and every intern machine should end green. It checks each row, repairs it, and verifies the result. |
cockpit status | Prints install / sign-in / capture / upload health in one screen. | The "is it working?" command. Run it whenever you're unsure. |
cockpit backfill --all | Uploads your HISTORICAL Codex + Claude sessions (from before Cockpit existed on this machine). Discovery defaults to depth 3 and 50 repos; raise --max-depth or --max-repos when the returned retry command says a cap was reached. | One-time catch-up so your past work counts too. "Backfill" = fill in the back-catalog. |
cockpit sync | Captures and uploads once, right now. This is what the background agent runs every 15 min — you almost never type it yourself. | Named for what it does: synchronize local session files up to the dashboard. |
cockpit analyze | Runs a fresh sync, then queues batch analysis of your latest uploaded sessions. It returns immediately; status and results appear in My Work. | One command when you want newly finished work uploaded and judged now. |
cockpit start --ticket <id> | Tags your CURRENT work with a Linear ticket so sessions attribute to it. --clear-ticket returns to general capture. | "Start (working on) X." Agents usually run this for you per the agent rules. |
cockpit login / cockpit pair | Just the sign-in + device-registration step, standalone (onboard already includes it). Works on a fresh machine too: it writes a minimal local config first (no collection roots — run cockpit onboard afterwards to register those). Two names, one command: login is what humans guess, pair is what the dashboard's device screen calls it. | Recovery path when a session expires or you switch accounts, or sign-in first on a brand-new machine. |
cockpit logout | Deletes this machine's session. | The undo of login. |
cockpit update / cockpit upgrade | Updates the CLI itself from npm, then reruns onboard. Two names, one command — aliases because half of people guess each. | Self-update; run when Edward announces a new version. |
cockpit install | Writes local config only (step 1 of onboard, standalone). | Plumbing; exists so onboard's pieces are individually runnable. You'll likely never type it. |
cockpit sessions | Read-only: lists your observed sessions and how each attributed. | Debugging "why isn't my session showing up?" without uploading anything. |
cockpit autostart install|uninstall|status | Manages the macOS launchd agent or per-user Windows Task Scheduler task behind the 15-min background sync. | Direct control of the background piece when you need to stop/inspect it. |
cockpit agent-rules install|uninstall|status | Manages the Cockpit ticket-binding text block inside ~/.codex/AGENTS.md / ~/.claude/CLAUDE.md. | It's literally "the rules your agents read." Passive markdown — never an executable hook. |
cockpit serve | Runs a tiny local HTTP status server. | Niche: lets other tools ask the collector how it's doing. |
cockpit logout, cockpit release, cockpit admin * | release publishes the CLI (maintainer, repo-gated); admin (bootstrap/invite) is absent from the public build entirely. | Maintainer surface — interns never touch these. |
Honest naming notes: update/upgrade and login/pair are deliberate synonym-aliases (cheap
forgiveness beats a "command not found"); install is a misleading name for "write config" but
is kept for onboard-step symmetry.
Flags
Normal setup needs no flags. Use flags only when the default guess is wrong:
cockpit onboard --email <[email protected]> --workspace ~/BLI
cockpit onboard --workspace ~/BLI --workspace ~/side-projects
cockpit onboard --device-name "Ian MacBook"
cockpit onboard --no-auth
--emailskips the email prompt.--workspacepins one collection root; repeat it for multiple unrelated roots.- Interactive onboarding from your home folder asks whether to sync all projects on the machine. Answer
yonly on a company machine where collecting every current and future repo under$HOMEis intended.nor Enter asks for the actual work folder; if no valid non-home folder is chosen, Cockpit captures nothing and tells you to rerun with--workspace <path-to-your-work-folder>. --allow-home-rootis the headless/scripted form of that full-home opt-in.--device-namechanges only the human label shown in Cockpit.--dashboard-urlis for staging/custom dashboards only. Production is the default.--no-authforces the old manual approval queue.--repostill works as a legacy alias for--workspace.
cockpit doctor is the normal fleet convergence command. On an interactive first run it uses the same email OTP login and root-picker flow as onboarding, then re-checks the machine. In headless, launchd, --json, or no-TTY runs it never prompts; missing auth or roots stay red with the repair text. --dry-run previews without writing auth or config.
cockpit update installs the latest public CLI and reruns onboarding checks against saved roots. cockpit upgrade is the same command.
cockpit --version, cockpit -V, and cockpit version print the installed
public package version. Windows autostart details and verification steps are in
docs/runbooks/cockpit-windows-task-scheduler-sync.md.
Analyze latest work
cockpit analyze --workspace "$PWD"
cockpit analyze first performs the same durable upload as cockpit sync. It
queues the analysis only after that upload succeeds, then exits without waiting
for the Fireworks batch. Use --json for a single machine-readable object that
contains both the sync receipt and queued job status. The dashboard button
analyzes the latest upload already stored by the background collector; run the
CLI command when the work ended too recently for the 15-minute background sync.
Each person can queue analysis once every three hours, subject to the team's
shared $2 UTC-day judge cap. Completion can take several minutes plus the wait
for the next 15-minute collector poll; My Work shows queued, running, done, or
failed status while you wait.
Parent Mode
Use a parent folder such as ~/BLI when it contains multiple repos. Cockpit scans child git repos/worktrees, creates one stable work context per worktree, and rolls them up under repo rows in the dashboard.
Defaults: 3 folder levels deep, up to 50 repos. Tune with --max-depth and --max-repos.
Pairing Recovery
The v2 happy path auto-approves pairing after the email OTP. Manual approval still exists for recovery:
cockpit onboard --no-auth --email <[email protected]> --workspace ~/BLI
Use that when the mailbox is unavailable, auth routes are down, or Edward has added an exact non-domain email exception. Cockpit prints a URL and code; Admin approves from Ambient -> Collector approvals. If the code expires, rerun cockpit onboard after approval and the durable access row will auto-pair.
If this is a reused laptop or VM, keep --email set. Cockpit reuses an existing session only when it belongs to that same email and dashboard URL.
Ticket Semantics
Setup is general ambient capture. Do not invent a ticket for onboarding.
When real ticket work starts:
cockpit start --ticket <ticket-id> --workspace "$PWD"
cockpit sync --workspace "$PWD" --json
For important ticketless work:
cockpit start \
--workspace "$PWD" \
--topic "lead ingestion planning" \
--intent planning \
--phase discovery \
--intent-confidence 0.9
cockpit onboard also refreshes managed ticket-binding guidance in ~/.codex/AGENTS.md and ~/.claude/CLAUDE.md so agents bind visible Linear tickets before edits inside the confirmed workspace.
Storage Layout
Local files:
~/.config/bli-cockpit/config.json: dashboard URL, device label, collection roots.~/.config/bli-cockpit/session.json: paired device token and owner metadata.~/.local/state/bli-cockpit/spool/: uploads waiting to be retried.~/.local/state/bli-cockpit/spool/install-events/: private atomic collector health receipts waiting for authenticated delivery. Receipts contain only sanitized operation metadata, never command output or transcript content.~/.local/state/bli-cockpit/cursors/: bookmarks for how far uploading has got, no raw content..codex-autorunner/contextspace/active_context.md: current work context inside a repo.
Remote data:
- approved user/device identity;
- repo/worktree fingerprints, branch, head SHA, optional ticket, source counts;
- private raw evidence objects and
ambient_evidence_refspointers; - Codex/Claude session attribution metadata.
Never provide service-role keys, raw DB URLs, cookies, root env files, or deployment tokens to this CLI. The collector never reads env files and does not collect random desktop screenshots or screen recordings.
Debug
cockpit sessions --workspace "$PWD" --json
cockpit status --workspace "$PWD" --json
cockpit sync --workspace "$PWD" --json
status --json includes pending_health_receipt_count,
oldest_pending_health_receipt_at, and
last_health_receipt_failure_reason. A nonzero count means Cockpit preserved a
collector failure locally and will replay it on the next authenticated run.
If cockpit update fails with npm EACCES, fix Homebrew global-package ownership once:
sudo chown -R $(whoami) /opt/homebrew/lib/node_modules/@bli-cockpit /opt/homebrew/bin/cockpit
Do not use sudo npm i -g; it recreates the ownership problem.