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 these three commands on the Mac that should be collected:

$ npm install -g @bli-cockpit/cli@latest
added <packages> in <seconds>s

$ cockpit onboard
Cockpit harvest onboarding
Dashboard: https://bli-cockpit-dashboard.vercel.app
Ticket: general ambient
What's your @buildlaunchiterate.ca email? (press enter to skip): [email protected]
Signing in as [email protected].
Code sent; valid 1h, resend in 60s by rerunning this command.
Email code needed:
  Check your latest Cockpit email for a 6- to 10-digit code.
What you can do:
  1) Paste the code here.
  2) No code yet: wait for the resend window, then rerun this command.
  3) Can't use email: rerun with --no-auth for manual approval.
Code: 482913
Signed in as [email protected].
2/5 Device paired.
PASS: Cockpit collector is ready for harvest.
You're live.
Dashboard: https://bli-cockpit-dashboard.vercel.app/my-work
Next: cockpit status

$ cockpit status
Install: ready
Auth: paired
Upload state: ready

The OTP proves you own an approved BLI mailbox. The JWT is used once to register this device and is never saved; the durable local credential remains the existing Cockpit device token.

Every command, what it does, and why it's called that

On a blank Mac, npm i -g @bli-cockpit/cli && cockpit do-everything 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.

| Command | What it does | Why it exists / why this name | |---|---|---| | cockpit onboard | The everything-command: signs you in (email code), registers this Mac, starts capture, uploads once, installs the 15-min background sync, and prints proof you're live. | You are boarding the crew. Run it once per machine; rerunning is always safe. | | cockpit do-everything / cockpit fix | Converges a Mac 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. fix is the alias people guess. | | 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 Mac). | 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). 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. | | 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 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

• --email skips the email prompt.
• --workspace pins 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 y only on a company machine where collecting every current and future repo under $HOME is intended. n or 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-root is the headless/scripted form of that full-home opt-in.
• --device-name changes only the human label shown in Cockpit.
• --dashboard-url is for staging/custom dashboards only. Production is the default.
• --no-auth forces the old manual approval queue.
• --repo still works as a legacy alias for --workspace.

cockpit do-everything 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.

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/: safe retry records.
• ~/.local/state/bli-cockpit/cursors/: upload/backfill cursors, 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_refs pointers;
• 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

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.