CLI overview

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.

To install the CLI, see Install the CLI. For the full onboarding flow (account, sign-in, runtime), see the Setup overview.

Workflows

SDK artifact install

Local app testing

Stream mock Whoop or Garmin data over WebSocket, SSE and UDP, and record or replay sessions.

Offline platform

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
Simulate & serve	`mock`, `local`, `receiver`	Simulate & serve
Platform	`login`, `logout`, `whoami`, `auth`, `org`, `project`, `api-key`, `usage`	Platform
AI & agents	`syni`, `mcp`, `guard`	AI & agents
Troubleshoot	`doctor`, `env`, `config`, `explain`, `version`, `update`	Troubleshoot
Other	`completion`, `ui`	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 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, 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.

# .synheart/config.yaml
ui:
  theme: tide

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, and whenever SYNHEART_REDUCED_MOTION is set to a truthy value such as 1.

SYNHEART_REDUCED_MOTION=1 synheart

Global flags

These flags work on every command. They are also listed, with their defaults, on the command reference 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 <name>`	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:

A command-line flag, such as --port 9000.
An environment variable.
The project config, .synheart/config.yaml in the current directory or a parent.
The built-in default.

# .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: <org-id>
  tenant: <tenant-id>
  project: <project-id>

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.

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.

synheart mock record --out session.ndjson --vendor whoop --duration 15m --seed 42
synheart mock replay --in session.ndjson --speed 2 --loop

mock start --out <file> records while it streams. mock replay serves over WebSocket on --port.

Choose a scenario

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/`

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.

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

Use the CLI from AI agents

Agent mode, JSON output, exit codes and the MCP server.

Command reference

Every command, flag and example, generated from the CLI.

Errors and environment

Error codes, environment variables and troubleshooting.

Install the CLI

Install on macOS, Linux or Windows.

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

Workflows

SDK artifact install

Local app testing

Offline platform

The interactive UI

Downloads

Copying text

Themes

Motion

Global flags

Settings precedence

Mock data

Record and replay

Choose a scenario

Local platform server

HSI export receiver

Debugging the CLI

Where to go next

Use the CLI from AI agents

Command reference

Errors and environment

Install the CLI

​Workflows

SDK artifact install

Local app testing

Offline platform

​The interactive UI

​Downloads

​Copying text

​Themes

​Motion

​Global flags

​Settings precedence

​Mock data

​Record and replay

​Choose a scenario

​Local platform server

​HSI export receiver

​Debugging the CLI

​Where to go next

Use the CLI from AI agents

Command reference

Errors and environment

Install the CLI

Workflows

The interactive UI

Downloads

Copying text

Themes

Motion

Global flags

Settings precedence

Mock data

Record and replay

Choose a scenario

Local platform server

HSI export receiver

Debugging the CLI

Where to go next