> ## 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.

# Simulate & serve

> Reference for the synheart commands in the Simulate & serve group.

Every command also accepts the [global flags](/cli/reference/index#global-flags).

## `synheart local`

Run a local copy of the Synheart platform

Starts an HTTP server on your machine that answers the platform endpoints
your SDK calls, so you can develop and test without network access:

```text theme={null}
GET  /api/v1/apps/{id}/consent-profiles
POST /api/v1/sdk/consent-token
POST /api/v1/sdk/consent-revoke
POST /v1/ingest/hsi
POST /v1/platform/session/ingest
POST /v1/platform/metadata/ingest
GET  /status
```

Runs until you press Ctrl+C. Pass --https to serve HTTPS on a local domain with
a locally trusted certificate; that adds an /etc/hosts entry and may ask for
your password. Undo it with 'synheart local cleanup'. Port, host and domain
fall back to the local section of .synheart/config.yaml. Needs no login.

**Usage**

```bash theme={null}
synheart local [flags]
```

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--api-key` | `string` | `mock-dev-api-key-2026` | API key the consent endpoints accept |
| `--data-dir` | `string` | - | Directory containing profiles.json (default: auto-detected) |
| `--domain` | `string` | `api.synheart.local` | Local domain name for HTTPS mode |
| `--hmac-secret` | `string` | `mock-dev-hmac-secret-2026` | Secret used to verify ingest signatures (HMAC) |
| `--host` | `string` | `127.0.0.1` | Address to bind to; 0.0.0.0 exposes the server on your network |
| `--https` | `bool` | `false` | Serve HTTPS with a locally trusted certificate and an /etc/hosts entry |
| `--https-port` | `int` | `8443` | Port for the HTTPS reverse proxy |
| `--port` | `int` | `8083` | Port to listen on |
| `--web` | `bool` | `false` | Serve the web dashboard for real-time visualization |
| `--web-port` | `int` | `8790` | Port for the web dashboard |

**Subcommands**

* `synheart local cleanup`: Undo the setup that local --https made

**Examples**

```bash theme={null}
# Start on 127.0.0.1:8083
synheart local
# Use another port and open the live dashboard
synheart local --port 9000 --web
# Serve HTTPS on api.synheart.local
synheart local --https
```

### `synheart local cleanup`

Undo the setup that local --https made

Removes the "# synheart" entries that 'synheart local --https' added to
/etc/hosts. Add --remove-certs to also delete the locally generated
certificates and stop trusting the local CA. Removing hosts entries may need
elevated permissions. Needs no login and no network. Progress goes to stderr.

**Usage**

```bash theme={null}
synheart local cleanup [flags]
```

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--remove-certs` | `bool` | `false` | Also remove certificates and untrust the local CA |

**Examples**

```bash theme={null}
# Remove the hosts entries
synheart local cleanup
# Remove certificates and the CA trust as well
synheart local cleanup --remove-certs
```

**JSON output:** not supported. This command does not print a JSON body.

## `synheart mock`

Generate and replay mock wearable data

Generates, records and replays mock HSI sensor data, so you can build
against the Human State Interface without a wearable. Needs no login and no
network.

'synheart mock' on its own prints this help; use the subcommands to run it.
For the guided mock flow, open 'synheart ui'.

**Usage**

```bash theme={null}
synheart mock
```

**Subcommands**

* `synheart mock describe`: Show a scenario's signals and phases
* `synheart mock list-scenarios`: List the available mock scenarios
* `synheart mock record`: Record mock wearable data to a file
* `synheart mock replay`: Replay a recorded mock session
* `synheart mock start`: Stream mock wearable data to your app

**Examples**

```bash theme={null}
# Stream the baseline scenario to your app
synheart mock start
# See which scenarios exist, then inspect one
synheart mock list-scenarios
synheart mock describe baseline
# Record a session, then play it back
synheart mock record --out session.ndjson
synheart mock replay --in session.ndjson
```

### `synheart mock describe`

Show a scenario's signals and phases

Prints one scenario in detail: its duration, default rate, the signals it
generates with their baselines, noise and units, and its phases with any
overrides. Use it to choose a scenario before you run it. Needs no login and no
network. With --json it prints the same details as an object.

**Usage**

```bash theme={null}
synheart mock describe <scenario>
```

**Aliases:** `scenario`, `scen`

**Examples**

```bash theme={null}
# Describe a scenario
synheart mock describe baseline
# As JSON
synheart mock describe baseline --json
```

**JSON output:** supported. Add `--json` (or `--format json`) to print a machine-readable body.

### `synheart mock list-scenarios`

List the available mock scenarios

Lists every scenario that 'synheart mock start' and 'mock record' can run,
each with a one-line description. Use it to find a scenario name. Needs no
login and no network. With --json it prints an object with an "items" array of
name and description.

**Usage**

```bash theme={null}
synheart mock list-scenarios
```

**Aliases:** `scenarios`, `ls`

**Examples**

```bash theme={null}
# List scenarios
synheart mock list-scenarios
# As JSON
synheart mock list-scenarios --json
```

**JSON output:** supported. Add `--json` (or `--format json`) to print a machine-readable body.

### `synheart mock record`

Record mock wearable data to a file

Generates sensor events for a scenario and writes them to an NDJSON file
without serving them, so you can replay the same session later with
'synheart mock replay'. Pass --seed to get the same data every time. Needs no
login and no network.

Scenario and vendor fall back to the mock section of .synheart/config.yaml when
you do not pass them.

**Usage**

```bash theme={null}
synheart mock record [flags]
```

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--duration` | `string` | `5m` | How long to record, such as 30s or 5m |
| `--out` | `string` | - | File to write the NDJSON recording to (required) |
| `--rate` | `string` | `50hz` | Tick rate for the generated signals, such as 50hz |
| `--scenario` | `string` | `baseline` | Scenario to record; list them with 'synheart mock list-scenarios' |
| `--seed` | `int64` | - | Random seed for repeatable output; defaults to the current time |
| `--vendor` | `string` | `whoop` | Vendor data format: whoop or garmin |

**Examples**

```bash theme={null}
# Record five minutes of the baseline scenario
synheart mock record --out baseline.ndjson
# Record half an hour of Garmin data, repeatably
synheart mock record --out run.ndjson --scenario workout --vendor garmin --duration 30m --seed 42
```

**JSON output:** not supported. This command does not print a JSON body.

### `synheart mock replay`

Replay a recorded mock session

Reads a recording made with 'synheart mock record' (or 'mock start --out')
and serves its events over WebSocket on --port, with the original timing scaled
by --speed. Use it to run the same session against your app again and again.
Needs no login and no network. Press Ctrl+C to stop.

Host and port fall back to the mock section of .synheart/config.yaml when you
do not pass them.

**Usage**

```bash theme={null}
synheart mock replay [flags]
```

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--host` | `string` | `127.0.0.1` | Address to bind to |
| `--in` | `string` | - | Recorded NDJSON file to replay (required) |
| `--loop` | `bool` | `false` | Restart from the beginning when the recording ends |
| `--port` | `int` | `8787` | Port to listen on |
| `--speed` | `float64` | `1` | Playback speed multiplier (2 is twice as fast) |

**Examples**

```bash theme={null}
# Replay a recording once
synheart mock replay --in workout.ndjson
# Replay at double speed, forever
synheart mock replay --in workout.ndjson --speed 2 --loop
```

**JSON output:** not supported. This command does not print a JSON body.

### `synheart mock start`

Stream mock wearable data to your app

Generates sensor events for a scenario and serves them over WebSocket (on
\--port), Server-Sent Events (--port plus 1) and UDP (--port plus 2) until you
press Ctrl+C or --duration ends. Connect your app's SDK to one of them.

Use --vendor garmin for Garmin-format payloads (the default is whoop), --out
to record the stream as NDJSON, and --web to open a live dashboard in your
browser. Port, host, scenario and vendor fall back to the mock section of
.synheart/config.yaml when you do not pass them. Needs no login and no
network.

**Usage**

```bash theme={null}
synheart mock start [flags]
```

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--duration` | `string` | - | How long to run, such as 5m or 1h (default: the scenario's own duration) |
| `--host` | `string` | `127.0.0.1` | Address to bind to |
| `--out` | `string` | - | Also record events to this file |
| `--port` | `int` | `8787` | Port to listen on |
| `--rate` | `string` | `50hz` | Tick rate for the generated signals, such as 50hz |
| `--scenario` | `string` | `baseline` | Scenario to run; list them with 'synheart mock list-scenarios' |
| `--seed` | `int64` | - | Random seed for repeatable output; defaults to the current time |
| `--vendor` | `string` | `whoop` | Vendor data format: whoop or garmin |
| `--web` | `bool` | `false` | Serve the web dashboard for real-time visualization |
| `--web-port` | `int` | `8790` | Port for the web dashboard (the SSE stream uses --port plus 1) |

**Examples**

```bash theme={null}
# Stream the baseline scenario on 127.0.0.1:8787
synheart mock start
# Open the live dashboard as well
synheart mock start --web
# A stressful hour of Garmin-format data, recorded to a file
synheart mock start --scenario stress --vendor garmin --duration 1h --out stress.ndjson
```

**JSON output:** not supported. This command does not print a JSON body.

## `synheart receiver`

Receive HSI export payloads over HTTP

Starts an HTTP server that accepts HSI export payloads POSTed to
/v1/hsi/import, for example from the Synheart Life app over your local network.
Each payload is checked against the HSI Export Schema v1, duplicates are
ignored, and the data is written to stdout or, with --out, to files. Runs until
you press Ctrl+C.

Senders must present a bearer token: pass --token, or let it generate one.
It listens on every network interface by default; use --host 127.0.0.1 to keep
it on this machine. Host, port and out fall back to the receiver section of
.synheart/config.yaml. Needs no login.

**Usage**

```bash theme={null}
synheart receiver [flags]
```

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--gzip` | `bool` | `false` | Accept gzip-compressed payloads |
| `--host` | `string` | `0.0.0.0` | Address to bind to; 0.0.0.0 listens on every network interface |
| `--out` | `string` | - | Directory to write received payloads to (default: print to stdout) |
| `--output-format` | `string` | `json` | Payload output format: json or ndjson |
| `--port` | `int` | `8787` | Port to listen on |
| `--token` | `string` | - | Bearer token that senders must present (default: a random token is generated) |

**Examples**

```bash theme={null}
# Print received payloads to stdout
synheart receiver
# Write NDJSON files to ./exports, with a token you choose
synheart receiver --out ./exports --output-format ndjson --token mysecret
# Accept gzip payloads on another port
synheart receiver --port 9000 --gzip
```

**JSON output:** not supported. This command does not print a JSON body.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.