Skip to main content
The CLI is built to be driven by AI coding agents and scripts. In agent mode it prints JSON, never opens the interactive UI, never prompts and never animates. Every failure has a stable error code and a semantic exit code.

Agent mode

Agent mode turns on automatically when the CLI sees that a coding agent started it. It checks these environment variables, in this order: Any of these counts when it is set to a value other than empty, 0, false, no or off. Set SYNHEART_AGENT=0 to force agent mode off, even inside an agent’s shell. This is useful when you run the CLI by hand in a terminal that an agent also uses. In agent mode:
  • The output format defaults to JSON. An explicit --format text still wins, also on errors raised before flags are parsed (synheart mock strt --format text prints the text error).
  • The interactive UI never opens. Bare synheart and synheart --help print a compact command index instead.
  • There are no spinners, no colour and no passive update notices.
  • Nothing prompts. A command that would prompt fails at once with SH-AGENT-001, and the hint names the flag to pass. For example, synheart login needs --ci-token <token> or SYNHEART_CI_TOKEN. synheart update does not prompt either: without --yes it only reports whether a newer version exists (a result with up_to_date, current and latest, and exit code 1 when there is one), and --yes applies it. synheart local --https and synheart local cleanup need sudo to trust the certificate and edit /etc/hosts; when sudo would ask for a password they fail with SH-AGENT-001 instead. Run sudo -v first, or run the command yourself with SYNHEART_AGENT=0.
synheart guard, which holds coding agents to rules you set, ignores SYNHEART_AGENT=0. An agent cannot switch detection off to get around a rule, and only a person at a terminal can grant an exception. See AI & agents.

Ask for JSON

Pass --json or --format json on any command that supports it. The command reference marks each command, and supports_json in the command map says the same thing for scripts. --json together with --format text is a usage error. synheart install and synheart sync count too: under --json they print one result object. A few commands have no JSON form, such as guard allow, guard init, guard install, guard sync, guard team join and guard team leave. An explicit --json on one of them is a usage error (exit 2) instead of silently printing text. guard rules, guard report, guard check, guard team status and explain do print JSON.

JSON conventions

Every JSON body follows the same rules, so scripts and agents can rely on it.
  • Names use snake_case. Common fields keep the same spelling everywhere: id, name, description, created_at, error_code, logged_in, next_cursor.
  • Lists are objects with an items array, even when there is only one page. This leaves room for next_cursor later without a breaking change.
  • Platform commands follow the same shape. org, project and api-key lists print {"items": [...]}, plus next_cursor and pagination when the platform sends them. A show prints the object itself. The platform’s success and message wrapper is dropped. A command with nothing to return, such as a delete or a revoke, keeps the platform’s body.
  • Timestamps are RFC 3339, such as 2026-05-06T18:42:11Z, never Unix integers. Time zone offsets are kept as given.
  • Durations are integers with a _ms (milliseconds) or _s (seconds) suffix.
  • Required fields are always present, even when empty. Optional fields are left out when they have no value.
  • Adding a field is not a breaking change. Removing or renaming one, or changing its type, is. Array order is only stable when the field name says so.

Errors in JSON

