# Commands

> Every command of the sypnia binary, with its flags, examples, output and exit codes.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/cli/commands/

For agents: Reference of the sypnia CLI: serve, aggregate, migrate, doctor, project, key, token, sourcemaps upload, problems, problem, version; flags, environment variables, example output and exit codes.

Every command of `sypnia`, in three groups. Each command says where it works: **\[Engine]** on a self-hosted engine, **\[Cloud]** against Sypnia Cloud. How to install the binary, the variables it reads and what its exit codes mean are on the [CLI overview](https://docs.sypnia.com/cli).

| Command                                   | What it does                                          |
| ----------------------------------------- | ----------------------------------------------------- |
| `sypnia serve`                            | Run the engine                                        |
| `sypnia aggregate`                        | Process what has arrived, once                        |
| `sypnia migrate`                          | Create or update the database tables                  |
| `sypnia doctor`                           | Check that the engine is set up correctly             |
| `sypnia project create`, `list`, `delete` | Manage projects                                       |
| `sypnia key create`, `list`, `revoke`     | Manage ingest keys                                    |
| `sypnia token create`, `list`, `revoke`   | Manage API tokens                                     |
| `sypnia sourcemaps upload`                | Upload a build's source maps and register its release |
| `sypnia problems`                         | List problems                                         |
| `sypnia problem`                          | Show one problem, or print its ready prompt           |
| `sypnia version`                          | Print the version                                     |

## Flags of every command

**Flags:**

- `--json` (boolean): Print the result as JSON, in the same shape as the HTTP API. Tables and colours are for people; scripts should use this.
- `--quiet, -q` (boolean): Print only errors.
- `--no-color` (boolean): No colours. Also when `NO_COLOR` is set or the output is not a terminal.
- `--config <file>` (path): Engine commands only. A configuration file in TOML. Environment variables win over the file. Also `SYPNIA_CONFIG`.
- `--help, -h` (boolean): Explain the command and its flags.

## Run the engine

These commands run where the engine runs. They read the engine's configuration (see the [configuration reference](https://docs.sypnia.com/self-hosting/configuration)) and need the database and the storage.

### `sypnia serve`

\[Engine]

**Run the engine.**

Starts everything in one process: the HTTP API, the ingest and OTLP endpoints, the MCP server, the Console and
the worker that processes what arrives (problems, sessions, numbers, uptime checks, alerts, webhooks,
retention). This is the whole engine for a Docker deployment.

The worker looks for new failures every `SYPNIA_PROCESSING_INTERVAL_SECONDS` (30 by default), and at once
when ingest in the same process has written new events, so a new problem appears within 2 minutes. It counts
everything else every 5 minutes.

It stops cleanly on `SIGTERM`: it finishes the requests in flight, up to 20 seconds, and the worker finishes its
current step. Processing is idempotent, so a killed worker loses nothing.

To spread the load, run several processes with different roles against the same database and bucket. The AWS
template does this with functions; each function is this same binary with one role.

**Flags:**

- `--listen <address>` (string, default `0.0.0.0:8080`): The address and port to listen on. Also `SYPNIA_LISTEN`.
- `--role <role>` (all | ingest | api | worker, default `all`): `ingest`: only the ingest and OTLP endpoints. `api`: only the API, the MCP server and the Console. `worker`: only processing, no HTTP except `/healthz`. `all`: everything. Also `SYPNIA_ROLE`.

**Run the whole engine:**

```bash
sypnia serve
```

`Output`

```text
sypnia 1.0.0  role=all  listen=0.0.0.0:8080
database  ok  postgres 16.4, schema 12
storage   ok  s3://sypnia-shop (us-east-1)
ai        off (SYPNIA_AI_PROVIDER=none)
ready     https://sypnia.example.com
```

**Run ingest and worker apart:**

```bash
sypnia serve --role ingest --listen 0.0.0.0:8081
sypnia serve --role worker
```

Exit codes: `0`, `3`, `4`.

### `sypnia aggregate`

\[Engine]

**Process what has arrived, once.**

Runs one pass of the worker and exits: reads the raw events that arrived since the last pass, groups failures
into problems, assembles sessions, updates the numbers, runs due uptime checks, creates alerts and sends
webhooks. `sypnia serve` does this by itself every 30 seconds; you only need this command to process from your
own scheduler (run it every minute), or to process a time range again with `--from` and `--to`.

Processing a range again is safe, and nothing is counted twice. Numbers kept per hour (page and API
performance) are replaced with what the raw events of that hour give. Counters that only ever add (a session's
totals, daily click counts, usage, a problem's occurrences) are not replaced: the engine keeps a ledger of the
raw objects it has already added, and adds each one once.

**Flags:**

- `--project <id or slug>` (string): Only this project. All projects when left out.
- `--from <time>` (string): Process again from this moment: an ISO 8601 timestamp or a relative value (`6h`, `2d`). Needs `--to` or defaults it to now.
- `--to <time>` (string): End of the range to process again.
- `--task <task>` (all | events | uptime | alerts | webhooks | retention | suggestions, default `all`): Run only one part of the pass. `suggestions` runs the weekly suggestions now, for the week that ended.
- `--watch` (boolean): Keep running and pass again every `SYPNIA_PROCESSING_INTERVAL_SECONDS`. The same as `serve --role worker` without `/healthz`.

**One pass:**

```bash
sypnia aggregate
```

`Output`

```text
shop  events 412 -> 2 sessions, 1 problem (0 new), 3 routes   0.8 s
shop  uptime 1 check, 0 down
shop  alerts 0 created, webhooks 0 sent
done in 1.1 s, data through 2026-03-12T10:34:10Z
```

**Process yesterday again for one project:**

```bash
sypnia aggregate --project shop --from 2026-03-11T00:00:00Z --to 2026-03-12T00:00:00Z
```

Exit codes: `0`, `1`, `3`, `4`.

### `sypnia migrate`

\[Engine]

**Create or update the database tables.**

Applies the database migrations the binary carries, in order, each in a transaction. Run it once after
installing and after every upgrade, before starting the new version. Migrations only add: an older binary keeps
working against a newer schema, so you can upgrade without stopping.

`sypnia serve` refuses to start against a schema older than itself (exit code 3), unless
`SYPNIA_AUTO_MIGRATE` is `true`.

**Flags:**

- `--status` (boolean): Show which migrations are applied and which are pending, and change nothing.
- `--dry-run` (boolean): Print the SQL that would run, and change nothing.

**Apply pending migrations:**

```bash
sypnia migrate
```

`Output`

```text
schema 11 -> 12
applied 0012_suggestions  (0.2 s)
database is up to date
```

Exit codes: `0`, `3`, `4`.

### `sypnia doctor`

\[Engine]

**Check that the engine is set up correctly.**

Reads the configuration and tests every piece the engine depends on, one line each: the settings themselves,
the database (reachable, Postgres 15 or later, schema up to date), the storage (writes, reads and deletes a
test object, and signs a link), the public address, the AI provider (one small request to the model you
configured) and the alert webhook (sends a signed `ping`). Each failure says what is wrong and which setting to
change.

Run it after installing, after changing a setting, and first when something does not work. The AI check sends
about 20 tokens to your provider; skip it with `--skip ai`.

**Flags:**

- `--only <checks>` (string): Comma-separated checks to run: `config`, `database`, `storage`, `address`, `ai`, `webhook`, `clock`.
- `--skip <checks>` (string): Comma-separated checks to leave out.

**Check everything:**

```bash
sypnia doctor
```

`Output`

```text
config    ok    14 settings read, 0 unknown
database  ok    postgres 16.4, schema 12 (up to date), 3 ms
storage   ok    s3://sypnia-shop: put, get, delete, presign
address   ok    https://sypnia.example.com/healthz answered 200
ai        ok    openrouter, model <model>: answered in 0.9 s
webhook   skip  SYPNIA_ALERT_WEBHOOK_URL is not set (alerts are recorded only)
clock     ok    0.2 s from the database's clock
all checks passed
```

**When the model name is wrong:**

```bash
sypnia doctor --only ai
```

`Output`

```text
ai        FAIL  openrouter answered 404: no model named "<model>"
                Set SYPNIA_AI_MODEL to a model your provider offers.
1 check failed
```

Exit codes: `0`, `1`, `3`.

## Projects, keys and tokens

These commands call the HTTP API, so they work from any machine. On a self-hosted engine use the root token (`SYPNIA_ROOT_TOKEN`) and say which engine with `SYPNIA_BASE_URL`. On Sypnia Cloud, `key` and `token` work with an `admin` API token; projects are created in the app.

### `sypnia project create`

\[Engine]

**Create a project.**

Creates a project and prints its first ingest key. Self-hosted engines only; needs the root token. On Sypnia Cloud, create projects in the app.

Calls: `POST /v1/projects`

**Flags:**

- `--name <name>` (string, required): The name people see.
- `--slug <slug>` (string): A short name for URLs and commands. Defaults to the name in lowercase with hyphens.
- `--timezone <zone>` (string, default `UTC`): An IANA time zone, such as `America/Bogota`. Days are cut in it.

**Create the shop's project:**

```bash
sypnia project create --name Shop
```

`Output`

```text
project     shop (prj_5k2m9x4q7w1z)
ingest key  spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e

Put the ingest key in your app. It is public: it can only send.
Next: sypnia token create --project shop --name "My laptop" --scopes read,replay
```

Exit codes: `0`, `1`, `4`, `5`.

### `sypnia project list`

\[Engine, Cloud]

**List projects.**

With the root token, every project of the engine. With an API token, the one project it belongs to.

Calls: `GET /v1/projects`

**Flags:**

None.

**List projects:**

```bash
sypnia project list
```

`Output`

```text
SLUG  ID                NAME  CREATED     ENVIRONMENTS
shop  prj_5k2m9x4q7w1z  Shop  2026-02-02  production, development
```

Exit codes: `0`, `4`, `5`.

### `sypnia project delete`

\[Engine]

**Delete a project and all of its data.**

Deletes the project for good. It asks you to type the slug again, unless you pass `--yes`. Self-hosted engines only; needs the root token.

Calls: `DELETE /v1/projects/{project_ref}`

**Arguments:**

- `<slug>` (string, required): The project's slug or id.

**Flags:**

- `--yes` (boolean): Do not ask. For scripts.

**Delete a test project:**

```bash
sypnia project delete playground --yes
```

Exit codes: `0`, `4`, `5`, `6`.

### `sypnia key create`

\[Engine, Cloud]

**Create an ingest key.**

Creates another ingest key for a project. Give each app or platform its own.

Calls: `POST /v1/keys`

**Flags:**

- `--project <id or slug>` (string): The project. Needed with the root token. Also `SYPNIA_PROJECT`.
- `--name <name>` (string, required): What the key is for.
- `--rate-limit <n>` (integer, default `600`): Requests a minute accepted from one address with this key. 10 to 6000.

**A key for the API server:**

```bash
sypnia key create --project shop --name "Checkout API"
```

`Output`

```text
key_8b5n2m7v4c1x  spk_a3c9e1f7b5d2084c6e0a9f3b7d1c5e82  Checkout API
```

Exit codes: `0`, `1`, `4`, `5`, `6`.

### `sypnia key list`

\[Engine, Cloud]

**List a project's ingest keys.**

Shows every key, including revoked ones. Ingest keys are public, so they are printed in full.

Calls: `GET /v1/keys`

**Flags:**

- `--project <id or slug>` (string): The project. Needed with the root token. Also `SYPNIA_PROJECT`.

**List keys:**

```bash
sypnia key list --project shop
```

`Output`

```text
ID                KEY                                   NAME     LAST USED         STATUS
key_3n8v2c6b1m4x  spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e  Web app  2026-03-12 10:00  active
```

Exit codes: `0`, `4`, `5`, `6`.

### `sypnia key revoke`

\[Engine, Cloud]

**Revoke an ingest key.**

Revokes a key. Apps that still use it stop sending within one minute. A project's last active key cannot be revoked.

Calls: `DELETE /v1/keys/{key_id}`

**Arguments:**

- `<key_id>` (string, required): The key's record id (`key_…`), from `key list`.

**Flags:**

- `--project <id or slug>` (string): The project. Needed with the root token. Also `SYPNIA_PROJECT`.

**Revoke a key:**

```bash
sypnia key revoke key_8b5n2m7v4c1x --project shop
```

Exit codes: `0`, `1`, `4`, `5`, `6`.

### `sypnia token create`

\[Engine, Cloud]

**Create an API token.**

Creates an API token and prints its secret once. Copy it now; it cannot be shown again.

Calls: `POST /v1/tokens`

**Flags:**

- `--project <id or slug>` (string): The project. Needed with the root token. Also `SYPNIA_PROJECT`.
- `--name <name>` (string, required): Who or what will use the token.
- `--scopes <list>` (string, required): Comma-separated: `read`, `replay`, `admin`. Give the fewest that do the job.
- `--expires <time>` (string): When the token stops working: a relative value (`90d`) or an ISO 8601 timestamp. It never expires when left out.

**A token for your coding agent:**

```bash
sypnia token create --project shop --name Cursor --scopes read
```

`Output`

```text
tok_9r4t6y2u8i1o  Cursor  read
sps_4Kq9Zt2MxV7bN1cR5wY8pL3dF6hJ0sA2gE4uT9iO

This is the only time the token is shown.
```

**A token for CI, to upload source maps:**

```bash
sypnia token create --project shop --name "CI source maps" --scopes admin --expires 365d
```

Exit codes: `0`, `1`, `4`, `5`, `6`.

### `sypnia token list`

\[Engine, Cloud]

**List a project's API tokens.**

Shows every token with its scopes and when it was last used. Secrets are never shown; the prefix is enough to recognise one.

Calls: `GET /v1/tokens`

**Flags:**

- `--project <id or slug>` (string): The project. Needed with the root token. Also `SYPNIA_PROJECT`.

**List tokens:**

```bash
sypnia token list --project shop
```

`Output`

```text
ID                NAME    PREFIX        SCOPES        LAST USED         EXPIRES  STATUS
tok_9r4t6y2u8i1o  Cursor  sps_4Kq9Zt2M  read, replay  2026-03-12 10:00  never    active
```

Exit codes: `0`, `4`, `5`, `6`.

### `sypnia token revoke`

\[Engine, Cloud]

**Revoke an API token.**

Revokes a token. Requests with it are refused within one minute.

Calls: `DELETE /v1/tokens/{token_id}`

**Arguments:**

- `<token_id>` (string, required): The token's record id (`tok_…`), from `token list`.

**Flags:**

- `--project <id or slug>` (string): The project. Needed with the root token. Also `SYPNIA_PROJECT`.

**Revoke a token:**

```bash
sypnia token revoke tok_9r4t6y2u8i1o --project shop
```

Exit codes: `0`, `4`, `5`, `6`.

## Work with a project

These commands call the HTTP API with an API token in `SYPNIA_API_TOKEN`. They work the same against Sypnia Cloud and a self-hosted engine.

### `sypnia sourcemaps upload`

\[Engine, Cloud]

**Upload a build's source maps and register its release.**

Run it in your build, after bundling and before deploying. It does four things:

1. Finds every JavaScript file under the directory and the map each one points to (its `sourceMappingURL`
   comment, or the file next to it ending in `.map`).
2. Registers the release, with what git knows: the commit, the commits since the previous release and the files
   they changed. This is what lets Sypnia say «since yesterday's change».
3. Uploads the maps Sypnia does not have yet, straight to storage.
4. With `--delete-after`, deletes the `.map` files from the directory, so they are never published.

Running it twice is cheap: maps that are already there are skipped. It needs an API token with the `admin`
scope in `SYPNIA_API_TOKEN`; keep it in your CI's secrets.

By default a failure stops your build (exit code 1 or 4). Pass `--allow-failure` if a deploy must never wait
for Sypnia: the command then prints the error and exits 0, and stacks of that release stay minified.

Calls: `POST /v1/releases, POST /v1/releases/{version}/sourcemaps`

**Arguments:**

- `<directory>` (string, required): The build output that holds the JavaScript files and their maps, for example `dist` or `.next/static`.

**Flags:**

- `--release <version>` (string, required): The release's name: the same string your app passes to `init` as `release`. Use the short git commit.
- `--url-prefix <path>` (string, default `/`): The path your site serves the directory from. With `dist/assets/a.js` served as `/assets/a.js`, upload `dist` with `/`, or `dist/assets` with `/assets`.
- `--environment <name>` (string, default `production`): The environment the release is deployed to.
- `--changes <mode>` (git | none, default `git`): `git` sends the commit, the commits since the previous release and the changed files, read from the repository in the current directory. `none` sends only the release's name.
- `--patches` (boolean): Also send each changed file's diff. It makes the analysis sharper. The diffs are your source code: they are stored in your engine, or in Sypnia Cloud, and sent to the AI provider with the analysis.
- `--previous <version>` (string): The release this one replaces. Defaults to the project's latest release in the environment.
- `--delete-after` (boolean): Delete the `.map` files from the directory after a successful upload.
- `--allow-failure` (boolean): Exit 0 even when the upload fails.
- `--dry-run` (boolean): Show what would be registered and uploaded, and send nothing.
- `--concurrency <n>` (integer, default `8`): Uploads at the same time. 1 to 32.

**In a build script:**

```bash
sypnia sourcemaps upload dist --release "$(git rev-parse --short HEAD)" --delete-after
```

`Output`

```text
release   4f2a91c (production), previous 9c1e7b2: 1 commit, 2 files changed
found     42 JavaScript files with a source map
uploaded  41 maps (6.2 MB), skipped 1 already there
deleted   42 .map files from dist
done in 3.4 s
```

Exit codes: `0`, `1`, `2`, `4`, `5`.

### `sypnia problems`

\[Engine, Cloud]

**List problems.**

Prints the project's problems as a table, latest activity first. The same filters as the API. With `--json` it prints what `GET /v1/problems` returns.

Calls: `GET /v1/problems`

**Flags:**

- `--status <status>` (open | resolved | ignored | all, default `open`): Which problems to list.
- `--since <time>` (string, default `30d`): Only problems seen after this moment.
- `--environment <name>` (string, default `production`): The environment to read.
- `--query <text>` (string): Text to find in the sentence, the title or the file.
- `--sort <field>` (last_seen | first_seen | people | occurrences, default `last_seen`): The order.
- `--limit <n>` (integer, default `20`): How many to print. 1 to 200.
- `--project <id or slug>` (string): The project. Needed with the root token. Also `SYPNIA_PROJECT`.

**What is open:**

```bash
sypnia problems
```

`Output`

```text
1 open problem in shop (production)

pay-button-does-nothing   3 people   since today 09:12   release 4f2a91c
  3 people tried to pay today and could not. The Pay button does nothing
  since yesterday's change.
  src/checkout/checkout.tsx:142  confidence high
```

Exit codes: `0`, `4`, `5`.

### `sypnia problem`

\[Engine, Cloud]

**Show one problem.**

Prints one problem: the sentence, who it hit, since when, the cause with its evidence, what to do, and where
to look. With `--context` it adds the stack with source lines, what the person did before and the trace. With
`--prompt` it prints only the ready prompt, as plain text, so you can pipe it into a file or a coding agent.

Calls: `GET /v1/problems/{problem}, /context, /prompt`

**Arguments:**

- `<problem>` (string, required): The problem's slug or id.

**Flags:**

- `--context` (boolean): Also print the stack, the breadcrumbs, the trace and the release's changes.
- `--prompt` (boolean): Print only the ready prompt.
- `--project <id or slug>` (string): The project. Needed with the root token. Also `SYPNIA_PROJECT`.

**Read a problem:**

```bash
sypnia problem pay-button-does-nothing
```

`Output`

```text
pay-button-does-nothing   open   prb_8f3k2m9x4q7w

3 people tried to pay today and could not. The Pay button does nothing
since yesterday's change.

Who         3 people. Two of them tried again and gave up.
Doing       Paying for an order, at the last step of checkout.
Since       Yesterday's change, deployed at 18:40. It worked before.
Cause       Release 4f2a91c renamed the cart's total from cart.total to
            cart.totalCents. The checkout still reads cart.total, so the
            payment goes out without an amount and the API answers 400.
            (confidence: high)
Evidence    4f2a91c:src/cart/cart.ts        renames total to totalCents
            src/checkout/checkout.tsx:142   still passes cart.total
            trace 7c2e9a4b…                 POST /api/checkout answered 400 amount_required
What to do  Read cart.totalCents in confirmPayment(), and show the customer
            a message when a payment is rejected.
Where       src/checkout/checkout.tsx:142  confirmPayment()
Open        https://app.sypnia.com/shop/problems/pay-button-does-nothing
```

**Copy the prompt for your coding agent:**

```bash
sypnia problem pay-button-does-nothing --prompt > fix.md
```

Exit codes: `0`, `4`, `5`, `6`.

### `sypnia version`

\[Engine, Cloud]

**Print the version.**

Prints the binary's version, its commit and the newest database schema it knows. With `--json`, as an object.

**Flags:**

None.

**Version:**

```bash
sypnia version
```

`Output`

```text
sypnia 1.0.0 (a1c9e3f, 2026-03-01) schema 12
```

Exit codes: `0`.
