Cockpit CLI

The Cockpit CLI is a thin layer over the running Cockpit server's HTTP API. Two binaries are installed by npm install -g @surething/cockpit: cockpit (canonical name) and cock (short alias) — identical. The server itself runs continuously; sub-commands speak HTTP to localhost:3457 to inspect or drive what's open in your panels.

cockpit and cock

The cockpit binary is the main entry point. Its short alias is cock — both are installed when you npm install -g @surething/cockpit.

Usage

cockpit [path] [options]
cock    [path] [options]

The two commands are identical; pick whichever you prefer to type.

Common forms

Start in the current directory:

cockpit

Start in a specific project:

cockpit ~/code/my-project

Start without auto-opening the browser:

cockpit . --no-open

Start on a different port:

cockpit . --port 4000

Show the version:

cockpit -v

Options

Default port

Cockpit listens on port 3457. You can override per-run with --port, or make it permanent by writing to ~/.cockpit/server.json:

{ "port": 4000 }

The per-run flag wins when both are set.

Sub-commands

cockpit itself starts the server. Two sub-commands are used to drive Cockpit from external scripts (CI, ChatOps, automation):

Both target an already-running Cockpit server at localhost:3457. They're the same APIs the in-app UI uses; exposing them as CLI commands lets you script the bubbles from anywhere.

See:

• cockpit browser — full action list (25+ actions: snapshot, click, type, network, perf, …)
• cockpit terminal — list / output / wait (read-only)

Upgrading

cockpit update

Equivalent to npm install -g @surething/cockpit@latest. See cockpit update for what gets preserved across upgrades.

Exit codes

Environment variables

cockpit browser

cockpit browser <id> <action> (or cock browser for the short form) drives a Browser bubble in your running Cockpit instance from outside — from the AI in a chat, from a shell script, from CI, from anywhere.

The <id> is the short ID badge from the Browser bubble's title bar. Click the badge to register the bubble and copy a starter command to your clipboard.

The CLI is designed for AI-driven E2E: every command has an actionable error template, silent failures are caught and warned, and the act/wait/assert cycle composes into atomic steps. Prefer selector-based interaction (--text, --selector) over snapshot refs — refs go stale on every re-render.

Quick examples

# Diagnose where the AI is currently parked (cheap, never blocks)
cock browser xa7k2 health
cock browser xa7k2 status

# Find and interact (selector-first; refs go stale on re-render)
cock browser xa7k2 snapshot --filter 'role=button' --include-hidden-text
cock browser xa7k2 click --text "Sign in"
cock browser xa7k2 click --selector 'button[type="submit"]'
cock browser xa7k2 fill --selector 'input[name="email"]' --value "[email protected]"
cock browser xa7k2 submit --form-selector 'form#login'

# Probe the backend (inherits page auth)
cock browser xa7k2 fetch /api/users/me
cock browser xa7k2 fetch /api/items --method POST --body '{"name":"hello"}'
cock browser xa7k2 fetch /api/items --json '$.data[0].id'

# act → wait → assert (atomic E2E)
cock browser xa7k2 click --text "Save"
cock browser xa7k2 wait --network-idle --quiet-ms 500
cock browser xa7k2 assert --selector '[role="status"]' --text "Saved"
cock browser xa7k2 assert --fetch /api/items --jsonpath '$.count' --equals 5

# Test isolation
cock browser xa7k2 reset --cookies --storage --reload
cock browser xa7k2 set --type cookie --name token --value abc123 --path /

# Run arbitrary JS (escape hatch — prefer fetch/click-by-selector when possible)
cock browser xa7k2 evaluate "document.title"
cock browser xa7k2 evaluate --all-frames "await fetch('/api/x').then(r=>r.json())"

Full action list

Inspection

Interaction

Selector-based forms are preferred — refs are valid only until the next snapshot or re-render.

Wait — synchronisation between act and assert

Assert — non-zero exit on failure

Navigation

Backend probing

fetch is the preferred way to read or mutate the backend from the AI — clearer than wrapping await fetch(...).then(r => r.json()) inside evaluate.

JavaScript

Use evaluate as an escape hatch when none of the higher-level actions fit. For plain HTTP calls, prefer fetch; for clicks, prefer click --text / --selector; for assertions, prefer assert --selector.

Lifecycle / fixtures

Diagnostics

Network capture

Snapshot output

snapshot returns a plain-text accessibility tree. The first 4–5 lines are a banner explaining the format, including the current snapshot version (v=N):

