Errors and environment

When a command fails, the CLI prints a typed error. In JSON mode the same information is a JSON body with error_code, class, exit_code, title, error, detail and hint, so scripts and agents can branch on it. See Use the CLI from AI agents.

✗ Not logged in   SH-AUTH-001
  No Synheart credentials found in the keyring or config file.

  TRY
    synheart login

Codes follow SH-<DOMAIN>-<NUMBER>. They are stable: search for them in your shell history, put them in support tickets, and branch on them in scripts. A code is never reassigned to a different meaning.

Error codes

Command line

Code	Meaning	What to do
`SH-CLI-USAGE`	You called the CLI wrong: a bad flag or argument, an unknown command, or `--json` with a different `--format`. Also raised when you pass `--json` to a command with no JSON form, such as `guard allow`. Exit code 2.	Read the usage line the CLI prints (on stderr), or run the command with `--help`.
`SH-MOCK-NOTFOUND`	You named a mock scenario that does not exist. Exit code 4.	Run `synheart mock list-scenarios`.
`SH-EXPLAIN-NOTFOUND`	`synheart explain` has no primer for that topic. Exit code 4.	The error lists the topics, and the hint suggests the closest one.
`SH-MOCK-003`	The rate you typed is not valid. Seen when you change the rate on the interactive mock screen.	Use a frequency like `10hz` or an interval like `100ms`.
`SH-FLAG-REMOVED`	You passed a flag that no longer exists. Exit code 2.	The error names the flag and what replaces it.
`SH-AGENT-001`	The step is interactive, and agent mode never prompts.	Re-run with the flag in the hint, such as `--yes` or `--ci-token`. Set `SYNHEART_AGENT=0` if a person is running the command.
`SH-TUI-001`	`synheart ui` needs a terminal. It does not open in CI, in a pipe, or when `SYNHEART_NO_TUI=1` is set.	Use the ordinary commands, or run it from a terminal.
`SH-TUI-002`	`synheart ui` is off in agent mode.	Use the ordinary commands with `--json`, or `synheart help --json` for the command map.

synheart ui with --json, --format json or --quiet fails with a plain error instead of a code: TUI is not available with --format json (or --quiet).

Code	Meaning	What to do
`SH-AUTH-001`	Not logged in.	`synheart login`
`SH-AUTH-002`	The CLI could not fetch your account info.	Retry. If it persists, run `synheart auth status`.
`SH-AUTH-003`	The credentials file is unreadable.	`synheart auth status` shows the path and permissions.
`SH-AUTH-004`	The CLI could not use the system keyring.	Unlock the OS keyring and retry, or set `SYNHEART_DISABLE_KEYRING`.
`SH-AUTH-005`	You denied the authorization in the browser.	Run `synheart login` again and approve it.
`SH-AUTH-006`	The device code expired before you finished.	Run `synheart login` again.
`SH-AUTH-007`	The CLI could not save your credentials locally.	Check the permissions of `~/.synheart`.
`SH-AUTH-008`	Authorization failed.	Run `synheart login` again.
`SH-AUTH-009`	The refresh token is expired or invalid. Retrying will not help.	`synheart login`
`SH-AUTH-010`	The CLI could not refresh your session, for a temporary reason.	Retry once. If it persists, run `synheart auth status`.
`SH-AUTH-011`	No CI token was supplied.	Set `SYNHEART_CI_TOKEN` or pass `--ci-token`.
`SH-AUTH-012`	The CLI could not save the CI token locally.	Check the permissions of `~/.synheart`.
`SH-AUTH-099`	Login failed for another reason.	Run `synheart auth status`, then `synheart login` again.

Install, sync and runtime

Code	Meaning	What to do
`SH-INST-001`	A package argument is missing, or there are too many.	`synheart install --help`
`SH-INST-002`	There is no `synheart.lock` in the project.	`synheart install runtime`
`SH-INST-003`	The CLI could not read the lockfile.	Check the file, or reinstall with `synheart install runtime`.
`SH-INST-004`	Lockfile drift: the lockfile names an artifact the current manifest no longer has.	Re-pin with the command in the hint, such as `synheart install runtime --version <version>`.
`SH-INST-005`	An artifact’s SHA-256 does not match the lockfile.	Do not use the file. Re-pin with `synheart install`.
`SH-INST-PROJECT`	The CLI could not resolve the project directory.	Check `--project-dir`.
`SH-INST-VARIANT`	The variant is unknown, or `--variant` was used on something that is not a runtime.	Use `edge`, `stable` or `lab` with `install runtime`.
`SH-INST-FORBIDDEN`	Your account is not entitled to that runtime variant.	Install without `--variant`, or check your plan with `synheart usage`.
`SH-INST-EMPTY`	Nothing was installed.	Check that your plan includes the package.
`SH-RT-NOLOCK`	No runtime is installed in this project.	`synheart install runtime`
`SH-RT-INCOMPATIBLE`	The installed runtime does not work with this project’s `synheart_core` version.	Follow the hint, usually `synheart runtime upgrade`.
`SH-RT-FILES`	Runtime files are missing or modified compared with `synheart.lock`.	`synheart sync`
`SH-RT-SYMBOLS`	A runtime library lacks functions its variant must export.	Reinstall the variant: `synheart install runtime`.