When a command fails in JSON mode, it still prints a valid JSON body and exits with a non-zero code. You never have to choose between the exit code and the body.
Every failure carries error_code, class, exit_code and message. The other fields appear only when they have something to say. An agent can act on fix without parsing text. fix.command is the first line of the hint when that line is a complete synheart command; a hint that is an example rather than a command gives no fix, so you never run it with made-up values. That means a placeholder (<id>, [name], prj_…), a quoted example string, a shell variable such as $TOKEN, […], ..., or a word like your-… or *.example. safe_to_run is true when the command writes no files, is not destructive, does not run until stopped and is not interactive. Reading the network or your account is fine, so you may run it unprompted. That covers --help and help, version, whoami, auth status, doctor, explain, env, config show and config path, completion, mcp, mock, mock list-scenarios and mock describe, org, project and api-key list and show, usage, syni personas, syni personas show, syni sessions show, syni version, guard check, guard rules and guard report, guard team status, runtime current, and update --check. needs_human is true when a person has to take part: synheart login without --ci-token, synheart update without --yes, guard allow, local --https, syni chat (the REPL), and ui or anything else that opens the interactive UI. A command that is neither, such as synheart install runtime, is one you may run once you have decided to. synheart mock describe workout --json prints the scenario’s own keys, here trimmed:
A mistyped name comes back with the candidates. This is synheart mock describe stres --json, which exits 4:
Changed in 0.20 (breaking). message replaces both title and error, which are gone. detail and hint are left out when empty instead of being "", and hint is also left out when it is only the command already in fix.command. fix, did_you_mean and valid_values are new. Readers of title or error should read message. Readers that tested detail == "" should test for its absence.
When the platform API answered with its own error, the body adds upstream, for example:
When the platform cannot be reached at all (connection refused, DNS, timeout), the error is SH-NET-004 with class: "transient" and exit code 5, so a script can retry. A command that reports status, such as whoami, auth status, auth refresh, runtime current and config path, keeps its own fields and adds the error fields beside them. For example, whoami signed out still has logged_in: false, and its message is Not signed in.. Its exit code follows the table below. A mistake in how you called the CLI, such as an unknown flag, uses error_code: "SH-CLI-USAGE" and exits 2. It is a JSON body whenever --json or --format json appears anywhere on the line, even after the bad flag. In text mode the usage pointer goes to stderr. An unknown scenario name is SH-MOCK-NOTFOUND and exits 4. An unknown flag on a group is reported as that flag, not as an unknown command: synheart mock --scenario baseline is unknown flag: --scenario, with close flag names in did_you_mean. An unknown subcommand is a usage error too. synheart mock strt, synheart org lst, synheart help <unknown> and synheart <unknown> --help all exit 2 with did_you_mean, instead of printing help and exiting 0. A bare group such as synheart mock still prints its help and exits 0. This is synheart mock strt --json:
Mistyped flags, scenarios and explain topics suggest the closest names the same way. A missing argument says what is missing rather than printing cobra’s accepts 1 arg(s), received 0: synheart mock describe with no name is Name a scenario, with valid_values listing the scenarios and a fix that runs synheart mock list-scenarios. In a stream, the error event carries the same fields plus ok: false. syni version --json prints spec, runtime and source. source is vendor when it read the installed files. With no vendored copy it falls back to what synheart.lock pins and reports "source": "lockfile". whoami --json and usage --json include claims_refreshed. It is true when that run refreshed a stale access token first, so a recent plan change is already reflected in the result.

Follow long-running commands (NDJSON)

Installs, servers and recordings can be followed line by line. Each line on stdout is one JSON object, flushed immediately. Progress bars, spinners and banners are off, and stderr carries only genuine warnings.

Which flag gives what

A command that prints one final object keeps doing so under --json, so existing scripts do not break. Streaming is opt-in with --format ndjson. A server has no single result, so --json and agent mode already mean the stream. --json together with --format ndjson is a usage error (exit 2).

The envelope

Every event starts with the same three fields:
ts is RFC 3339 with milliseconds. Other fields are snake_case and sorted alphabetically; do not rely on their order. Ignore unknown fields and unknown event names, because new ones can be added.

Events

Exactly one terminal event (done or error) ends a run, and nothing follows it. The process exit code matches exit_code. A server stops on SIGINT or SIGTERM by emitting done with "interrupted": true and exits 0. A failure before the stream starts, such as a bad flag, is a single error event.

Receiver exports

In event mode synheart receiver writes only events to stdout. Each received export is an item event with kind: "export" and an export_id. The export is in payload (one compact line) when you pass no --out, or path is the file written when you do. --output-format then only affects the files under --out. The ready event carries endpoint and token, and done carries received, duplicates and errors.

Recipe: start the mock server and connect

  1. Start synheart mock start --json and read stdout line by line.
  2. Wait for the ready event. Do not connect before it, because the listeners are not bound until then. A port already in use produces an error event instead.
  3. Read ws_url (also sse_url and udp_url) and connect. dashboard_url is in the event only when you started the server with --web.
  4. Stop the server with SIGINT and read the final done event for counts.

Exit codes

Branch on the exit code instead of parsing messages.

Command map

The full map is over 100 KB, so bare synheart and synheart --help in agent mode print a compact index instead (about 10 KB). synheart help --json prints the full machine-readable map of every public command and flag. For one command, run synheart <command> --help --json or synheart help <command> --json. It prints just that command’s entry, the same object as one element of commands. In agent mode --help defaults to JSON; pass --format text to get the text back.

The command index

Start here. It lists every command’s path and one-line summary, grouped the way synheart --help groups them (build, run, account, cloud, ai, tools and other), plus the exit codes and environment variables.
A group lists its top-level commands, each followed by its subcommands. Use next for one command’s detail and full for the whole map.