# a11y tree v=3 — refs valid until next snapshot
# Text inside <details>/<summary> and unnamed container <div>/<section> is collapsed.
# Grep on role / aria-label, NOT on user-visible emoji / text.
# Tips: --include-hidden-text surfaces collapsed innerText; --filter <regex> reduces output.
body [e0#v3]
  ...

Each addressable element gets a ref like e5#v3. The #v3 suffix is the snapshot epoch — refs from an earlier snapshot are rejected with a clear "stale" error that points you to click --text / click --selector as the re-render-safe alternative. Most AI workflows should skip refs entirely and use --text / --selector directly.

Post-verify for click / key / submit

These actions are most prone to silent failure — CDP reports "succeeded" even when the framework didn't actually react to the event (React-controlled inputs ignoring synthetic keydown, portal-rendered buttons with no real handler, etc.). The CLI silently probes the page state before and after each action; if nothing observable changed in the verify window, it writes a warning to stderr along with actionable templates (without affecting the action's main stdout).

Output format

Most actions return JSON on stdout — easy to pipe into jq, gron, or to read from the AI. url, title, and network_detail return plain text. screenshot returns a file path. snapshot returns the banner + plain-text accessibility tree. health, status, wait, and assert print a one-line human-friendly summary. fetch prints [status] (contentType) followed by the body, or [status] $.jsonpath = followed by the extracted value.

Warnings (silent-failure detection, cookie not accepted, etc.) go to stderr. The main result stays on stdout, so a > redirect captures the real data while letting the AI still see the warning.

Exit codes

0 on success, non-zero on failure (stale ref, network error, assertion failure, no matching element, etc.). See the main CLI page for the full exit code list.

When NOT to use this CLI

• Testing LLM-agent driven flows end-to-end. The agent's stochastic tool choice and stop_reason make UI assertions flaky. Prefer a thin runtime script that calls the same middleware or service directly with controlled inputs.
• Pages that stream or re-render for >10 s. evaluate calls queue behind page work and may time out (~15 s default). Run wait --extension-ready between acts and asserts; if it stays hung, pivot to a service-level test.
• Multi-tab / popup OAuth flows. Each Browser bubble tracks one tab. Open the secondary tab in its own bubble, or stub the OAuth handshake.

cockpit terminal

cockpit terminal <id> <action> (or cock terminal) reads from a Terminal bubble in your running Cockpit — pulls the buffered output or waits for a running command to settle.

Note: the terminal CLI is intentionally read-only. There is no stdin and no follow (live streaming). The code comment says: "read-only by design; the write side belongs to the Bash tool / web UI." For interactive control, drive the bubble inside Cockpit's UI, or use a Browser bubble + cock browser for automation.

The <id> is the short ID badge from the Terminal bubble's title bar. Click the badge to register the bubble and copy a starter command to your clipboard.

Full action list

Quick examples

# Find your bubbles
cock terminal list

# Snapshot what's on screen now
cock terminal xy789 output

# Wait for npm run build to finish
cock terminal xy789 wait

# Then look at the result
cock terminal xy789 output | tail -50

When to use this

Main patterns:

• AI reads what your shell is doing through the bubble. Run npm run dev in a Terminal bubble. Hand cock terminal <id> to the AI in chat — it can output for recent logs and wait for a build to settle.
• CI / scripts observe a long-running command from outside. A launcher script kicks off npm run dev in a Cockpit terminal; another script periodically runs cock terminal <id> output to scrape logs and assert.

Limits

The Terminal CLI is intentionally lighter than the Browser CLI:

• No write to stdin. You can't push commands into the terminal process from the CLI.
• No screen-scraping with structured selectors (output gives you the raw buffer, you parse it yourself).
• No window-resize, signals, or Ctrl+C-style interrupt actions.

For full interactive control (Ctrl+C, typing commands, etc.), interact with the bubble in Cockpit's UI directly.

cockpit codegraph

cockpit codegraph queries the project-wide code index that powers the in-product CodeGraph feature (/cg mode), but from your shell so it composes with scripts, CI, and Unix pipelines.

The Cockpit server must be running — the CLI talks to it over HTTP on the local port.

Two families of subcommands

Lookups — coordinates only (file paths + line numbers), mirroring the in-product API:

Analytics — blended scoring across PPR / TF-IDF / Louvain communities / co-edit:

Common flags

--json             # Raw JSON response (full schema; see per-cmd --help)
--help, -h         # Subcommand-specific help (output format + exit codes + examples)

Output format (plain text)

TAB-separated, one row per result. Pipeable into cut, awk, fzf, etc.

