--- title: "CLI" description: "Every mainsdk command and flag the specs define, with exit codes, an example, and the milestone each one ships in." section: "reference" status: "Planned for 0.2" spec: "cli-core" canonical: "https://mainsdk.dev/docs/reference/cli" updated: "2026-10-28" --- # CLI > Every mainsdk command and flag the specs define, with exit codes, an example, and the milestone each one ships in. Status: Planned for 0.2 · Canonical: https://mainsdk.dev/docs/reference/cli · Updated: 2026-10-28 The `mainsdk` CLI lives in your repo and works with no account. Run it with `npx mainsdk`, `pnpm mainsdk` or `bunx mainsdk`. npm: ```bash npx mainsdk check ``` pnpm: ```bash pnpm mainsdk check ``` bun: ```bash bunx mainsdk check ``` No command calls MainSDK Cloud before you run `mainsdk login`. Each command below names the milestone of the spec that defines it, for example "0.2". Commands from milestone 0.6 on need the Cloud or ship after the public beta. ## Commands at a glance | Command | What it does | Milestone | | --- | --- | --- | | [`--help`, `-h`](#help) | Prints the command list, like `mainsdk` alone | 0.2 | | [`init`](#init) | Writes `main.yaml`, a project ID, agent rules and the MCP server entry | 0.2 | | [`add`](#add) | Adds one interface with a local driver and a test | 0.3 | | [`doctor`](#doctor) | Diagnoses your machine and project offline | 0.3 | | [`sync`](#sync) | Plans changes to `main.yaml` in plain words, then opens a pull request | 0.2 | | [`check`](#check) | Runs every gate and every overlay combination in use | 0.2 | | [`privacy labels`](#privacy-labels) | Prints the privacy labels (web, manifest, App Store, Play) the code and `main.yaml` generate | 0.4 | | [`discover`](#discover) | Lists what your code uses: hosts, folders, server facts and programs | 0.3 | | [`info`](#info) | Shows everything about an app, yours or a running one | 0.2 | | [`fix`](#fix) | Applies the machine fix of a finding as a diff; a fix that widens a grant waits for a person | 0.5 | | [`next`](#next) | Says the one next action for an agent in under 300 tokens | 0.5 | | [`types`](#types) | Writes `.mainsdk/types/main.d.ts` from `main.yaml` | 0.5 | | [`mcp`](#mcp) | Runs an MCP server for coding agents: catalog, info, check, discover, explain, next, fix | 0.5 | | [`seal`](#seal) | Signs the build record (`mainsdk.seal.json`), makes seal keys, verifies a seal and diffs the capabilities of two seals | 0.2 | | [`network export`](#network-export) | Writes the allow list as Kubernetes or AWS security-group rules | 0.3 | | [`upgrade`](#upgrade) | Moves every MainSDK package to a new release with codemods and a pull request, and checks for security releases | 0.5 | | [`licence verify`, `licence show`](#licence) | Checks an app licence file offline and prints its claims, chain and state | 0.4 | | [`logs`](#logs) | Reads the local event store (`--security` for security events); `--env prod` tails production from the Cloud | 0.2 (local); 0.6 (Cloud) | | [`debug`](#debug) | Raises detail for one user, request or release for up to 60 minutes with no redeploy | 0.6 | | [`replay`](#replay) | Re-runs a failed request from its trace on fake drivers, with no outbound call | 0.6 | | [`triage`](#triage) | Groups errors, opens GitHub issues that name the release, commit, file and line, and opens gated fix pull requests | 0.6 | | [`incident`](#incident) | Switches off a target, sets read-only mode or signs everyone out, with a reason; reads the controls in force | 0.4 | | [`alerts test`](#alerts-test) | Sends a test alert through every driver of a recipient | 0.4 | | [`dev`](#dev) | Runs your app offline on a local driver for every interface | 0.2 | | [`explain`](#explain) | Explains an error code, a trace or the resolved config | 0.1–0.2 | | [`status`](#status) | Shows the state of every remote dependency | 0.4 | | [`errors`](#errors) | Lists error groups in the local event store, newest first | 0.2 | | [`signals`](#signals) | Prints the signals the app recorded, newest first, with count and age | 0.4 | | [`neighbours`](#neighbours) | Shows this app's host bus settings, its socket and the last host signals; `rotate-key` writes a new host key | 0.4 | | [`apps`](#apps) | Lists the MainSDK apps on this machine from the registry folder, flags broken seals, stale and duplicate records, and lists declared actions | 0.4 | | [`context`](#context) | Shows the shared context: group, purposes, `share-with`, sinks, and consent and flow counts per purpose, with no person in them | 0.4 | | [`fleet`](#fleet) | Reads Fleet records: push log with inclusion proofs, breach scope, forensic timeline, evidence bundles and deploy admission | 1.4 | | [`connectors`](#connectors) | Pings each configured GRC, privacy, vulnerability and ticket connector without writing, and pushes an assure run | 1.2 | | [`ops mcp`](#ops-mcp) | Runs a stdio MCP server for a running app's ops tools: status, signals, norms, playbooks, plans and approval-only runs | 0.4 | | [`playbooks`](#playbooks) | Lists and plans rules, lists runs, and approves, declines or reverts one | 0.4 | | [`norms`](#norms) | Shows what the app has learned: each metric's bucket, count, p50, p99 and learning state | 0.4 | | [`eject`](#eject) | Replaces MainSDK calls with plain provider code | 0.3 | | [`adopt`](#adopt) | Brings an existing app onto MainSDK one pull request at a time | 0.5 | | [`docs`](#docs) | Reads the docs of the installed version, offline, and serves them to agents over MCP | 0.5 | | [`contract diff`](#contract-diff) | Fails on a breaking contract change not released as a new major | 0.1 | | [`contract record`](#contract-record) | Refreshes the recorded getqr.id calls that the offline contract test replays | 0.3 | | [`login`](#login-logout-and-keys) | Device login; adds the project to your Cloud account | 0.6 | | [`db migrate`](#db-migrate) | Runs your migrations once per region store under a lock, with a lock timeout and retries | 0.3 | | [`share webhooks`](#share) | Registers or lists the getqr.id webhook endpoints of the app | 0.4 | | [`webhooks`](#webhooks) | Lists inbound deliveries recorded under `dev` and replays one | 0.4 | | [`deploy`](#deploy) | Writes the platform's files from `main.yaml`, checks a build before it ships and diffs two environments | 0.4 | | [`i18n`](#i18n) | Finds message keys, writes pseudo-locales, moves messages in and out, and drafts translations | 0.4 | | [`migrate`](#migrate) | Maps a provider's calls to interfaces and opens a pull request | 0.7 | | [`assure`](#assure) | Checks the app against standards and packs, with owners and fixes | 0.7 | ## init Creates the project. Works offline and with no account. ```text mainsdk init [--preset minimal|indie|saas|agency] [--from ] [--new-id] [--force] ``` | Flag | Meaning | | --- | --- | | `--preset ` | Choose the starting `main.yaml`: `minimal` (the four required keys), `indie` (the default), `saas` or `agency` | | `--from ` | Start from a description made on mainsdk.dev or by your agent | | `--new-id` | Replace the project ID, for a fork or a copy | | `--force` | Run in a repo that already has `main.yaml` | | `--template ` | Start from a reference architecture: `mainsdk/saas-web`, `mainsdk/api-service`, `mainsdk/payments-checkout`, `mainsdk/ai-agent` (milestone 0.7) | What it writes: - `main.yaml` with `schema: 1`, a project ID (a UUIDv7 shown as `prj_…`), `overlays.order` and `policy.placement: server`. - `.mainsdk/` for local state, added to `.gitignore`. - A MainSDK section in `AGENTS.md` and `CLAUDE.md`, between markers, appended to files you already have. - The MCP server entry for the coding agent it detects. ```text $ npx mainsdk init mainsdk init · pinecart project prj_01JC8Q4W7ZK3M5N8P2R6T9V0XY wrote main.yaml wrote AGENTS.md, CLAUDE.md (MainSDK section) updated .gitignore (.mainsdk/) mcp registered for Claude Code Next: edit main.yaml, then run mainsdk sync ``` With `--preset minimal`, `init` writes only `schema`, `project`, `baseline` and `overlays.order`, in at most ten lines. The default `indie` preset adds `auth`, `db` and `files` on their local drivers, `logging` and a deny-by-default `network` in observe mode; `saas` and `agency` build on it. `init` asks no question when it runs without a terminal. A preset only chooses keys: you can widen or tighten any of them later, and `mainsdk explain config` says why each default is there. The `saas` preset adds passkey and email sign-in methods; `agency` turns on the audit log. Running `init` again in the same repo exits 2 unless you pass `--new-id` or `--force`. ## add Adds one interface to an existing project with its local driver and one example test, then runs `check`. It changes nothing outside the files it reports. Planned for milestone 0.3 (spec `fast-start`). ```text mainsdk add auth|db|ai|pay|... ``` It works for each interface once its local driver ships: `config`, `secrets`, `policy` and `log` at milestone 0.2, and `auth`, `db` and `ai` at 0.3. `add` refuses to weaken a key that is already set and says which command raises the guarantee. ```text $ npx mainsdk add auth mainsdk add · auth updated main.yaml (auth, local driver) wrote test/auth.test.ts check no new critical finding ``` The output above shows the shape; the exact wording is [TBD]. ### add recipe `mainsdk add recipe ` adds a worked pattern to the project: `main.yaml` keys on local drivers, code in `src/recipes/.ts`, its test and a note in `docs/recipes/.md`, together. The recipes are `stripe-subscriptions`, `api-keys-and-plans`, `invite-teammates`, `agent-with-approval` and `memory-and-tools`. A target file that exists with other text fails with `MAIN-DEV-0002` and nothing is written; `--dry-run` lists the changes first. Init also writes the agent context: `.claude/skills/mainsdk/SKILL.md`, `.cursor/rules/mainsdk.mdc` and a marked section of `AGENTS.md`, and `sync` refreshes only the marked text. ## doctor Reports the state of your machine and project in one run: Node, git, lockfile, environment, drivers and network. It runs offline, sends no telemetry and names the fix for every problem. Spec `fast-start` (milestone 0.3). ```text mainsdk doctor [--json] ``` With Node 20 and no lockfile, `mainsdk doctor --json` reports two problems, each with a `fix`, and exits non-zero. The JSON report is `{ version: 1, passed, problems: [{ id, message, fix }], notes }`. The problems are `node` (older than 22.18), `lockfile`, `main-yaml`, `gitignore` (`.mainsdk/` not ignored) and `env` (a `.env` that git would track). `notes` carry facts that do not fail the run: whether the folder is in git, the declared drivers and the network mode. ## sync Makes the code match `main.yaml`. It shows the plan first, resolves driver versions into `main.lock`, applies the change on a new branch, runs `check` and opens a pull request. ```text mainsdk sync [--plan] [--no-pr] ``` | Flag | Meaning | | --- | --- | | `--plan` | Print the plan and change nothing | | `--no-pr` | Leave the branch; don't open a pull request | | `--package `, `--all`, `--affected --base ` | Monorepo scope (milestone 0.7). See [monorepos](https://mainsdk.dev/docs/guides/monorepos) | With no git remote or no GitHub access, `sync` leaves the branch and prints the plan. `sync` also installs what `policy.placement` needs: for `server` in a Next.js app the route `app/api/mainsdk/decide/route.ts`, for `edge` the entry `mainsdk.edge.ts`, and for `browser` the config `mainsdk.browser.ts` (with `policy.browser.local: true`, also `mainsdk.policy-engine.ts`, the lazily loaded Cedar engine chunk). Change the placement and run `sync --plan` to see files added and the old placement's files removed. `sync` never overwrites a file it did not write. ```text $ npx mainsdk sync Plan + email driver resend (email@1.4) because features lists email ~ main.lock resend 2.3.1 sha256:9f2c… Branch mainsdk/sync-email · check passed · pull request opened ``` ## check Runs every registered gate and resolves and tests every overlay combination in use. Gates are explained in [the check](https://mainsdk.dev/docs/concepts/the-check). ```text mainsdk check [--env ] [--json [--agent]] [--sarif ] [--fail-on ] ``` | Flag | Meaning | | --- | --- | | `--env ` | Resolve for an environment, for example `prod` | | `--json` | Print the versioned JSON result on stdout | | `--agent` | With `--json`: output for a repair loop. Every finding carries its `fix` and `file`, and a finding still open after the third run carries `ask: person` and no more `fix` text. The count of unresolved runs lives in `.mainsdk/agent-loop.json` and the report's `agent.maxTries` says how many runs an agent gets (3) | | `--sarif ` | Also write SARIF 2.1.0 for code scanning: one result per finding with its file and line. The `--json` document is described by `packages/cli/schema/check-report.schema.json` | | `--fail-on ` | Fail only at or above this severity | | `--explain-baseline` | Print the Main 27 pack: its generation, every rule with its area and standards mapping, and the bill of contracts. With `--json`, `generation` and `contracts` are keys of the document | | `--maps` | Print the standards each finding maps to (ASVS, OWASP Top 10:2025, SOC 2, ISO 27001) under it; `--json` always carries them. A mapping helps a review and is not certification | | `--package `, `--all`, `--affected --base ` | Monorepo scope (milestone 0.7) | | Exit code | Meaning | | --- | --- | | 0 | Passed | | 1 | A gate failed | | 2 | Usage or configuration error, with a `MAIN-CONFIG-` code | The `engagement` gate (spec engagement) awaits the copy rules before the report is built. Its model pass runs only with `check.ai: true` and an ai driver; when it was skipped, the text report prints a `note:` line and the JSON document carries `notes`. The `feeds` and `imports` gates report `MAIN-FEED-0010` to `0013` and `MAIN-IMPORT-0020`. The `config` gate loads `main.yaml` with the selected environment plus each market, segment and target overlay file in the folder, one at a time, and names the overlay file and line of any combination that fails. The text report prints the failing findings first, each with its code and fix. `check --env prod` fails with `MAIN-CHECK-0026` if any interface resolves to a local driver: ```text $ npx mainsdk check --env prod mainsdk check · pinecart · env prod · Main 27 ✗ secrets 1 finding MAIN-CHECK-0026 critical main.env.prod.yaml fix: Set secrets.driver to a key service in main.env.prod.yaml ✓ config ✓ policy ✓ network 1 gate failed · exit 1 ``` ```jsonc // npx mainsdk check --json { "version": 1, "project": "prj_01JC8Q4W7ZK3M5N8P2R6T9V0XY", "env": "prod", "passed": false, "gates": [{ "id": "secrets", "passed": false, "findings": [ { "code": "MAIN-SECRET-0002", "severity": "critical", "file": "app/lib/pay.ts", "line": 3, "rule": "secrets.no_literal", "fix": "Move the key to secrets and use secret:STRIPE_KEY" } ] }] } ``` The `schema` gate validates `main.yaml` against the JSON Schema the `mainsdk` package ships (`mainsdk/main.schema.json`, built from the catalog and the key tables). An unknown top-level key fails the run with `MAIN-CONFIG-0030` and names the nearest key. An unknown nested key, or a value of the wrong type (`MAIN-CONFIG-0032`), is reported as a warning with its path and a fix. `mainsdk init` writes the schema's path on the first line of `main.yaml`, so your editor flags the same keys. If the schema is not built, the gate warns with `MAIN-CONFIG-0033` and validates nothing. Every code is listed in [check codes](https://mainsdk.dev/docs/reference/check-codes). ## discover Reads your source and lists what the app uses outside itself: the hosts it calls, the folders it reads and writes, the server facts it asks for and the programs it runs. Each item says whether `main.yaml` declares it. It runs offline and changes nothing. ```text mainsdk discover [--env ] [--json] [--out ] ``` | Flag | Meaning | | --- | --- | | `--env ` | Resolve the declared lists for an environment. The default is `dev` | | `--json` | Print the result as JSON | | `--out ` | Write the JSON to a file and print its path | The JSON manifest is version 2: its `calls` section lists every call on a MainSDK interface the code makes (for example `files.uploadUrl` or `system.run`), with its interface, its sensitive kind or `false`, and every file and line. A call whose name is computed at run time is listed under `dynamic`. Use it to fill `network.allow` and `permissions` from what the code really does. See [declare what your app uses](https://mainsdk.dev/docs/guides/declare-what-your-app-uses). The manifest also carries `notify.engagement` when the app declares it: the guardrail values, whether the strict rules and guardian controls apply, and each journey with its rungs, read from `journey()` and `ladder()` in the code. ## privacy labels Prints the privacy labels generated from what the code and `main.yaml` really do, never written by hand. `web` and `manifest` list one line per interface that makes a promise to a person (engagement is the first). `app-store` and `play` are the store forms, built from the labelled `db.fields`, the third-party drivers in `main.yaml` (listed as processors), the retention rules and, with `--manifest`, the hosts, system facts and programs a `mainsdk discover --out` manifest found. ```text mainsdk privacy labels [--format web|manifest|app-store|play] [--manifest ] [--env ] ``` | Flag | Meaning | | --- | --- | | `--format web` | One line per source, as text. The default | | `--format manifest` | JSON: `{ version: 1, labels: [{ source, text }] }` | | `--format app-store` | The App Store privacy label: data linked to the user by Apple's data types, processors, hosts and retention | | `--format play` | The Play Data safety answers: data collected by Google's categories, processors, hosts and retention | | `--manifest ` | A manifest from `mainsdk discover --out `, for the app-store and play forms | Exit 2 for a format that does not exist or a manifest that cannot be read. ## network export Writes the `network.allow` list as egress rules for the platform that runs the app, so the platform blocks what the SDK would block. ```text mainsdk network export --to k8s|aws-sg [--discovered] [--env ] ``` | Flag | Meaning | | --- | --- | | `--to k8s` | A Kubernetes `NetworkPolicy`. Names are resolved to `/32` or `/128` addresses first | | `--to aws-sg` | AWS security-group egress rules | | `--discovered` | Also include the undeclared hosts that `discover` finds in your code | | `--env ` | Read the allow list for an environment. The default is `dev` | Vercel and Cloudflare exports are planned. Any other `--to` value exits 2. ## licence Checks an app licence the way the app does, offline, and prints what is in it. Neither command calls the network. See [App licensing](https://mainsdk.dev/docs/interfaces/licence). ```text mainsdk licence verify [ | -] [--json] [--strict] [--at ] [--env ] [--machine ] [--root ed25519:... --product

] mainsdk licence show [ | -] [--json] [--machine] ``` | Flag | Meaning | | --- | --- | | `` or `-` | The licence file (JSON or compact `mlic1.` form), or standard input. Without it, both commands read `licence.file` or `licence.token` from `main.yaml` | | `--json` | Print `{ status, reason, scope, licence, chain, revocation, graceEndsAt }` | | `--strict` | `verify` only: a licence in grace exits 1 | | `--at ` | `verify` only: judge the licence at that time instead of now | | `--env ` | `verify` only: the environment the licence is checked in. The default is `dev` | | `--machine ` | `verify` only: the machine id a machine-bound licence is checked against | | `--root ... --product