Network and registry

Code	Meaning	What to do
`SH-NET-001`	The CLI could not reach the auth service.	Check your connection and retry.
`SH-NET-002`	The CLI could not reach the release manifest.	Check your connection and retry.
`SH-NET-003`	The CLI could not reach the artifact registry, or a download failed.	Check your connection and retry.
`SH-NET-004`	The CLI could not reach the platform API, or it did not answer in time. Exit code 5, so it is safe to retry.	Check your connection and `SYNHEART_API_URL`, then retry. `synheart doctor` checks connectivity.
`SH-REG-404`	The interactive install screen could not find the package.	Try the latest channel, and set a platform if the package is platform-specific.
`SH-REG-429`	The registry is rate limiting the interactive install screen.	Wait a moment and try again.
`SH-REG-000`	The interactive install screen hit another registry error.	Retry. The message carries the registry’s reason.
`SH-SUPPLY-001`	This CLI build does not trust the registry signing key.	Update the CLI: `synheart update`.
`SH-SUPPLY-002`	The registry manifest is not signed.	Do not continue. Contact support.
`SH-SUPPLY-003`	The registry manifest signature is invalid, or could not be verified.	Do not continue. Contact support.
`SH-SUPPLY-004`	The registry manifest is outside its validity window.	Check your system clock, then retry.
`SH-PLATFORM-400`	The platform rejected the request.	Check the arguments.
`SH-PLATFORM-403`	Forbidden. Exit code 3.	Check `--org`, `--tenant`, or `SYNHEART_ORG_ID`.
`SH-PLATFORM-404`	Not found.	`synheart org list` to confirm the resource exists.
`SH-PLATFORM-429`	The platform is rate limiting you. Exit code 5.	Wait a moment and retry.
`SH-PLATFORM-500`	The platform service had an error.	Retry later, or contact support.

The synheart org, project and api-key commands return SH-AUTH-001 for an HTTP 401.

Config, update, usage and Syni

Code	Meaning	What to do
`SH-CFG-002`	No project config was found.	Create `.synheart/config.yaml`. See project settings.
`SH-CFG-003`	The theme name is unknown. The error names where it was set.	Use `tide`, `ember`, `signal` or `mono`.
`SH-CFG-004`	`SYNHEART_THEME_MODE` (or `ui.mode`) is not `auto`, `light` or `dark`.	Set it to `auto`, `light` or `dark`, or unset it.
`SH-CFG-HOME`	The CLI could not find your home directory.	Set `HOME` (or `USERPROFILE` on Windows).
`SH-LOCAL-ADMIN`	On Windows, the interactive local platform screen needs Administrator rights to edit the hosts file for HTTPS mode.	Reopen the terminal with Run as administrator and try again.
`SH-LOCAL-SUDO`	The interactive local platform screen needs administrator rights, and `sudo` cannot prompt inside the full-screen UI.	Quit the UI (`q`) and run the command from a shell, or run `sudo -v` first and try again.
`SH-UPD-MANAGED`	A package manager manages this binary.	Update with the package manager, or pass `--force`.
`SH-UPD-APPLY`	The update failed to apply. The existing binary is untouched.	Retry.
`SH-UPD-ROLLBACK`	The rollback failed.	Reinstall with the installer script.
`SH-UPD-NOPREV`	There is no previous binary to roll back to.	Nothing to do.
`SH-UPD-NOPLATFORM`	The latest manifest has no binary for your OS and architecture.	Check the release page.
`SH-UPD-EXEC`	The CLI could not find its own binary path.	Reinstall with the installer script.
`SH-UPD-ABORT`	You declined the update prompt.	Run `synheart update --yes` to skip the prompt.
`SH-USAGE-001`	There is no organization on this session.	Pass `--org`, or set `SYNHEART_ORG_ID`.
`SH-USAGE-002`	The billing API request failed.	Retry later.
`SH-USAGE-403`	You are not allowed to read usage for this org. Exit code 3.	Check your role.
`SH-USAGE-404`	The usage endpoint was not found.	Check `--org`.
`SH-SYNI-001`	A Syni message is required.	Pass a message to `synheart syni chat`.
`SH-SYNI-002`	A project ID is required to list personas.	Pass `--project`, set `SYNHEART_PROJECT_ID`, or add `project:` under `platform:` in `.synheart/config.yaml`. `synheart project list` shows the ids.
`SH-SYNI-403`	Syni cloud chat is not allowed for this org. Exit code 3.	Check your plan.
`SH-SYNI-404`	The persona or session does not exist. Exit code 4.	`synheart syni personas`, and check the `--session` ID.
`SH-SYNI-429`	You are over your Syni quota.	Wait, or check `synheart usage`.
`SH-SYNI-500`	The Syni API request failed.	Retry later.

Environment variables