search    sym\t<file>:<line>\t<kind>\t<qname>            or  file\t<file>
callers   <file>:<line>\t<qname>\t[<callLines>]
callees   <file>:<line>\t<qname>\t[<callLines>]
impact    d=<depth>\t<file>:<line>\t<qname>
file      <kind>\t<startLine>-<endLine>\t<qname>
coedit    <cooccur>/<total>\t<file>                  # after a '# history' comment
context   <score>\t<file>:<line>\t<qname>\t[<signals>]
related   <score>\t<file>:<line>\t<qname>\t<<relations>>
risk      <score>\td=<depth>\t<file>:<line>\t<qname>\t[<tags>]
affected  <file>                                     # one test path per line

Pass --json to get the full structured payload instead.

Diagnostics on stderr

Designed so warnings don't break shell pipelines:

# ambiguousIn: <files…>     Same qname in multiple files — pass --file
# cursor: <note>            Cursor format auto-corrected ('.' → '::', etc.)
# degraded: <reason>        analytics-warming / coedit-unavailable / truncated

Exit codes

Prerequisites

The CLI hits http://localhost:3457 by default (the same port as the main Cockpit server — not a separate codegraph port). Override via:

COCKPIT_HOST=… COCKPIT_PORT=… cock codegraph …

Examples

cock codegraph search getCodeIndex

cock codegraph related getCodeIndex --top 5

cock codegraph risk searchIndex --depth 2

# Newline-separated test paths for whatever changed:
git diff --name-only | cock codegraph affected --stdin

# Drive jest directly with the affected tests:
git diff --name-only | cock codegraph affected --stdin --as-cmd jest

# Same idea for vitest:
git diff --name-only | cock codegraph affected --stdin --as-cmd "vitest run"

See also

• CodeGraph (in-product) — the same index, but queried by the AI via /cg slash mode.
• LSP — alternative for editor-grade go-to-definition / find-references.

cockpit connection

cockpit connection list enumerates every bubble — terminal and browser — that the running Cockpit server knows about, with each bubble's user-set title (set via the ✎ button next to the bubble's short id).

The point is to give an LLM (or a human at a shell) a way to map cryptic 4-character bubble ids to human-meaningful purposes before driving them via cockpit terminal <id> … or cockpit browser <id> …. This page maps to the /cc slash mode used by the agentic flow.

Usage

cockpit connection list [--cwd PATH] [--all] [--json]

Only one subcommand exists today — list.

Flags

Output (plain, TAB-separated)

<type>  <shortId>  <title-or-(none)>  <projectCwd-or-?>  <command-or-empty>

One row per bubble. <type> is term or browser.

Output (--json)

Array of:

{
  "type": "term" | "browser",
  "shortId": "abcd",
  "title": "optional user-set label",
  "projectCwd": "/abs/path",
  "tabId": "…",
  "command": "npm run dev",
  "alive": true
}

Exit codes

Examples

# All live bubbles across all projects:
cockpit connection list

# Only this project's bubbles:
cockpit connection list --cwd $PWD

# Everything (including dead), as JSON for programmatic use:
cockpit connection list --all --json | jq

See also

• cockpit terminal — drive a terminal bubble by id.
• cockpit browser — drive a browser bubble by id.

cockpit update

cockpit update upgrades Cockpit to the latest published version.

cockpit update

Equivalent to running:

npm install -g @surething/cockpit@latest

You can run either; they do the same thing.

What gets preserved

Everything in your Cockpit data folder (~/.cockpit/) is untouched by an upgrade:

• API keys and engine settings
• Sessions and pinned tabs
• Scheduled tasks
• Skills registry
• Notes
• Reviews
• The Chrome extension cache

Just the global npm package gets replaced.

After upgrading

Restart any running cockpit process to pick up the new version. If you have Cockpit open in a browser tab, refresh the page after restart.

To verify:

cockpit -v

If cockpit update fails

The most common cause is that npm install -g needs elevated permissions on your system (a globally-installed npm package is owned by root on some setups). If you see an EACCES error, run with sudo:

sudo npm install -g @surething/cockpit@latest

Or, better, fix your npm permissions once so you don't need sudo. The npm docs have a guide for this — search "resolving EACCES permissions errors npm".

Pinning to a version

To install a specific version instead of the latest:

npm install -g @surething/[email protected]

The version list is at npmjs.com/package/@surething/cockpit.

Downgrade

The same command — just give it the older version you want:

npm install -g @surething/[email protected]

Your data folder is forward and backward compatible across minor versions; downgrading is safe.