` | Verify without a `main.yaml`: pin this root for this product | | `--machine` (on `show`) | Print this machine's id and nothing else | | Exit code | Meaning | | --- | --- | | 0 | `valid`, or `grace` (it prints the days left) | | 1 | `expired`, `revoked`, `suspended`, `tampered` or `missing`, or `grace` with `--strict` | | 2 | Usage error, or no `main.yaml` and no `--root` and `--product` | `show` prints the claims, the chain with key ids, the newest revocation list and the state. The claims of a licence that doesn't verify are printed under `unverified`, so read them as untrusted. ```bash mainsdk licence verify ./main.licence --strict # in CI: fail when the licence is in grace mainsdk licence show --machine # the id to give your vendor for a machine-bound licence ``` ## upgrade Moves an app to a new MainSDK release. See [Upgrades](https://mainsdk.dev/docs/interfaces/upgrade) and [Upgrade MainSDK](https://mainsdk.dev/docs/guides/upgrade-mainsdk). ```text mainsdk upgrade [--to | --to latest] [--plan] [--json] mainsdk upgrade --check [--json] ``` | Flag | Meaning | | --- | --- | | `--to ` | The target; `latest` (the default) is the registry's dist-tag. An exact version the CLI already has notes for plans offline | | `--plan` | Print the plan and write nothing | | `--json` | Print the plan, or the check result, as JSON | | `--check` | Exit 1 with `MAIN-UPGRADE-0005` when a release marked `security` is newer than the installed one; cached for 24 hours; offline it reports `MAIN-UPGRADE-0004` as info and exits 0 | | `--continue --from ` | The second half, run by the newly installed CLI: key moves, codemods, sync, check, tests, commit and pull request | | Exit code | Meaning | | --- | --- | | 0 | Done, nothing to upgrade, or the check found no security release | | 1 | A guard or step failed (`MAIN-UPGRADE-0001`, `-0004`, `-0006`), or `--check` found a security release | | 2 | Usage error | ## info Prints everything about an app: name, version and Main mark, project ID, targets, interfaces and drivers, network destinations, data labels and regions, and open exceptions. Pass a URL to read and verify a running app's signed `/.well-known/mainsdk.json`. ```text mainsdk info [] [--json] ``` ```text $ npx mainsdk info Pinecart 2.4.1 · Main 27 ✓ prj_01JC8Q4W… (2.4.1+main27) Targets web Interfaces auth (github) · ai (bedrock) · db (postgres) · policy (cedar) Data personal: email · regions: us, eu Exceptions none ``` `info` also prints an `alerts` line (recipients by name and driver, never their keys, the routes and the open alerts) and a `security` line (sinks, lowest severity sent, detector thresholds and event counts by type). With a path to a folder holding `mainsdk.seal.json` (or to the JSON file), `info` verifies the seal and the shape of its `mark` against `mainsdk-mark@1`, and prints `verified`, `signature`, `mark`, `state` and `schema`; one changed byte in the record gives `verified: false` and exit 1. The mark is `+main27` with state `pass`, `exception` (an open exception is in use), `lapsed` (an exception expired and its finding is open) or `fail`. With a URL, `info` fetches `/.well-known/mainsdk.json` over HTTPS only and verifies it as [`seal verify`](#seal) does. `--key ` pins the signer; without it a record that verifies is shown as `signed`, not `verified` (`MAIN-SEAL-0004`). Every field shown comes from the signed payload, never from the document around it. ```text $ npx mainsdk info https://orders.acme.dev --key ed25519:MCowBQYDK2VwAyEA… verified signer ed25519:4f0c… project prj_01JC8Q… app Acme Orders 2.4.1 (owner acme) build sha256:9b1e… 1834 files, commit 4f2c1e9…, built by github-actions ``` A record whose signature fails exits 1 with `MAIN-INFO-0002 signature does not verify`. Unverified fields are never shown as verified. ## seal Signs one record of what the build is (spec seal): a hash of exactly the files that ship, what the code uses, its capability inventory, interfaces, actions, env names, check result, SBOM digest, commit and builder. It runs in the CLI with no network and is free. ```text mainsdk seal --key [--provenance ] [--out

] [--env ] [--json] mainsdk seal --sigstore [--out ] [--env ] mainsdk seal --sigstore --bundle --trust-root [--provenance ] [--allow-email-identity] mainsdk seal keygen [--out ] [--force] mainsdk seal verify [--key ] [--identity --issuer ] [--trust-root ] [--env ] [--json] mainsdk seal diff [--key ] [--json] [--fail-on sensitive] ``` | Command or flag | Meaning | | --- | --- | | `seal --key ` | Sign with a local ed25519 key (PKCS#8 PEM). Writes `mainsdk.seal.json`, `mainsdk.seal.files` (the file manifest) and `mainsdk.sbom.cdx.json` (CycloneDX 1.6) next to `main.yaml`, or in `--out` | | `seal --sigstore` | Writes the statement to `.mainsdk/seal.statement.json` (and the file manifest and SBOM) for your CI to sign keyless, for example with `cosign attest-blob --statement`. No seal is written yet: the CLI holds no OIDC credentials and calls neither Fulcio nor Rekor | | `--sigstore --bundle ` | Verifies the CI's Sigstore bundle against `--trust-root` and against the statement, then writes it into `mainsdk.seal.json`. An email identity is refused unless `--allow-email-identity`, because Rekor publishes the certificate | | `--provenance ` | Verifies an SLSA provenance bundle whose subject is the build hash and carries it in the seal document as `provenance` | | `--trust-root ` | The pinned Sigstore `trusted_root.json` (Fulcio authorities and Rekor keys). Nothing is fetched; a bundle can't be checked without it | | `--identity --issuer ` | The signer a bundle must have: the certificate's SAN against the pattern and its OIDC issuer exactly. Without them `seal verify` uses the `sigstore` entries of `seal.signers` | | `--env ` | The environment whose `main.yaml` is sealed. The default is `MAINSDK_ENV`, else `dev` | | `seal keygen` | Writes an ed25519 private key with mode 0600 (default `mainsdk-seal.pem`) and prints the public key in the `seal.signers` form, `ed25519:` | | `seal verify ` | Prints `verified`, `signed` (`MAIN-SEAL-0004`) or fails with `MAIN-INFO-0002`. For a folder it also recomputes the build hash and fails with `MAIN-SEAL-0007` naming the files that differ. Exits 0 only when verified | | `seal diff ` | Compares two seals (files, folders or HTTPS URLs, each verified first): calls, sensitive kinds, grants and actions added, removed or changed, sensitive changes first as `MAIN-SEAL-0008` | | `--fail-on sensitive` | `seal diff` exits 1 when any `MAIN-SEAL-0008` is reported | Before signing, `seal` refuses a record that would carry a secret, an email address or the value of an environment variable present at build (`MAIN-SEAL-0003`), and a file it can't hash (`MAIN-SEAL-0005`). The record holds env var names only, never values, and no commit author. A Sigstore bundle is verified offline by the CLI's own verifier on `node:crypto`, with no dependency: certificate chain to the pinned trust root, the Rekor signed entry timestamp, the inclusion proof and signed checkpoint, the certificate's validity at the integration time, then the signer. A bundle that fails any step is `invalid` (`MAIN-INFO-0002`, with the reason); one that verifies for another signer is `signed` (`MAIN-SEAL-0004`). It does not check RFC 3161 timestamps or the certificate's SCT. The app itself never verifies a bundle chain: at run time it checks the files and reports the signer as `unverified-at-runtime`. ```text $ npx mainsdk seal keygen --out ~/.keys/orders-seal.pem ed25519:MCowBQYDK2VwAyEA… $ npx mainsdk seal --key ~/.keys/orders-seal.pem sealed sha256:9b1e… 1834 files $ npx mainsdk seal verify . verified signer ed25519:4f0c… ``` Every adapter serves `mainsdk.seal.json` unchanged at `GET /.well-known/mainsdk.json`; the file manifest is never served, and the SBOM only with `seal.publish.sbom: true`. At boot the app recomputes the build hash and sets `app.info().seal`; see the `seal` keys in [main.yaml](https://mainsdk.dev/docs/reference/main-yaml). ## logs Reads the local event store in `.mainsdk/events/` (git-ignored, 7 days). ```text mainsdk logs [--follow] [--level ] [--trace ] [--security] [--json] ``` `--security` shows only security events (spec security-events), one line each with type, severity and message. With `--json` it prints the event itself: OCSF fields, ATT&CK tags, actor and app. ```text $ npx mainsdk logs --level error --trace 4bf92f3577b34da6a3ce929d0e0e4736 2026-11-03T10:14:02Z error MAIN-DATA-0007 Record belongs to another user app/api/orders/[id]/route.ts:18 · rule data.owner_scope fix: Scope the query with db.orders.for(user). ``` Live tail from MainSDK Cloud is free. It reads the project's production records from its region, asks for a fresh passkey first, and with `--follow` asks again every 2 seconds, so each record shows within 5 seconds of being written: ```text mainsdk logs --follow --env prod [--user ] [--trace ] [--level error] [--json] ``` See [debugging](https://mainsdk.dev/docs/guides/debugging). ## debug Raises detail for one user, request or release for up to 60 minutes with no redeploy (spec debug-loop; Teams). The app reads the active sessions and keeps below-level records only for that target; the session switches itself off and its start and end are audited. ```text mainsdk debug start --user | --request | --release [--for 30m] mainsdk debug stop ``` `--for 90m` is cut to 60 minutes and the answer says so. Give exactly one target, or the Cloud answers `MAIN-DEBUG-0002`. On Free the Cloud answers HTTP 402 with a link to Teams (`MAIN-DEBUG-0001`, exit 3) and the app is unchanged. Exit codes: 0 done, 1 the Cloud refused, 2 usage or no login, 3 needs Teams. ## replay Re-runs a failed request from its trace on the test app with a fake driver for every interface (Teams). A call that tries to reach the network is blocked and counted, so a replay never touches a real provider. ```text mainsdk replay [--handlers ] [--file ] [--json] ``` The handlers file, `mainsdk.replay.ts` by default, exports a function for each action by name. Exit 0 means the same error code came back; 1 means it did not. See [debugging](https://mainsdk.dev/docs/guides/debugging). ## triage Groups the project's errors, finds the release and commit that introduced each from the Main mark, and opens a GitHub issue that names the file and line, the trace and the steps from customer reports (spec debug-loop). ```text mainsdk triage connect github --installation [--repo owner/name] mainsdk triage run mainsdk triage fix --head ``` `run` opens one issue for each error group that has none (hosted triage, Teams). `fix` opens a draft pull request from the branch you pushed and sets the `mainsdk/check` status to pending; it turns green only when `pnpm mainsdk check --json` reports `"status": "pass"`, and the repository's own gates still apply. ## dev Runs your app on local drivers: a local driver for every interface in use, no provider calls and no account. ```text mainsdk dev [--port ] [--env dev] mainsdk dev [-- ] ``` With an entry file, `dev` serves its default `fetch` function on `127.0.0.1` (port 3000 unless `--port` says otherwise) and prints one line for each request. The token `Bearer dev_` signs the request in as the test user ``, from this machine only and only on the `local` auth driver, so `curl -H "authorization: Bearer dev_ada" ...` needs no sign-in flow. A `dev_` token from another address is a bad token. `--env prod` is refused with `MAIN-DEV-0008`; a missing entry, a missing `fetch` export or a port in use is `MAIN-DEV-0009`. With `--cockpit`, `dev` also serves a page on `127.0.0.1` (the next port up) that lists each request with its status, events and decisions and a replay button that sends it again on local drivers. It answers this machine only. ```bash npx mainsdk dev app.ts npx mainsdk dev -- next dev ``` With `-- `, `dev` runs your command with every interface on a local driver. Local drivers include files for `config`, `.mainsdk/secrets.json` for `secrets`, Cedar for `policy`, the terminal for `log`, SQLite for `db`, a local inbox for `email`, test cards for `pay` and an in-process queue for `jobs`. `check --env prod` refuses them with `MAIN-CHECK-0026`. ## fix Applies the machine fix of a check finding (spec agent-experience). `check --json --agent` carries `patch`, `yaml` and `widens` on each finding; `fix` builds the same change and writes it. A finding with no mechanical fix says `ask: person` and why. ```text mainsdk fix |--all [--dry-run] [--allow-widen] [--json] ``` `--dry-run` prints the unified diff and writes nothing. A fix that widens a grant, such as a host for `network.allow`, is planned but not applied: `MAIN-DEV-0001`, until a person reviews it and runs it with `--allow-widen`. Every applied fix is recorded in `.mainsdk/agent-changes.jsonl`. The rules with a builder are `MAIN-SECRET-0002`, `MAIN-FILES-0010` and `MAIN-NET-0007`. ## next Prints the one thing an agent should do now, as `kind` (`fix`, `edit`, `test`, `declare`, `ask-person` or `done`), the command and a sentence, in at most 300 tokens. It looks at check findings first, then unreviewed widening changes, stale types (`MAIN-DEV-0004`) and missing tests. A finding still open after three runs is `ask-person`. ```text mainsdk next [--env ] [--json] ``` ## types Writes `.mainsdk/types/main.d.ts`, an interface `Declared` listing the hosts, events, flags, agents, secrets, features and actions `main.yaml` declares. `next` reports `MAIN-DEV-0004` while the file is older than `main.yaml`. ```text mainsdk types [--json] ``` ## mcp Runs an MCP server over stdio for a coding agent. The tools are `catalog.lookup` (answered from the catalog packed with this CLI), `project.info`, `check.run`, `discover.run`, `explain` and `next.run`; each answer is cut to 800 tokens unless the call passes `detail: "full"`. `fix.apply` is offered only with `--allow-write`; without it the call fails with `MAIN-DEV-0003`. Not the same as [`ops mcp`](#ops-mcp), which talks to a running app. ```text mainsdk mcp [--allow-write] ``` ## explain Explains an error code, a trace or the resolved config. Works offline from the local registry and event store. ```text mainsdk explain [--json] mainsdk explain config [--market ] [--segment ] [--env ] [--json] ``` `explain config` also takes `--target ` (milestone 1.1) and `--package

