CLI reference
The sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.
On this page
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
curl -fsSL https://sypnia.com/install.sh | shLinux and macOS, x86-64 and ARM. Installs to ~/.local/bin/sypnia.
Docker
docker run --rm ghcr.io/sypnia/sypnia:1 versionThe image holds the same binary. Its default command is serve.
npm
npx sypnia versionFor JavaScript projects and CI. The sypnia package downloads the binary for your platform.
Check it:
sypnia versionsypnia 1.0.0 (a1c9e3f, 2026-03-01) schema 12Say 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. |
export SYPNIA_API_TOKEN=<your API token>
sypnia problemsexport SYPNIA_BASE_URL=https://sypnia.example.com
export SYPNIA_API_TOKEN=<your API token>
sypnia problemsThe 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:
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
- Every command with its flags, examples, output and exit codes.
- Every setting the engine commands read.
- Where to put
sypnia sourcemaps uploadin your pipeline.