Docs

Commands

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

Applies to EngineCloud At launch

View as Markdown
On this page
  1. Flags of every command
  2. Run the engine
  3. sypnia serve
  4. sypnia aggregate
  5. sypnia migrate
  6. sypnia doctor
  7. Projects, keys and tokens
  8. sypnia project create
  9. sypnia project list
  10. sypnia project delete
  11. sypnia key create
  12. sypnia key list
  13. sypnia key revoke
  14. sypnia token create
  15. sypnia token list
  16. sypnia token revoke
  17. Work with a project
  18. sypnia sourcemaps upload
  19. sypnia problems
  20. sypnia problem
  21. 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.

CommandWhat it does
sypnia serveRun the engine
sypnia aggregateProcess what has arrived, once
sypnia migrateCreate or update the database tables
sypnia doctorCheck that the engine is set up correctly
sypnia project create, list, deleteManage projects
sypnia key create, list, revokeManage ingest keys
sypnia token create, list, revokeManage API tokens
sypnia sourcemaps uploadUpload a build’s source maps and register its release
sypnia problemsList problems
sypnia problemShow one problem, or print its ready prompt
sypnia versionPrint 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) 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

    The address and port to listen on. Also SYPNIA_LISTEN.

    Default: 0.0.0.0:8080

  • --role <role>
    all | ingest | api | worker

    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.

    Default: all

Run the whole engine

Terminal
sypnia serve
Output
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

Terminal
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

    Run only one part of the pass. suggestions runs the weekly suggestions now, for the week that ended.

    Default: all

  • --watch
    boolean

    Keep running and pass again every SYPNIA_PROCESSING_INTERVAL_SECONDS. The same as serve --role worker without /healthz.

One pass

Terminal
sypnia aggregate
Output
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

Terminal
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

Terminal
sypnia migrate
Output
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

Terminal
sypnia doctor
Output
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

Terminal
sypnia doctor --only ai
Output
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

    An IANA time zone, such as America/Bogota. Days are cut in it.

    Default: UTC

Create the shop's project

Terminal
sypnia project create --name Shop
Output
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

EngineCloud

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

Terminal
sypnia project list
Output
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

Terminal
sypnia project delete playground --yes

Exit codes: 0, 4, 5, 6.

sypnia key create

EngineCloud

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

    Requests a minute accepted from one address with this key. 10 to 6000.

    Default: 600

A key for the API server

Terminal
sypnia key create --project shop --name "Checkout API"
Output
key_8b5n2m7v4c1x  spk_a3c9e1f7b5d2084c6e0a9f3b7d1c5e82  Checkout API

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

sypnia key list

EngineCloud

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

Terminal
sypnia key list --project shop
Output
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

EngineCloud

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

Terminal
sypnia key revoke key_8b5n2m7v4c1x --project shop

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

sypnia token create

EngineCloud

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

Terminal
sypnia token create --project shop --name Cursor --scopes read
Output
tok_9r4t6y2u8i1o  Cursor  read
sps_4Kq9Zt2MxV7bN1cR5wY8pL3dF6hJ0sA2gE4uT9iO

This is the only time the token is shown.

A token for CI, to upload source maps

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

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

sypnia token list

EngineCloud

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

Terminal
sypnia token list --project shop
Output
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

EngineCloud

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

Terminal
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

EngineCloud

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

    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.

    Default: /

  • --environment <name>
    string

    The environment the release is deployed to.

    Default: production

  • --changes <mode>
    git | none

    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.

    Default: git

  • --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

    Uploads at the same time. 1 to 32.

    Default: 8

In a build script

Terminal
sypnia sourcemaps upload dist --release "$(git rev-parse --short HEAD)" --delete-after
Output
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

EngineCloud

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

    Which problems to list.

    Default: open

  • --since <time>
    string

    Only problems seen after this moment.

    Default: 30d

  • --environment <name>
    string

    The environment to read.

    Default: production

  • --query <text>
    string

    Text to find in the sentence, the title or the file.

  • --sort <field>
    last_seen | first_seen | people | occurrences

    The order.

    Default: last_seen

  • --limit <n>
    integer

    How many to print. 1 to 200.

    Default: 20

  • --project <id or slug>
    string

    The project. Needed with the root token. Also SYPNIA_PROJECT.

What is open

Terminal
sypnia problems
Output
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

EngineCloud

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

Terminal
sypnia problem pay-button-does-nothing
Output
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

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

Exit codes: 0, 4, 5, 6.

sypnia version

EngineCloud

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

Terminal
sypnia version
Output
sypnia 1.0.0 (a1c9e3f, 2026-03-01) schema 12

Exit codes: 0.

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