@statoss/cli

@statoss/cli

Sends an app's schema, source maps and releases to StatOSS. No dependencies; Node 22.18 or later.

Install

npx @statoss/cli --help          # or: pnpm dlx @statoss/cli --help
pnpm add -D @statoss/cli         # then: pnpm statoss --help

Environment

Variable	Option	What
STATOSS_API_KEY	--key	An API key with write access
STATOSS_URL	--url	StatOSS, by default https://statoss.com

The key is sent only in the Authorization header and never printed.

Config

statoss.config.ts in the directory you run the CLI from, or statoss.config.mjs, .js or .json; --config <file> names another.

import { defineSchema } from "@statoss/sdk";

export default {
  app: "web", // the app's slug or id
  schema: defineSchema({
    levels: { "payment-failed": { like: "error", label: "Payment failed" } },
    categories: { billing: { label: "Billing", color: "plum" } },
    fields: { route: { label: "Route", filterable: true } },
  }),
};

The schema can be a plain object of the same shape. Node reads a .ts config itself, by stripping its types: imports in it need their file extension (./schema.ts), and enums and namespaces are not allowed. On an older Node, name it statoss.config.mjs.

statoss schema

statoss schema                  # print what the schema would change
statoss schema --apply          # apply it, after a yes
statoss schema --apply --yes    # apply without asking (CI)
statoss schema --prune --apply  # also remove what the schema leaves out

Values the app has that the schema does not name stay, unless --prune. A kind the schema leaves out (no levels, say) is left alone even then. Built-in levels and fields, merged spellings, values others are merged into, and values a rule still names are never removed; the plan says which it kept. Without a terminal, --apply needs --yes.

Exit codes: 0 done or no change, 1 an error, 2 the plan was not applied.

statoss sourcemaps upload

statoss sourcemaps upload ./dist --release web@1.4.0
statoss sourcemaps upload ./dist --dry-run

For each .js, .mjs and .cjs file under the directory that has a source map, adds a debug ID to the file and its map (as sentry-cli sourcemaps inject does), then uploads the maps. Run it on the build output before you deploy it: the deployed files must carry the IDs. A file that has a debug ID already keeps it. node_modules is left out. Links are followed while they stay inside the directory; a link or a map outside it is left alone, so point it at a directory holding both the files and their maps. --dist <name> sets the distribution, --app <app> the app when the config does not.

A file it has to leave out (its map missing, unreadable, or too large) is named, the rest still go up, and the run exits 1.

statoss releases

statoss releases new web@1.4.0
statoss releases finalize web@1.4.0
statoss releases deploy web@1.4.0 --env production

--app <app> or the config's app; finalize and deploy without one act on every app of the key with that release. deploy puts a deploy marker on the app's status page.