The full map

  • Commands are sorted by path. Hidden commands and flags are left out.
  • flags holds a command’s own flags. global_flags holds the flags every command inherits.
  • subcommands lists the paths of a command’s visible direct subcommands.
  • supports_json is derived from the commands themselves, so it is true for every command that prints a single JSON body, including install and sync. It is false for the streaming commands (mock start, mock record, mock replay, local, receiver): their --json emits an NDJSON event stream instead of one object.
  • examples is a list of {"description", "command"} objects: the # comment above the example in the text help ("" when there is none) and the command. Independent synheart commands under one comment are separate entries that share the description; lines that only work together (an export before synheart login, a cd, a pipe) stay one entry, joined by \n.
  • group is the section a top-level command appears under in synheart --help. It is empty for subcommands.
  • formats lists the --format values the command honours: always text, json when it prints a single JSON body, ndjson when it takes part in the event stream. A server (mock start, mock record, mock replay, local, receiver) lists ["text", "ndjson"], and install and sync list all three.
  • requires_auth, network, writes_files, destructive, long_running and interactive say what running the command involves, so an agent can decide before it runs. requires_auth means an account. network means a call to Synheart’s servers or the internet (local listeners do not count). writes_files means files are created or changed (the CLI’s own caches, such as the credential refresh whoami may do, do not count). destructive means something is deleted or revoked for good. long_running means it runs until stopped. interactive means a person at the keyboard: a browser sign-in, a confirmation, sudo, guard allow or the interactive UI, which agent mode fails on instead of prompting. A parent group that only prints help has all six false.
  • exit_codes and env list the exit codes and the environment variables the CLI reads.
An agent that has not seen the CLI before can read the index once, then ask for the commands it needs.

Check the setup with doctor

synheart doctor --json reports each check as an entry in checks[]:
  • ok is true when no check has status error. summary counts the checks by status.
  • scenarios_dir is left out when there is no local scenarios directory.
  • status is ok, warn or error.
  • fix.command is the exact command that resolves the check.
  • safe_to_run follows the same rule as the error envelope’s fix: it is true when the command writes no files, is not destructive, exits by itself and needs no person. An account or network read is fine. It comes from the command’s traits in the command map, so synheart install runtime, synheart sync and synheart mock start --port … are false. When it is false, ask a person before running it, or run it once you have decided to.
  • needs_human is true when a person has to take part, such as synheart login, which opens a browser.
  • fix.requires lists fixes that must succeed first. While you are signed out, a fix that needs an account has "requires": ["synheart login"]. The text report’s TRY list is in that order.
  • notes[] holds facts that are not verdicts. Outside an app project (no Package.swift, build.gradle or pubspec.yaml, and no .synheart/ here or above) a missing synheart.lock is not a warning. The report notes Not in an app project · cd into your app, or run synheart init instead.
  • doctor exits 1 only when your app cannot work: the runtime is missing or incompatible, or its files are missing or modified. Warnings do not change the exit code.
Changed in 0.21 (breaking).
  • Index group ids and names changed. Ids are now build, run, account, cloud, ai, tools and other; they were build, simulate, platform, ai, troubleshoot and other. Names are Build, Run locally, Account, Cloud, AI & agents, Tools and Other. Platform is split into Account (login, logout, whoami, auth, usage) and Cloud (org, project, api-key). The command map’s group uses the same ids.
  • help --json examples are objects, {"description", "command"}, not strings.
  • synheart mock describe --json keys are snake_case. Signals and phase overrides use the scenario file’s keys (baseline, noise, rate, unit, add, multiply, value, ramp, ramp_to_baseline) and list only the keys that are set. Phases are {"name", "duration", "overrides"}, and phases is [], never null.
In agent mode, synheart login fails fast with SH-AGENT-001 instead of opening a browser. Pass --ci-token <token> or set SYNHEART_CI_TOKEN for unattended sign-in.

MCP server

synheart mcp serve runs an MCP (Model Context Protocol) server on stdin and stdout, so an agent in Claude Code, Cursor or Claude Desktop can do its first hour on an app without a shell. It has 15 tools. Nothing in the server signs in, opens a browser, copies to the clipboard or prompts.

Set it up

The client starts the server as a subprocess. Relative paths in tool arguments resolve against its working directory, normally the app project you opened. If the agent cannot find synheart, give the client the absolute path from which synheart, because client subprocesses often inherit a minimal PATH.

The tools

“Safe” says whether an agent may call the tool unprompted. “CLI” is the command it stands for. Every tool’s inputSchema has additionalProperties: false. An unknown argument, a value of the wrong type, a port out of range or a value outside an enum fails with SH-CLI-USAGE (exit 2), with did_you_mean and valid_values. The full argument list for each tool is in tools/list.

