CLI commands
Setup, discovery, live calls, and machine output.
These commands use the current JSON output contract. Read the release compatibility note when upgrading an older installation.
The CLI emits compact JSON in terminals, pipes, and CI. --json remains a compatibility alias.
--help returns structured command metadata and --version returns a version object.
Commands
| Command | Purpose |
|---|---|
init | Wire Genie into a Vite or Next.js app. |
doctor | Check config and packages. Add --live for the running stack. |
hub | Start the standalone local hub. |
link | Link packages from a local Genie checkout. |
tools | List groups or show one tool contract. |
status | Show bridge, app, session, and readiness state. |
call | Run one live tool. |
batch | Run several calls over one connection. |
capture export | Write a verified capture artifact and return its receipt. |
Discover a tool
npx @genie-react/cli tools
npx @genie-react/cli tools react.render
npx @genie-react/cli tools react_render_causesThe last command shows the description, input schema, limits, and a runnable example.
Time limits
npx @genie-react/cli call react_get_tree '{}' \
--connect-timeout 8000 \
--wait 15000 \
--timeout 30000| Option | What it bounds |
|---|---|
--connect-timeout | Opening the bridge WebSocket. Range: 100–120000 ms. |
--wait | Waiting for an app session. Range: 1–120000 ms. |
--timeout | One tool call. The bridge clamps it to 1000–120000 ms. |
reason:"busy" indicates the app cannot service the call yet. Inspect app state and the returned retry delay. A timeout does not establish whether a mutation completed.
Targeting
npx @genie-react/cli status --session checkout-agent
npx @genie-react/cli status --url ws://localhost:4390/__genie/wsUse GENIE_SESSION and GENIE_BRIDGE_URL to set these once per shell.
Stable failures
Failures keep stdout as valid JSON. They include a stable reason and a safe next
command when recovery is known. A failed batch item does not stop later items.
Output framing and limits
Finite commands return one JSON value, except the JSONL modes below. call retains the advertised tool result schema. Setup
receipts list artifacts and manual actions without dumping source files. Diagnostic records use
JSONL on stderr; --verbose enables connection phases.
batch and --ndjson emit one result per line; batch --json returns one array. --fields
emits projected JSONL rows and zero bytes for an empty collection. hub emits ready, reused,
and stopped lifecycle records. Process exit is 0 for CLI success and 1 for failure. A wait or quiesce result can report ok:false
with exit 0; add --fail-on-result-error to call when a failed wait must fail the script.
Output defaults to 262,144 bytes per JSON document or default JSONL record. An explicit batch
--max-bytes bounds the whole command. --max-bytes accepts 512–50,000,000 bytes. Oversized
output becomes an explicit status:"truncated" envelope. Retrieve fewer records using tool
pagination, select a branch with --select, or raise the limit; never treat truncation as complete evidence.
npx @genie-react/cli call --help
npx @genie-react/cli tools timeline_read
npx @genie-react/cli call react_get_renders '{}' --select /coverage