Usage
The CLI talks to the desktop app over a per-user named pipe (a Unix domain socket on Linux/macOS). If the desktop is not running, ambih start spawns it in tray mode and waits for the pipe to appear. Every command accepts --json to switch from human-readable output to newline-delimited JSON for agents and CI.
$ambih <command> [options]
ambih start
Launch the project rooted at the current directory and mirror its output back to your terminal. The launch command can be passed positionally (ambih start "npm run dev") or with --cmd. If a project is already registered for this directory the saved command is used; pass a new one to update it. If none exists, one is auto-registered with the folder's leaf name (override with --name). Pressing Ctrl+C stops the project — the terminal you launched it from owns its lifecycle. If the project is already running, the CLI prompts to tail the existing output; force the choice with --attach or --no-attach.
Synopsis
ambih start ["COMMAND"] [--name NAME] [--attach | --no-attach] [--json]
Options
--name NAME
Name to use when auto-registering a new project.
--cmd "…"
Launch command, as an alternative to passing it positionally.
--attach
Always tail an already-running project instead of prompting.
--no-attach
Never tail; exit 0 without touching a running session.
--json
Stream session_started → log_line* → session_exited as NDJSON.
Example
$ambih start "npm run dev" --name web-app
ambih list
Print every registered project. Running projects are marked.
Synopsis
ambih list | ls [--json]
Options
--json
Emit one JSON object per project (is_running, name, id, …).
Example
$ambih list --json | jq -r 'select(.is_running) | .name'
ambih status
Live + last-session state for one project. While running: current session id, uptime, git branch, and the latest 1 Hz resource sample (CPU / memory / disk / net). While idle: the most recent persisted session with its outcome, duration, exit code, and aggregate stats. The single-shot "what is this project doing right now?" query.
Synopsis
ambih status <project-ref> [--json]
Options
--json
Emit the status as a single JSON object.
Example
$ambih status web-app
ambih history
Recent sessions for one project, newest first. Each row carries an outcome (running | success | failed | stopped | orphaned), duration, git branch, and aggregate metrics. In JSON mode rows stream one per line, so agents can pipeline and short-circuit.
Synopsis
ambih history <project-ref> [--limit N] [--json]
Options
--limit N
How many sessions to return. Default 10; clamped to [1, 1000].
--json
Stream one JSON object per session.
Example
$ambih history web-app --limit 20
ambih diff
Per-metric comparison between two sessions — like git diff but for resource use. Session refs are full GUIDs or unique 8+ character ID prefixes (matching what ambih history emits). Each row carries a, b, delta, delta_percent, and a direction (up | down | unchanged | missing).
Synopsis
ambih diff <session-a> <session-b> [--json]
Options
--json
Stream one JSON object per metric, in a stable order.
Example
$ambih diff a1b2c3d4 e5f6a7b8
ambih exec
One-shot run of a command against an already-registered project, with full monitoring (resource curve, anomalies, exit code). Like ambih start but it refuses if the project is already running (single-instance discipline) and saves the command as the project's launch command. The agent-friendly way to run a build or test under measurement.
Synopsis
ambih exec <project-ref> "<command>" [--json]
Options
--json
Identical event sequence to ambih start --json.
Example
$ambih exec web-app "npm run build" --json
ambih shell
Open a pty-attached interactive shell inside the project's directory. The terminal switches to raw mode so arrow keys, tab completion, Ctrl+C, and full-screen TUIs (vim, htop, less) work like a local shell. Uses the project's configured shell (pwsh on Windows, zsh on Mac, bash on Linux). Refuses if the project is already running — one session per project. Exit with exit or Ctrl+D. No --json mode; shell is interactive by definition.
Synopsis
ambih shell <project-ref>
Example
$ambih shell web-app
ambih verify
CI verdict for one session against a set of checks. Exits 0 = pass, 1 = fail, 2 = inconclusive — pipeline it like eslint --max-warnings 0. Without --session it targets the latest persisted session. All checks are conjunctive.
Synopsis
ambih verify <project-ref> [--session <id>] [--check …] [--max-* …] [--json]
Options
--session <id>
Target a specific session instead of the latest.
--check exit-code
Session exited with code 0.
--check no-anomalies
Zero Warning+ anomalies in the session.
--check regression
Project health verdict isn't Regression (latest session only).
--max-memory <size>
Peak memory under a threshold. Accepts 512MB, 1.5GB, 1024K, 2048.
--max-cpu <percent>
Peak CPU under a threshold. Accepts 80, 80%, 12.5.
--max-duration <dur>
Total duration under a threshold. Accepts 30s, 5m, 1h, 1500ms.
Example
$ambih verify web-app --check exit-code --check no-anomalies \ --max-memory 512MB --max-duration 5m
ambih stop
Stop the live session of a project. The project itself stays registered.
Synopsis
ambih stop <project-ref>
Example
$ambih stop web-app
ambih delete
Remove a project. A running session is stopped first.
Synopsis
ambih delete | rm <project-ref>
Example
$ambih rm web-app
ambih ping
Liveness probe — succeeds when a Ambih desktop instance is listening on the per-user IPC pipe.
Synopsis
ambih ping [--json]
Options
--json
Emit the probe result as JSON.
Example
$ambih ping
ambih help
Show the built-in help text, or print the CLI version with --version / -v.
Synopsis
ambih help | --help | -h ambih --version | -v
Example
$ambih --version
Project references
Any command that takes a <project-ref> accepts a full GUID, the exact project name, a unique id-prefix, or a case-insensitive name. Session refs (used by diff and verify --session) accept a full GUID or a unique 8+ character ID prefix — the same prefixes ambih history prints.
JSON output
Pass --json to switch a command to newline-delimited JSON (NDJSON) on stdout. Each line is one structured event with an event discriminator, a schema_version field, and a UTC timestamp — pipe it through jq or any stream parser. Pre-stream errors (e.g. the desktop not running) still print plain text to stderr and exit non-zero; the JSON contract only covers events emitted after a successful command start.
$ambih start "npm test" --json | jq -c 'select(.event == "anomaly")'
Environment
The CLI communicates with the desktop app over a per-user named pipe (a Unix domain socket on Linux/macOS), so it never opens a network port. If the desktop is not running, ambih start launches it in tray mode and waits for the pipe before streaming. Install or update the CLI from Settings → CLI in the app, which adds the install folder to your user-scope PATH.