# CLI reference

> The sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.

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

For agents: Overview of the sypnia CLI: one binary that is both the engine (serve, aggregate, migrate, doctor) and its client (project, key, token, sourcemaps upload, problems, problem); install methods, environment variables, exit codes.

**\[Engine]** **\[Cloud]** `sypnia` is one program. It is the engine itself (`sypnia serve`) and the tool you use around it: create projects and tokens, upload source maps from your build, read problems from a terminal.

| You want to                                 | Command                                          | Works with                                                   |
| ------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------ |
| Run the engine on your own server           | `sypnia serve`, `migrate`, `doctor`, `aggregate` | A self-hosted engine                                         |
| Create projects, ingest keys and API tokens | `sypnia project`, `key`, `token`                 | A self-hosted engine. `key` and `token` also on Sypnia Cloud |
| Upload source maps in your build            | `sypnia sourcemaps upload`                       | Both                                                         |
| See what is failing, from a terminal        | `sypnia problems`, `sypnia problem`              | Both                                                         |

If you use Sypnia Cloud and a framework SDK such as `@sypnia/next`, you may never need the CLI: the SDK uploads source maps by itself and the app does the rest.

## Install

**Script**

```bash
curl -fsSL https://sypnia.com/install.sh | sh
```

Linux and macOS, x86-64 and ARM. Installs to `~/.local/bin/sypnia`.

**Docker**

```bash
docker run --rm ghcr.io/sypnia/sypnia:1 version
```

The image holds the same binary. Its default command is `serve`.

**npm**

```bash
npx sypnia version
```

For JavaScript projects and CI. The `sypnia` package downloads the binary for your platform.

Check it:

```bash
sypnia version
```

**You should see:**`sypnia 1.0.0 (a1c9e3f, 2026-03-01) schema 12`

## Say where and who

Commands that talk to the API need to know which engine and which credential. They read them from the environment.

| Variable            | Used by       | Meaning                                                                                                                                                                                               |
| ------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SYPNIA_BASE_URL`   | admin, client | Where the API is. For a self-hosted engine, its base URL, without `/v1`. On the engine's own machine it is also the setting that says the engine's public address. Default: `https://api.sypnia.com`. |
| `SYPNIA_API_TOKEN`  | admin, client | An API token (`sps_…`). `read` for `problems` and `problem`; `admin` for `sourcemaps upload`, `key` and `token`.                                                                                      |
| `SYPNIA_ROOT_TOKEN` | admin         | The root token of a self-hosted engine. Needed for `project create` and `project delete`. When both tokens are set, admin commands use the root token.                                                |
| `SYPNIA_PROJECT`    | admin, client | A project id or slug. Needed only with the root token; an API token already belongs to one project. The same as `--project`.                                                                          |
| `SYPNIA_CONFIG`     | engine        | Path of the configuration file. The same as `--config`.                                                                                                                                               |
| `SYPNIA_…`          | engine        | Every setting of the engine. See the configuration reference.                                                                                                                                         |

`Against Sypnia Cloud`

```bash
export SYPNIA_API_TOKEN=<your API token>
sypnia problems
```

`Against your own engine`

```bash
export SYPNIA_BASE_URL=https://sypnia.example.com
export SYPNIA_API_TOKEN=<your API token>
sypnia problems
```

The CLI never stores a token. It has no `login` command and writes no configuration file of its own.

## Output

By default the CLI prints for people: tables, colours, short sentences. Add `--json` to any command that reads data and it prints exactly what the HTTP API returns, so a script can use it:

```bash
sypnia problems --json | jq '.data[].slug'
```

Errors go to standard error, as one line: the API's `code` and `message`.

## Exit codes

The same on every command, so a script can tell what went wrong.

| Code | Meaning                                                                                                                                |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `0`  | Success.                                                                                                                               |
| `1`  | The command ran and the answer is no: a `doctor` check failed, an upload failed, the API answered an error not listed below.           |
| `2`  | Wrong usage: an unknown flag, a missing argument. Nothing was done.                                                                    |
| `3`  | Wrong configuration: a required setting is missing or invalid, or the database schema is older than the binary (run `sypnia migrate`). |
| `4`  | Cannot reach something: the database, the storage, the API or the network. Safe to retry.                                              |
| `5`  | Not allowed: the token is missing, unknown, revoked, or lacks the scope (`401`, `403`).                                                |
| `6`  | Not found: no such project, problem, key or token (`404`).                                                                             |

## Commands
