Docs

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 EngineCloud At launch

View as Markdown
On this page
  1. Install
  2. Say where and who
  3. Output
  4. Exit codes
  5. Commands

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 toCommandWorks with
Run the engine on your own serversypnia serve, migrate, doctor, aggregateA self-hosted engine
Create projects, ingest keys and API tokenssypnia project, key, tokenA self-hosted engine. key and token also on Sypnia Cloud
Upload source maps in your buildsypnia sourcemaps uploadBoth
See what is failing, from a terminalsypnia problems, sypnia problemBoth

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

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

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

Check it:

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

VariableUsed byMeaning
SYPNIA_BASE_URLadmin, clientWhere 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_TOKENadmin, clientAn API token (sps_…). read for problems and problem; admin for sourcemaps upload, key and token.
SYPNIA_ROOT_TOKENadminThe 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_PROJECTadmin, clientA project id or slug. Needed only with the root token; an API token already belongs to one project. The same as --project.
SYPNIA_CONFIGenginePath of the configuration file. The same as --config.
SYPNIA_…engineEvery setting of the engine. See the configuration reference.
Against Sypnia Cloud
export SYPNIA_API_TOKEN=<your API token>
sypnia problems
Against your own engine
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:

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

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

Commands

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close