` (monorepos, milestone 0.7). Every value comes with the file and line it came from: ```text $ npx mainsdk explain config --market in --segment enterprise payments.driver = razorpay (main.in.yaml:1) payments.methods = ["cards"] (main.segment.enterprise.yaml:2) ``` With `--json` it prints `config` (the same object `resolveConfig` returns), `sources` (file and line by JSON pointer), `values` (one row per leaf with `path`, `value`, `file` and `line`) and the `exceptions` in use. A flag such as `--plan pro` selects a team dimension with its own `main.plan.pro.yaml`. ## incident Sets, clears and reads the incident controls (spec incident-controls). Every change goes through the config driver, needs `--reason`, writes an `incident.control` audit record and prints when it will have reached every instance. A control only tightens what `main.yaml` allows. ```text mainsdk incident on kill ... --reason "" [--expires 4h] [--env prod] mainsdk incident on read-only --reason "" [--expires 4h] mainsdk incident on sign-out [--tenant tnt_…] --reason "" mainsdk incident off kill | off read-only | off sign-out [--tenant tnt_…] --reason "" mainsdk incident status [--env prod] [--json] ``` A target is `action:`, `route:`, `interface:`, `driver:`, `agent:` or `tool:`. Without `--reason`, or with a config driver that cannot write, the command fails with `MAIN-INCIDENT-0005` and prints the key and value to set by hand. | Exit | Meaning | | --- | --- | | 0 | Done, or status printed | | 2 | Bad usage, no reason, or the driver cannot write | ## alerts test Sends a test alert, marked as a test, through every driver of one recipient and prints each result (spec alerts). ```text mainsdk alerts test [--env prod] [--json] ``` | Exit | Meaning | | --- | --- | | 0 | Every driver sent it | | 1 | At least one driver failed | | 2 | Bad usage or an invalid `alerts` section | ## status Lists every remote dependency, MainSDK services and each configured driver, with its state and since when. ```text mainsdk status [--json] ``` ```text $ npx mainsdk status mainsdk-cloud down since 10:02Z telemetry buffered (4,120 queued, 0 dropped) tuf stale since 09:40Z last good: baseline 27.0.3 db:postgres ok ``` ## norms Shows each configured metric's current bucket with its value count, median, p99 and whether it is still learning (spec norms). It reads this project's model; `mainsdk info` shows the same under `norms`. ```text mainsdk norms [--json] [--env ] ``` ```text $ npx mainsdk norms norms hour-of-week in Asia/Kolkata, one value per 1m requests all n 0 p50 0.000 p99 0.000 learning ``` ## analytics Asks the app's own analytics store a question and prints the rows, with the number of hidden small groups (spec analytics). It reads totals across tenants, so it is for the operator, and it needs `builtin` in `analytics.to`. ```text mainsdk analytics --query [--event ] [--window day|week|month] [--by ] [--from ] [--to ] [--steps ] [--within ] [--json] ``` ```text $ npx mainsdk analytics --query active --window month --by country country people IN 412 US 187 (2 groups hidden: fewer than 10 people) ``` See [track events](https://mainsdk.dev/docs/guides/track-events). ## errors Lists the error groups in the local event store, newest first, with count, first and last seen and release. ```text mainsdk errors [--since ] [--release ] [--json] ``` ## signals Prints the signals the local app recorded in `.mainsdk/events/`, newest first, with severity, subject, scope, count and age (spec signals). ```text mainsdk signals [--min ] [--name ] [--json] [--follow] ``` ```text $ npx mainsdk signals --min medium 4m high app.import_failed import:nightly instance x3 ``` ## playbooks Lists the rules, plans one without applying it, lists runs, and acts on a run in a running dev app through `.mainsdk/control/` (spec playbooks). A revert needs `--reason`. ```text mainsdk playbooks [list] [--json] mainsdk playbooks plan [--signal ] mainsdk playbooks runs [--state ] [--json] mainsdk playbooks approve | decline [--reason "..."] mainsdk playbooks revert --reason "..." mainsdk playbooks unquarantine ``` ## neighbours Shows this app's host bus settings, its socket name and the last host signals recorded in `.mainsdk/events/` (spec neighbours). `rotate-key` writes a new host key beside the apps folder. ```text mainsdk neighbours [--json] [--apps

] mainsdk neighbours rotate-key [--apps ] ``` ## apps Lists every MainSDK app recorded in the machine's registry folder (spec app-registry): project id, app, owner, version, seal state, boot check, last seen and destinations. It reads files only and makes no connection. Flags: `MAIN-INFO-0002` (broken seal), `MAIN-SEAL-0001` (boot check mismatch), `MAIN-APPS-0003` (stale), `MAIN-APPS-0002` (duplicate project id) and `MAIN-APPS-0006` (one side lists a peer that does not list it back). It exits 0, or 1 with `--strict` when any flag is raised. ```text mainsdk apps [--json] [--strict] [--apps ] mainsdk apps --actions [--risk read|write|destructive] [--json] mainsdk apps --prune ``` `--actions` lists the actions the sealed apps declare, with app, intent and risk. `--prune` deletes records stopped or stale for more than 30 days. The folder is `--apps`, then `MAINSDK_APPS_DIR`, then `~/.mainsdk/apps`. ## context Shows the shared context of this app (spec context): the group, the identity mode, the sinks and, for each purpose, who it shares with, how long it is kept, how many people said yes and how many flows went out and came in. The counts are plain numbers the running app keeps in the run folder. It prints no context id, user id or attribute value. `mainsdk info` shows a one-line summary and `ops.status` carries the same document. ```text mainsdk context [--json] [--env ] ``` ## fleet Reads the Fleet records an app owner or a CISO needs (specs fleet-control and fleet-prove). Every command reads files only and changes nothing. `log` lists the pushes that reached an app with the policy hash, signers, time, blast radius and an inclusion proof it verifies; a tampered log fails with exit 1. `scope` names the people, labels and regions a key, user or app touched in a time window. `timeline` prints the hash-chained forensic timeline and the position where it breaks. `evidence` writes a ZIP bundle for one standard and period (`MAIN-FLEET-0011` for an unknown standard). `admit` refuses a release that lacks a required deploy mark (`MAIN-FLEET-0007`). `mainsdk check` also fails a build that includes a blocked package (`MAIN-FLEET-0006`). ```text mainsdk fleet log --app [--json] mainsdk fleet scope [--key |--user |--app ] --from --to [--json] mainsdk fleet timeline [--app ] [--from ] [--to ] [--json] mainsdk fleet evidence --standard --period .. --out mainsdk fleet admit [--env ] [--marks ] [--json] ``` The state folder is `--state`, then `MAINSDK_FLEET_DIR`, then `.mainsdk/fleet`. See [Read your Fleet records](https://mainsdk.dev/docs/guides/read-your-fleet-records). The pilot commands are for MainSDK staff and need `--staff ` or `MAINSDK_STAFF` (`MAIN-PILOT-0006` otherwise); their state is under `/pilots`. `verify` prints the TXT record that proves an organisation's domain and exits 1 until it resolves (`MAIN-PILOT-0001`). `tenant create` makes a `ten_` tenant in a region. `pilot enrol` puts a partner's project in its tenant with signed proof and an audit line (`MAIN-PILOT-0003` for another organisation's project). `pilot add` writes the pilot register, `pilot role` sets the tenant's delegated key role, and `pilots` lists partners and the count toward the gate of 10. ```text mainsdk fleet verify [--org ] [--json] mainsdk fleet tenant create --org --region us|eu|in [--json] mainsdk fleet pilot enrol --tenant --project [--json] mainsdk fleet pilot add --org --started [--name ] [--paid] [--tenant ] mainsdk fleet pilot role --tenant --key = [--key …] [--threshold ] mainsdk fleet pilots [--json] ``` The inventory commands (specs fleet-discover and fleet-observe) read a snapshot, `/visibility/.json`, and change nothing. `apps` lists every app with owner, environment, version, mark and last release, and coverage as verified over total. `surface` exports the attack surface as `k8s-networkpolicy`, `vercel-firewall` or `aws-sg` (`MAIN-FLEET-0015` for another name). `map` lists data flows to providers, narrowed by `--label` and `--region-outside`. `broken` lists apps failing an SLO now. `sbom find` lists the apps and releases running a package version (`MAIN-FLEET-0016` when the query is not `name@version`). `vulns` lists reachable issues ranked by KEV and EPSS. See [See every app you run](https://mainsdk.dev/docs/guides/see-your-whole-estate). ```text mainsdk fleet apps --tenant [--json] mainsdk fleet surface --tenant --export mainsdk fleet map --tenant [--label