Commands
Every command of the sypnia binary, with its flags, examples, output and exit codes.
On this page
- Flags of every command
- Run the engine
- sypnia serve
- sypnia aggregate
- sypnia migrate
- sypnia doctor
- Projects, keys and tokens
- sypnia project create
- sypnia project list
- sypnia project delete
- sypnia key create
- sypnia key list
- sypnia key revoke
- sypnia token create
- sypnia token list
- sypnia token revoke
- Work with a project
- sypnia sourcemaps upload
- sypnia problems
- sypnia problem
- sypnia version
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.
| 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
-
--jsonbooleanPrint the result as JSON, in the same shape as the HTTP API. Tables and colours are for people; scripts should use this.
-
--quiet, -qbooleanPrint only errors.
-
--no-colorbooleanNo colours. Also when
NO_COLORis set or the output is not a terminal. -
--config <file>pathEngine commands only. A configuration file in TOML. Environment variables win over the file. Also
SYPNIA_CONFIG. -
--help, -hbooleanExplain 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) and need the database and the storage.
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>stringThe address and port to listen on. Also
SYPNIA_LISTEN.Default:
0.0.0.0:8080 -
--role <role>all | ingest | api | workeringest: 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. AlsoSYPNIA_ROLE.Default:
all
Run the whole engine
sypnia servesypnia 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.comRun ingest and worker apart
sypnia serve --role ingest --listen 0.0.0.0:8081
sypnia serve --role workerExit codes: 0, 3, 4.
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>stringOnly this project. All projects when left out.
-
--from <time>stringProcess again from this moment: an ISO 8601 timestamp or a relative value (
6h,2d). Needs--toor defaults it to now. -
--to <time>stringEnd of the range to process again.
-
--task <task>all | events | uptime | alerts | webhooks | retention | suggestionsRun only one part of the pass.
suggestionsruns the weekly suggestions now, for the week that ended.Default:
all -
--watchbooleanKeep running and pass again every
SYPNIA_PROCESSING_INTERVAL_SECONDS. The same asserve --role workerwithout/healthz.
One pass
sypnia aggregateshop 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:10ZProcess yesterday again for one project
sypnia aggregate --project shop --from 2026-03-11T00:00:00Z --to 2026-03-12T00:00:00ZExit codes: 0, 1, 3, 4.
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
-
--statusbooleanShow which migrations are applied and which are pending, and change nothing.
-
--dry-runbooleanPrint the SQL that would run, and change nothing.
Apply pending migrations
sypnia migrateschema 11 -> 12
applied 0012_suggestions (0.2 s)
database is up to dateExit codes: 0, 3, 4.
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>stringComma-separated checks to run:
config,database,storage,address,ai,webhook,clock. -
--skip <checks>stringComma-separated checks to leave out.
Check everything
sypnia doctorconfig 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 passedWhen the model name is wrong
sypnia doctor --only aiai FAIL openrouter answered 404: no model named "<model>"
Set SYPNIA_AI_MODEL to a model your provider offers.
1 check failedExit 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.
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 requiredThe name people see.
-
--slug <slug>stringA short name for URLs and commands. Defaults to the name in lowercase with hyphens.
-
--timezone <zone>stringAn IANA time zone, such as
America/Bogota. Days are cut in it.Default:
UTC
Create the shop's project
sypnia project create --name Shopproject 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,replayExit codes: 0, 1, 4, 5.
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
sypnia project listSLUG ID NAME CREATED ENVIRONMENTS
shop prj_5k2m9x4q7w1z Shop 2026-02-02 production, developmentExit codes: 0, 4, 5.
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 requiredThe project’s slug or id.
Flags
-
--yesbooleanDo not ask. For scripts.
Delete a test project
sypnia project delete playground --yesExit codes: 0, 4, 5, 6.
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>stringThe project. Needed with the root token. Also
SYPNIA_PROJECT. -
--name <name>string requiredWhat the key is for.
-
--rate-limit <n>integerRequests a minute accepted from one address with this key. 10 to 6000.
Default:
600
A key for the API server
sypnia key create --project shop --name "Checkout API"key_8b5n2m7v4c1x spk_a3c9e1f7b5d2084c6e0a9f3b7d1c5e82 Checkout APIExit codes: 0, 1, 4, 5, 6.
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>stringThe project. Needed with the root token. Also
SYPNIA_PROJECT.
List keys
sypnia key list --project shopID KEY NAME LAST USED STATUS
key_3n8v2c6b1m4x spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e Web app 2026-03-12 10:00 activeExit codes: 0, 4, 5, 6.
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 requiredThe key’s record id (
key_…), fromkey list.
Flags
-
--project <id or slug>stringThe project. Needed with the root token. Also
SYPNIA_PROJECT.
Revoke a key
sypnia key revoke key_8b5n2m7v4c1x --project shopExit codes: 0, 1, 4, 5, 6.
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>stringThe project. Needed with the root token. Also
SYPNIA_PROJECT. -
--name <name>string requiredWho or what will use the token.
-
--scopes <list>string requiredComma-separated:
read,replay,admin. Give the fewest that do the job. -
--expires <time>stringWhen 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
sypnia token create --project shop --name Cursor --scopes readtok_9r4t6y2u8i1o Cursor read
sps_4Kq9Zt2MxV7bN1cR5wY8pL3dF6hJ0sA2gE4uT9iO
This is the only time the token is shown.A token for CI, to upload source maps
sypnia token create --project shop --name "CI source maps" --scopes admin --expires 365dExit codes: 0, 1, 4, 5, 6.
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>stringThe project. Needed with the root token. Also
SYPNIA_PROJECT.
List tokens
sypnia token list --project shopID NAME PREFIX SCOPES LAST USED EXPIRES STATUS
tok_9r4t6y2u8i1o Cursor sps_4Kq9Zt2M read, replay 2026-03-12 10:00 never activeExit codes: 0, 4, 5, 6.
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 requiredThe token’s record id (
tok_…), fromtoken list.
Flags
-
--project <id or slug>stringThe project. Needed with the root token. Also
SYPNIA_PROJECT.
Revoke a token
sypnia token revoke tok_9r4t6y2u8i1o --project shopExit 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.
Upload a build’s source maps and register its release.
Run it in your build, after bundling and before deploying. It does four things:
- Finds every JavaScript file under the directory and the map each one points to (its
sourceMappingURLcomment, or the file next to it ending in.map). - 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».
- Uploads the maps Sypnia does not have yet, straight to storage.
- With
--delete-after, deletes the.mapfiles 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 requiredThe build output that holds the JavaScript files and their maps, for example
distor.next/static.
Flags
-
--release <version>string requiredThe release’s name: the same string your app passes to
initasrelease. Use the short git commit. -
--url-prefix <path>stringThe path your site serves the directory from. With
dist/assets/a.jsserved as/assets/a.js, uploaddistwith/, ordist/assetswith/assets.Default:
/ -
--environment <name>stringThe environment the release is deployed to.
Default:
production -
--changes <mode>git | nonegitsends the commit, the commits since the previous release and the changed files, read from the repository in the current directory.nonesends only the release’s name.Default:
git -
--patchesbooleanAlso 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>stringThe release this one replaces. Defaults to the project’s latest release in the environment.
-
--delete-afterbooleanDelete the
.mapfiles from the directory after a successful upload. -
--allow-failurebooleanExit 0 even when the upload fails.
-
--dry-runbooleanShow what would be registered and uploaded, and send nothing.
-
--concurrency <n>integerUploads at the same time. 1 to 32.
Default:
8
In a build script
sypnia sourcemaps upload dist --release "$(git rev-parse --short HEAD)" --delete-afterrelease 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 sExit codes: 0, 1, 2, 4, 5.
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 | allWhich problems to list.
Default:
open -
--since <time>stringOnly problems seen after this moment.
Default:
30d -
--environment <name>stringThe environment to read.
Default:
production -
--query <text>stringText to find in the sentence, the title or the file.
-
--sort <field>last_seen | first_seen | people | occurrencesThe order.
Default:
last_seen -
--limit <n>integerHow many to print. 1 to 200.
Default:
20 -
--project <id or slug>stringThe project. Needed with the root token. Also
SYPNIA_PROJECT.
What is open
sypnia problems1 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 highExit codes: 0, 4, 5.
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 requiredThe problem’s slug or id.
Flags
-
--contextbooleanAlso print the stack, the breadcrumbs, the trace and the release’s changes.
-
--promptbooleanPrint only the ready prompt.
-
--project <id or slug>stringThe project. Needed with the root token. Also
SYPNIA_PROJECT.
Read a problem
sypnia problem pay-button-does-nothingpay-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-nothingCopy the prompt for your coding agent
sypnia problem pay-button-does-nothing --prompt > fix.mdExit codes: 0, 4, 5, 6.
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
sypnia versionsypnia 1.0.0 (a1c9e3f, 2026-03-01) schema 12Exit codes: 0.