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 textstill wins, also on errors raised before flags are parsed (synheart mock strt --format textprints the text error). - The interactive UI never opens. Bare
synheartandsynheart --helpprint 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 thehintnames the flag to pass. For example,synheart loginneeds--ci-token <token>orSYNHEART_CI_TOKEN.synheart updatedoes not prompt either: without--yesit only reports whether a newer version exists (a result withup_to_date,currentandlatest, and exit code 1 when there is one), and--yesapplies it.synheart local --httpsandsynheart local cleanupneed sudo to trust the certificate and edit/etc/hosts; when sudo would ask for a password they fail withSH-AGENT-001instead. Runsudo -vfirst, or run the command yourself withSYNHEART_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
itemsarray, even when there is only one page. This leaves room fornext_cursorlater without a breaking change. -
Platform commands follow the same shape.
org,projectandapi-keylists print{"items": [...]}, plusnext_cursorandpaginationwhen the platform sends them. Ashowprints the object itself. The platform’ssuccessandmessagewrapper 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.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:
synheart mock describe stres --json, which exits 4:
upstream, for example:
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:
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 modesynheart 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
- Start
synheart mock start --jsonand read stdout line by line. - Wait for the
readyevent. Do not connect before it, because the listeners are not bound until then. A port already in use produces anerrorevent instead. - Read
ws_url(alsosse_urlandudp_url) and connect.dashboard_urlis in the event only when you started the server with--web. - Stop the server with SIGINT and read the final
doneevent for counts.
Exit codes
Branch on the exit code instead of parsing messages.Command map
The full map is over 100 KB, so baresynheart 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 waysynheart --help groups them (build, run, account, cloud, ai, tools and other), plus the exit codes and environment variables.
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. flagsholds a command’s own flags.global_flagsholds the flags every command inherits.subcommandslists the paths of a command’s visible direct subcommands.supports_jsonis derived from the commands themselves, so it istruefor every command that prints a single JSON body, includinginstallandsync. It isfalsefor the streaming commands (mock start,mock record,mock replay,local,receiver): their--jsonemits an NDJSON event stream instead of one object.examplesis a list of{"description", "command"}objects: the# commentabove the example in the text help (""when there is none) and the command. Independentsynheartcommands under one comment are separate entries that share the description; lines that only work together (anexportbeforesynheart login, acd, a pipe) stay one entry, joined by\n.groupis the section a top-level command appears under insynheart --help. It is empty for subcommands.formatslists the--formatvalues the command honours: alwaystext,jsonwhen it prints a single JSON body,ndjsonwhen it takes part in the event stream. A server (mock start,mock record,mock replay,local,receiver) lists["text", "ndjson"], andinstallandsynclist all three.requires_auth,network,writes_files,destructive,long_runningandinteractivesay what running the command involves, so an agent can decide before it runs.requires_authmeans an account.networkmeans a call to Synheart’s servers or the internet (local listeners do not count).writes_filesmeans files are created or changed (the CLI’s own caches, such as the credential refreshwhoamimay do, do not count).destructivemeans something is deleted or revoked for good.long_runningmeans it runs until stopped.interactivemeans a person at the keyboard: a browser sign-in, a confirmation, sudo,guard allowor the interactive UI, which agent mode fails on instead of prompting. A parent group that only prints help has all sixfalse.exit_codesandenvlist the exit codes and the environment variables the CLI reads.
Check the setup with doctor
synheart doctor --json reports each check as an entry in checks[]:
okistruewhen no check has statuserror.summarycounts the checks by status.scenarios_diris left out when there is no local scenarios directory.statusisok,warnorerror.fix.commandis the exact command that resolves the check.safe_to_runfollows the same rule as the error envelope’sfix: it istruewhen 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, sosynheart install runtime,synheart syncandsynheart mock start --port …arefalse. When it isfalse, ask a person before running it, or run it once you have decided to.needs_humanistruewhen a person has to take part, such assynheart login, which opens a browser.fix.requireslists 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 (noPackage.swift,build.gradleorpubspec.yaml, and no.synheart/here or above) a missingsynheart.lockis not a warning. The report notesNot in an app project · cd into your app, or run synheart initinstead.doctorexits 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.
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
- Claude Code
- Cursor / Claude Desktop
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 onessynheart 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:synheart_initsets up the app project. It refuses your home directory (SH-CFG-006) and never overwrites a backup.synheart_doctorchecks the setup. Each check’sfixsays what to run next.synheart_mock_list_scenariosandsynheart_mock_describepick a scenario.synheart_mock_startstreams mock data and returns its endpoints.synheart_connect_infogives the WebSocket, SSE, UDP and control URLs and a client snippet for the app.synheart_mock_statusshows whether the app has connected (clients,ever_connected).synheart_mock_stopends the stream.
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_startfails withSH-MOCK-005(usage, exit 2). Stop it first, or keep using it. - It ends on
synheart_mock_stop, when itsdurationruns 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.commandsuggests 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’sisError: 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 --httpsandlocal cleanup(sudo), anduiandsyni(a terminal UI or chat). - Commands that install or fetch artifacts:
install,sync,runtime installandruntime upgrade, andguard 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_doctornames them as fixes. - Other long-running servers:
mock record,mock replay,localandreceiver. They write files or serve a platform.synheart_mock_startcovers building against mock data. - Platform commands (
org,project,api-key,usage) andlogout: account-level changes outside the first-hour loop. - Resources, prompts and sampling are not offered, and the transport is stdio only.
Recipes
Bootstrap an app project
An agent sets up a Flutter or native app project from a clean checkout:synheart doctor --json again at the end. "ok": true means the app can run.