Safety comes from command traits

A tool’s safe verdict is not a separate list. It comes from the traits of the CLI command the tool stands for, the same ones synheart help --json reports and fix.safe_to_run uses: a tool is safe when its command writes no files, deletes nothing, exits by itself and needs no person. Reading the network or the account is fine. The same traits give each tool in tools/list its MCP annotations (readOnlyHint, destructiveHint, openWorldHint), and each tool’s description says what it does, its side effects and whether it is safe to call unprompted.

The first hour

A typical run for an agent on a new app:
  1. synheart_init sets up the app project. It refuses your home directory (SH-CFG-006) and never overwrites a backup.
  2. synheart_doctor checks the setup. Each check’s fix says what to run next.
  3. synheart_mock_list_scenarios and synheart_mock_describe pick a scenario.
  4. synheart_mock_start streams mock data and returns its endpoints.
  5. synheart_connect_info gives the WebSocket, SSE, UDP and control URLs and a client snippet for the app.
  6. synheart_mock_status shows whether the app has connected (clients, ever_connected).
  7. synheart_mock_stop ends the stream.
To check it, ask the agent: “Set this app up for Synheart and stream some mock data I can connect to.” It should call synheart_init, then synheart_mock_start, then synheart_connect_info.

The mock stream

synheart_mock_start does what synheart mock start does, without blocking. It returns once the WebSocket (port), SSE (port+1) and UDP (port+2) listeners are bound, and the stream keeps running inside the MCP server. It writes no files and opens no browser, so --out and --web are not arguments.
  • One stream per server. While one runs, another synheart_mock_start fails with SH-MOCK-005 (usage, exit 2). Stop it first, or keep using it.
  • It ends on synheart_mock_stop, when its duration runs out, or when the MCP server exits because the client disconnects or closes stdin. Its ports are free again when it ends.
  • A port in use fails with SH-MOCK-004 (transient, exit 5), as the CLI does. fix.command suggests another port.
synheart_mock_start, synheart_mock_status and synheart_mock_stop return the stream’s status: running, state (none, running, stopping, finished, stopped or failed), scenario, vendor, rate, host, port, seed, endpoints (ws_url, sse_url, udp_url, control_url), events, events_per_s, clients (ws, sse, udp) and ever_connected. synheart_mock_stop adds was_running, and with nothing running it does nothing and says "was_running": false. If the stream has not shut down within 10 seconds, synheart_mock_stop fails with SH-MOCK-007 and the state stays stopping until it has.

Errors

When a tool fails, the reply sets MCP’s isError: true flag instead of a JSON-RPC error, so the conversation does not abort. The text is the CLI’s JSON error envelope: error_code, class, exit_code and message, plus detail, hint, fix, did_you_mean and valid_values when present. fix.command is a CLI command line; an agent on MCP calls the matching tool when there is one. synheart_auth_status, synheart_whoami and synheart_doctor (when the app cannot work) report a status, so they fail with that body and the envelope merged in, as --json does. Signed out, synheart_whoami returns:

What is not a tool

The server mirrors what an agent can do on its own. These stay with the person at the terminal:
  • Interactive commands: login (a browser sign-in), guard allow (only a person may approve), update (it confirms and replaces the binary), local --https and local cleanup (sudo), and ui and syni (a terminal UI or chat).
  • Commands that install or fetch artifacts: install, sync, runtime install and runtime upgrade, and guard sync. They write into the app project from the registry and need an account. An agent runs them in a shell when you ask; synheart_doctor names them as fixes.
  • Other long-running servers: mock record, mock replay, local and receiver. They write files or serve a platform. synheart_mock_start covers building against mock data.
  • Platform commands (org, project, api-key, usage) and logout: account-level changes outside the first-hour loop.
  • Resources, prompts and sampling are not offered, and the transport is stdio only.
To check the server from a shell, without any client:
The reply lists every tool, sorted by name.
Changed in 0.21. The server grew from 7 read-only tools to 15, and it now includes tools that write files (synheart_init) or keep running (synheart_mock_start). synheart_list_scenarios is deprecated in favour of synheart_mock_list_scenarios; it still works. synheart_auth_status and synheart_whoami signed out, and synheart_doctor when the app cannot work, now come back with isError: true, as --json exits non-zero.

Recipes

Bootstrap an app project

An agent sets up a Flutter or native app project from a clean checkout:
Run synheart doctor --json again at the end. "ok": true means the app can run.

Branch on failure

Run the CLI unattended