> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synheart.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# CLI overview
> What the synheart CLI does, how to open its interactive UI, and the flags and settings every command shares.
`synheart` is the command-line tool for building on the Human State Interface (HSI). Use it to:
* Install the Synheart runtime and SDK packages into your app, and pin their versions.
* Stream mock wearable data to your app while you build.
* Run a local copy of the platform for consent and ingest testing.
* Receive HSI exports from a Synheart mobile client over your local network.
* Manage your account, organizations, projects and API keys.
* Let AI coding agents use all of the above safely. See [Use the CLI from AI agents](/cli/agents).
To install the CLI, see [Install the CLI](/setup/install-cli). For the full onboarding flow (account, sign-in, runtime), see the [Setup overview](/setup/overview).
## Workflows
Sign in, install the runtime, and pin exact versions in `synheart.lock` so every machine and CI run matches.
Stream mock Whoop or Garmin data over WebSocket, SSE and UDP, and record or replay sessions.
Run local consent and ingest endpoints, and receive HSI exports from mobile apps.
Commands are grouped the way `synheart --help` groups them. Each group has a generated reference page.
| Group | Commands | Reference |
| - | - | - |
| Build your app | `install`, `sync`, `runtime` | [Build your app](/cli/reference/build-your-app) |
| Simulate & serve | `mock`, `local`, `receiver` | [Simulate & serve](/cli/reference/simulate-and-serve) |
| Platform | `login`, `logout`, `whoami`, `auth`, `org`, `project`, `api-key`, `usage` | [Platform](/cli/reference/platform) |
| AI & agents | `syni`, `mcp`, `guard` | [AI & agents](/cli/reference/ai-and-agents) |
| Troubleshoot | `doctor`, `env`, `config`, `explain`, `version`, `update` | [Troubleshoot](/cli/reference/troubleshoot) |
| Other | `completion`, `ui` | [Other](/cli/reference/other) |
## The interactive UI
Run `synheart` with no arguments in a terminal to open the interactive UI. `synheart ui` (alias `synheart tui`) does the same. The home menu lists every guided flow, grouped as Build, Run locally, Synapse (Guard status, Guard report, Set up guard, Team rules and Dashboard), Account, Cloud (orgs, projects, API keys and Syni) and Tools.
The home screen reads your project without going online:
* **Next** beside the logo suggests the one thing to do now. Missing runtime files come first, then a missing lockfile, then signing in; on a healthy project it suggests starting mock data. The cursor starts on that item, so Enter runs it.
* Menu items carry their state: Sync shows how many runtime files are missing, Doctor how many problems it found, Update an arrow when a release is waiting, and Mock data a dot while something listens on its port.
* In a terminal at least about 110 columns wide, a panel beside the menu describes the focused item and shows the project at a glance: its runtime packages, mock data and your account.
These are the same checks [`synheart doctor`](/cli/reference/troubleshoot) runs, so the two never disagree.
Move with the arrow keys or `h` `j` `k` `l`, and press Enter to open an item. Each item also has a one-key shortcut:
| Key | Opens |
| - | - |
| `i` | Install: what this project has, add packages, reinstall, upgrade, or use a local runtime build |
| `s` | Sync |
| `e` | Env |
| `m` | Mock data |
| `p` | Local platform |
| `v` | HSI receiver |
| `y` | Syni |
| `a` | Sign in (or Sign out when you are signed in) |
| `$` | Usage & plan |
| `d` | Doctor |
| `x` | Explain |
| `c` | Config |
| `,` | Settings (theme, light or dark, motion) |
| `u` | Update |
| `?` | Help (keyboard shortcuts and tips) |
| `q` | Quit |
### Downloads
Install and Sync show overall progress and a bar for each file still downloading. Press `p` to pause and `r` to resume. Files already downloaded are kept, and the rest continues from where it stopped, including after you quit and run the same install again. A stalled or dropped download is retried automatically.
### Copying text
Click and drag to select text on any screen, as in any other terminal program. Inside a screen, `y` copies the most useful thing on it: the highlighted ID in a list, the stream URL or API key on a live view, or the whole page as plain text on results, Doctor, Help and Explain. Over SSH, copying uses your terminal's clipboard support (OSC 52).
The UI leaves the mouse to your terminal, so the scroll wheel moves the cursor or scrolls the page, and `PgUp`/`PgDn` scroll every page. To have the UI handle the wheel itself, set `SYNHEART_MOUSE=1`. Selecting text then needs Shift (Option in macOS terminals) while you drag.
The UI does not open in CI, in a pipe, in [agent mode](/cli/agents), with `--json` or `--quiet`, or when `SYNHEART_NO_TUI=1` is set. In those cases bare `synheart` does not open the UI (in agent and JSON mode it prints the command map instead). `synheart ui` refuses with an error: `TUI is not available with --format json` or `--quiet` for those flags, `SH-TUI-002` in agent mode, and `SH-TUI-001` when there is no terminal, in CI, or when `SYNHEART_NO_TUI=1` is set. Use the ordinary commands in scripts.
## Themes
The CLI and the UI share one colour theme. Pick one with `--theme`, with the `SYNHEART_THEME` environment variable, or with `ui.theme` in `.synheart/config.yaml`. The flag wins over the variable, and the variable wins over the config file.
| Theme | Look |
| - | - |
| `tide` | The orange-to-teal brand gradient: teal structure, orange for the next action. This is the default. |
| `ember` | Warm graphite with a single orange accent. |
| `signal` | Near-monochrome. Orange appears only where you act. |
| `mono` | No colour; bold and dim only. |
```yaml theme={null}
# .synheart/config.yaml
ui:
theme: tide
```
```bash theme={null}
synheart --theme signal doctor
SYNHEART_THEME=tide synheart
```
An unknown theme name fails with `SH-CFG-003`.
Each theme has a dark and a light variant. The CLI detects your terminal background and picks the matching one. To force a variant, set `SYNHEART_THEME_MODE=light` or `SYNHEART_THEME_MODE=dark`. `auto`, the default, detects the background. Any other value fails with `SH-CFG-004`.
Colour turns off when you pass `--no-color`, when `NO_COLOR` is set, when `TERM=dumb`, or when output is not a terminal. In those cases the CLI uses `mono`.
## Motion
The UI plays short animations. They are off in CI, in [agent mode](/cli/agents), and whenever `SYNHEART_REDUCED_MOTION` is set to a truthy value such as `1`.
```bash theme={null}
SYNHEART_REDUCED_MOTION=1 synheart
```
## Global flags
These flags work on every command. They are also listed, with their defaults, on the [command reference](/cli/reference/index#global-flags) page.
| Flag | Purpose |
| - | - |
| `--format text\|json\|ndjson` | Output format. `ndjson` is an event stream, for commands that stream. Agent mode defaults to `json`. |
| `--json` | Shorthand for `--format json`. Combining it with `--format text` is a usage error (exit code 2). |
| `--theme ` | Colour theme: `tide`, `ember`, `signal` or `mono`. |
| `--no-color` | Turn off coloured output. |
| `-q`, `--quiet` | Hide non-essential output. |
| `-v`, `--verbose` | Print extra diagnostic output. It also shows the underlying cause on typed errors. |
### Settings precedence
Commands that read project settings resolve each value in this order, highest first:
1. A command-line flag, such as `--port 9000`.
2. An environment variable.
3. The project config, `.synheart/config.yaml` in the current directory or a parent.
4. The built-in default.
```yaml theme={null}
# .synheart/config.yaml
mock:
port: 9000
host: 127.0.0.1
scenario: workout
vendor: garmin
local:
port: 8090
domain: api.synheart.local
receiver:
port: 7777
host: 127.0.0.1
out: ./exports
scenarios:
dir: ./my-scenarios
ui:
theme: tide
mode: auto # auto, light or dark
motion: on # on or reduced
platform:
org:
tenant:
project:
```
```bash theme={null}
synheart config show # the resolved settings and the file in use
synheart config path # the config file path; exits 1 when there is none
```
`mock`, `local` and `receiver` read their matching section, and `doctor` reads the `mock` section for the port it checks. The `ui` section sets the theme, the light or dark mode and the motion. The `platform` section sets the default organization, tenant and project for `syni` and the `org`, `project`, `api-key` and `usage` commands; the matching `SYNHEART_ORG_ID`, `SYNHEART_TENANT_ID` and `SYNHEART_PROJECT_ID` variables override it.
A user config at `~/.synheart/config.yaml` holds the same `ui` and `platform` settings for every project on your machine. A project config overrides it value by value.
## Mock data
`synheart mock` generates synthetic vendor streams so you can build and test without a wearable. It streams raw vendor-format JSON, the same shape WHOOP and Garmin send. The SDK runtime in your app turns it into HSI.
```bash theme={null}
synheart mock start # whoop, baseline scenario
synheart mock start --vendor garmin --scenario workout
synheart mock start --rate 100hz --duration 5m
synheart mock start --seed 42 # repeatable output
```
By default `mock start` serves three transports from one port setting:
| Transport | Address |
| - | - |
| WebSocket | `ws://127.0.0.1:8787/hsi` (`--port`) |
| Server-Sent Events | `http://127.0.0.1:8788/hsi/sse` (`--port` plus 1) |
| UDP | `udp://127.0.0.1:8789` (`--port` plus 2) |
All three carry the same payload. Add `--web` to open a live dashboard on `--web-port` (default `8790`).
### Record and replay
Record a session to an NDJSON file, then replay it later with the same timing. This is useful for regression tests that need a fixed stream.
```bash theme={null}
synheart mock record --out session.ndjson --vendor whoop --duration 15m --seed 42
synheart mock replay --in session.ndjson --speed 2 --loop
```
`mock start --out ` records while it streams. `mock replay` serves over WebSocket on `--port`.
### Choose a scenario
```bash theme={null}
synheart mock list-scenarios
synheart mock describe baseline
```
A scenario is a named time-series profile. `describe` prints its duration, default rate, signals and phases.
## Local platform server
`synheart local` runs a local copy of the platform endpoints your SDK calls, so you can build without network access or platform quota. It needs no login.
| Setting | Default |
| - | - |
| Port | `8083` (`--port`) |
| API key | `mock-dev-api-key-2026` (`--api-key`) |
| HMAC secret | `mock-dev-hmac-secret-2026` (`--hmac-secret`) |
| Consent profiles | `profiles.json` from `--data-dir` (default: auto-detected) |
| Saved ingests | `~/.synheart/local/ingested/` |
```bash theme={null}
synheart local # plain HTTP on 127.0.0.1:8083
synheart local --port 9000 --api-key my-key # custom credentials
synheart local --https # HTTPS on api.synheart.local
synheart local --web --web-port 8791 # live dashboard
synheart local cleanup # remove the /etc/hosts entries
synheart local cleanup --remove-certs # also remove the local certificates
```
With `--https`, the CLI creates a locally trusted certificate, adds an `/etc/hosts` entry for `--domain` (default `api.synheart.local`) and serves HTTPS on `--https-port` (default `8443`). That step may ask for your password. Undo it with `synheart local cleanup`.
`--host` defaults to `127.0.0.1`. Pass `--host 0.0.0.0` only when you want other devices on your network to reach the server.
## HSI export receiver
`synheart receiver` accepts HSI export payloads that a Synheart mobile client POSTs to `/v1/hsi/import`, for example from the Synheart Life app over your local network. It checks each payload against the HSI Export Schema v1, ignores duplicates, and writes the data to stdout or, with `--out`, to files.
```bash theme={null}
synheart receiver # port 8787, random token
synheart receiver --port 9000 --token my-token
synheart receiver --out ./exports --output-format ndjson --gzip
```
Senders must present the bearer token. Pass `--token`, or let the CLI generate one. The receiver listens on every network interface by default; pass `--host 127.0.0.1` to keep it on your machine.
The payload format flag is `--output-format json|ndjson`. The old `--format ndjson` on `receiver` still works and prints a deprecation note, but `--format` is now the global output flag.
## Debugging the CLI
The CLI has hidden developer flags for profiling itself (`--pprof` and the `--cpu-profile`, `--mem-profile` and `--trace-profile` family). They do not appear in `--help` or `synheart help --json`. You only need them if you are reporting a performance problem with the CLI.
## Where to go next
Agent mode, JSON output, exit codes and the MCP server.
Every command, flag and example, generated from the CLI.
Error codes, environment variables and troubleshooting.
Install on macOS, Linux or Windows.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.