The CLI reads these variables. Each is checked against the CLI source.

Variable	Purpose
`SYNHEART_AGENT`	`1` forces agent mode on. `0` forces it off.
`CLAUDECODE`, `CLAUDE_CODE_ENTRYPOINT`, `CURSOR_AGENT`, `CODEX_SANDBOX`, `GEMINI_CLI`, `COPILOT_AGENT`	Set by coding agents. Any of them turns agent mode on.
`SYNHEART_NO_TUI`	`1` stops the interactive UI from opening.
`SYNHEART_MOUSE`	`1` lets the interactive UI capture the mouse for wheel scrolling.
`SYNHEART_NO_UPDATE_CHECK`	`1` turns off the passive update notice.
`SYNHEART_THEME`	Colour theme: `tide`, `ember`, `signal` or `mono`. Same as `--theme`.
`SYNHEART_THEME_MODE`	`auto` (the default), `light` or `dark`. `light` and `dark` skip the terminal background check.
`SYNHEART_REDUCED_MOTION`	A truthy value, such as `1`, turns off animation.
`SYNHEART_API_URL`	Overrides the platform API base URL. The default is `https://api.synheart.ai`.
`SYNHEART_DIST_URL`	Overrides the distribution URL. The default is `https://dist.synheart.ai`.
`SYNHEART_UPDATE_MANIFEST_URL`	Overrides the manifest URL that `synheart update` reads.
`SYNHEART_CI_TOKEN`	A long-lived token for non-interactive `synheart login`. Prefer it over `--ci-token`, because flags show up in process lists and shell history.
`SYNHEART_DISABLE_KEYRING`	Stores credentials in `~/.synheart/credentials.enc` instead of the system keyring.
`SYNHEART_ORG_ID`	Default organization ID for `usage`, `syni`, and the `org`, `project` and `api-key` commands.
`SYNHEART_TENANT_ID`	Default tenant ID for `syni` and the platform commands.
`SYNHEART_PROJECT_ID`	Default project ID for `syni`. Overrides `platform.project` in `.synheart/config.yaml`.
`SYNHEART_INSTALL_JOBS`	Number of parallel downloads for `install` and `sync`, from 1 to 16.
`SYNHEART_ALLOW_ALL_ORIGINS`	`1` lets the mock servers accept browser requests from any origin. By default only non-browser clients, `file://` pages and loopback origins are accepted.
`SYNHEART_INSTALL_DIR`	Read by the installer scripts, not by the CLI. Sets where `synheart` is installed.
`NO_COLOR`	Any value turns off colour. See no-color.org.
`CI`	Any value turns off the interactive UI and update notices.

Two further variables, SYNHEART_INSECURE_SKIP_MANIFEST_VERIFY and SYNHEART_REGISTRY_PINNED_KEYS_FILE, exist only for CLI developers testing against an unsigned or local registry. Never set them in a real environment.

Troubleshooting

Mock stream port already in use

Pass --port to synheart mock start, or check a port with synheart doctor --port 8787. The defaults are 8787 (WebSocket), 8788 (SSE) and 8789 (UDP). --port N moves all three together: WebSocket on N, SSE on N+1, UDP on N+2.

I need the same runtime version in CI

Commit synheart.lock, and run synheart sync in CI. If the lockfile no longer matches the registry, sync fails with SH-INST-004 or SH-INST-005 instead of installing something different. synheart doctor also reports modified runtime files (SH-RT-FILES).

synheart local --https fails to write /etc/hosts

The HTTPS mode adds an /etc/hosts entry and trusts a local certificate, which can need administrator rights. Run it with the permissions the error asks for, or use plain HTTP (synheart local). Undo the changes with synheart local cleanup --remove-certs.

The receiver cannot be reached from my phone

Check that your phone and computer are on the same network, and that your firewall allows the receiver’s port (default 8787). The receiver listens on every interface unless you pass --host. synheart doctor --port 8787 checks that the port is free.

SYNHEART_API_URL is not picked up

The CLI reads environment variables on every run. Check that the variable is exported in the shell that runs the CLI, and run synheart env to confirm.

The colours look wrong on my terminal

Set SYNHEART_THEME_MODE=light or dark if the CLI guessed your background wrongly. Pick another theme with --theme, or turn colour off with NO_COLOR=1.

For anything else, run synheart doctor, and include the output of synheart version --build when you ask for help.

Get Started

Setup

CLI

Synapse

Platform

HSI

Synheart Wear

Synheart Auth

Synheart Core

Synheart Behavior

Syni

Syni Spec

Synheart Session

RAMEN 🍜

Lab Mode

Privacy

Guides

Error codes

Command line

Install, sync and runtime

Network and registry

Config, update, usage and Syni

Environment variables

Troubleshooting

​Error codes

​Command line

​Sign-in

​Install, sync and runtime

​Network and registry

​Config, update, usage and Syni

​Environment variables

​Troubleshooting

Error codes

Command line

Sign-in

Install, sync and runtime

Network and registry

Config, update, usage and Syni

Environment variables

Troubleshooting