# os — OpenSteward CLI

> The os binary is the single operator + developer-facing CLI for an OpenSteward deployment. Every subcommand under a vertical or tag group (os users, os platforms, os auth,…

<!-- AUTOGENERATED by `pnpm docs:cli` — do not edit by hand. -->



The `os` binary is the single operator + developer-facing CLI for an OpenSteward deployment. Every subcommand under a vertical or tag group (`os users`, `os platforms`, `os auth`, etc.) is **generated mechanically** from the OpenAPI specs at `docs/openapi/admin-api.openapi.json` (operator) and `docs/openapi/openapi.json` (public). Renaming a route in the spec renames the matching command on the next `pnpm cli:generate`.

Install:

```bash
pnpm add -g @opensteward/cli
# or, ad-hoc:
npx @opensteward/cli --help
```


## Top-level usage

```text
Usage: os [options] [command]

OpenSteward CLI — operator + developer surface, generated from the OpenAPI specs

Options:
  -V, --version            output the version number
  --base-url <url>         admin-api or integration-server base URL
  --test                   target the /test/v1 sandbox with an osk_test_ key
                           (public API commands)
  --token <jwt>            bearer token (overrides credentials file + env)
  --json                   emit raw JSON instead of the renderer-chosen format
  --jsonpath <expr>        JSONPath filter to apply to the response
  --quiet                  suppress non-essential output
  --no-color               disable ANSI color in output
  -h, --help               display help for command

Commands:
  accounting               accounting subcommands
  api-keys                 api-keys subcommands
  audit                    audit subcommands
  auth                     auth subcommands
  company-info             company-info subcommands
  connect-link-templates   connect-link-templates subcommands
  connect-sessions         connect-sessions subcommands
  connections              connections subcommands
  crm                      crm subcommands
  customer-support         customer-support subcommands
  dashboard-tasks          dashboard-tasks subcommands
  dashboards               dashboards subcommands
  data                     data subcommands
  destinations             destinations subcommands
  docsign                  docsign subcommands
  ecommerce                ecommerce subcommands
  end-user-tokens          end-user-tokens subcommands
  end-users                end-users subcommands
  events                   events subcommands
  identity-providers       identity-providers subcommands
  inventory                inventory subcommands
  license                  license subcommands
  logistics                logistics subcommands
  logos                    logos subcommands
  notifications            notifications subcommands
  oauth-clients            oauth-clients subcommands
  payments                 payments subcommands
  platform                 platform subcommands
  platforms                platforms subcommands
  projects                 projects subcommands
  roles                    roles subcommands
  runtime-settings         runtime-settings subcommands
  sandbox                  sandbox subcommands
  schema-status            schema-status subcommands
  scim                     scim subcommands
  scope-groups             scope-groups subcommands
  sql-access               sql-access subcommands
  sso                      sso subcommands
  superset                 superset subcommands
  sync-jobs                sync-jobs subcommands
  tenants                  tenants subcommands
  users                    users subcommands
  verticals                verticals subcommands
  webhook-subs             webhook-subs subcommands
  webhook-subscriptions    webhook-subscriptions subcommands
  backup [args...]         Snapshot every docker volume + .env + config files
                           into a single tarball
  restore [args...]        Restore an OpenSteward backup tarball (counterpart of
                           `os backup`)
  doctor [args...]         Preflight checks: env vars, config drift, disk,
                           schema versions, encrypted-blob round-trip, license
  rotate-secret [args...]  Rotate STORE_ENCRYPTION_KEY on every SQLite db
                           (offline; refuses if WAL is fresh)
  setup                    Interactive first-run setup: authenticate, brand,
                           enable platforms, mint a key
  help [command]           display help for command
```

## Generated command groups

Each of the groups below was generated from the OpenAPI specs and exposes one subcommand per operation in the matching tag. Help text, flags, required-ness, and response renderers are all derived from the spec — see [`docs/openapi/admin-api.openapi.json`](https://docs.opensteward.dev/downloads/openapi/admin-api.openapi.json) and [`docs/openapi/openapi.json`](https://docs.opensteward.dev/downloads/openapi/openapi.json) for the source.

### `os accounting`

```text
Usage: os accounting [options] [command]

accounting subcommands

Options:
  -h, --help                              display help for command

Commands:
  create-bill [options]                   Create bill
  create-contact [options]                Create contact
  create-creditmemo [options]             Create credit memo
  create-expense [options]                Create expense
  create-invoice [options]                Create invoice
  create-journal [options]                Create journal
  create-order [options]                  Create order
  create-purchaseorder [options]          Create purchase order
  create-salesorder [options]             Create sales order
  delete-bill [options] <id>              Delete bill
  delete-contact [options] <id>           Delete contact
  delete-invoice [options] <id>           Delete invoice
  get-account-by-id [options] <id>        Get account
  get-bill-by-id [options] <id>           Get bill
  get-contact-by-id [options] <id>        Get contact
  get-creditmemo-by-id [options] <id>     Get credit memo
  get-expense-by-id [options] <id>        Get expense
  get-invoice-by-id [options] <id>        Get invoice
  get-journal-by-id [options] <id>        Get journal
  get-order-by-id [options] <id>          Get order
  get-purchaseorder-by-id [options] <id>  Get purchase order
  get-quote-by-id [options] <id>          Get quote
  get-salesorder-by-id [options] <id>     Get sales order
  get-taxrate-by-id [options] <id>        Get tax rate
  get-transaction-by-id [options] <id>    Get transaction
  list-accounts [options]                 List accounts
  list-bills [options]                    List bills
  list-contacts [options]                 List contacts
  list-creditmemos [options]              List credit memos
  list-expenses [options]                 List expenses
  list-invoices [options]                 List invoices
  list-journals [options]                 List journals
  list-orders [options]                   List orders
  list-organizations [options]            Get organisation
  list-purchaseorders [options]           List purchase orders
  list-quotes [options]                   List quotes
  list-salesorders [options]              List sales orders
  list-taxrates [options]                 List tax rates
  list-transactions [options]             List transactions
  update-bill [options] <id>              Update bill
  update-contact [options] <id>           Update contact
  update-invoice [options] <id>           Update invoice
  help [command]                          display help for command
```

### `os api-keys`

```text
Usage: os api-keys [options] [command]

api-keys subcommands

Options:
  -h, --help             display help for command

Commands:
  create [options]       Mint a new tenant API key (plaintext returned once) —
                         Mint a new tenant-scoped developer API key. Admin role
                         required. The response includes the plaintext key
                         **once** — it is not stored and cannot be retrieved
                         again. Returns `400` if `tenantId` is missing. Writes
                         an `api_key.mint` audit entry.
  delete <id>            Revoke a tenant API key — Permanently revoke a tenant
                         API key by id, taking effect immediately. Admin role
                         required. Returns `404` if no key matches the id.
                         Writes an `api_key.revoke` audit entry.
  list [options]         List tenant API keys (active + revoked) — List
                         developer API keys (both active and revoked) for the
                         deployment, optionally filtered to one tenant via
                         `tenantId` and to one key mode via `mode`. Operator
                         role or higher — an operator can check whether a key is
                         active without being able to mint one. Returns key
                         metadata only; the plaintext secret is never included.
  rotate [options] <id>  Rotate a tenant API key (replacement plaintext returned
                         once) — Mint a replacement key with the same tenant,
                         label, scopes and mode, and schedule the old key’s
                         revocation after a grace window (default 24h) in which
                         both keys work — no downtime gap while the new key is
                         rolled out. Admin role required. The response includes
                         the replacement’s plaintext **once**. Returns `404`
                         when the key does not exist, is revoked or expired, or
                         was already rotated inside its grace window. Writes an
                         `api_key.rotate` audit entry.
  help [command]         display help for command
```

### `os audit`

```text
Usage: os audit [options] [command]

audit subcommands

Options:
  -h, --help        display help for command

Commands:
  actions           Every audit action the registry knows — The typed action
                    vocabulary, for building filter UIs without hand-typing
                    exact dotted action literals. Admin role required.
  export [options]  Export audit-log entries as CSV or JSON — Export the
                    (optionally filtered) audit log as a downloadable `csv`
                    (default) or `json` attachment, supporting the same filters
                    as the list endpoint. Admin role required. Streamed from a
                    SQLite cursor so large logs do not materialise at once, and
                    the export itself is recorded as an `audit.export` audit
                    entry.
  list [options]    List audit-log entries, newest first — List operator
                    audit-log entries (paginated, newest first; `limit` capped
                    at 200). Admin role required. Supports filtering by
                    `action`, `user_id`, `target_id` (exact match on the
                    acted-on id — “everything that happened to key X”),
                    `vertical` (case-insensitive substring), and a `from`/`to`
                    date range (ISO-8601 or epoch-ms), plus `sort`/`dir` to
                    order the result. Filters and ordering are applied in SQL
                    before the page slice, so `meta.total` reflects the filtered
                    set and every page reflects the requested order.
  help [command]    display help for command
```

### `os auth`

```text
Usage: os auth [options] [command]

auth subcommands

Options:
  -h, --help       display help for command

Commands:
  has-users        Whether any admin user exists yet (first-run check) —
                   Read-only check the setup wizard uses to decide whether to
                   show the first-run form. No authentication required and no
                   side effects. Returns `{ hasUsers: false }` on a fresh
                   deployment, `{ hasUsers: true }` once the first admin has
                   been created.
  login [options]  Sign in with username + password — Exchange a username and
                   password for a JWT used to authenticate subsequent admin-api
                   calls. No prior authentication required. Subject to lockout
                   after repeated failures (returns `429`, with a `Retry-After`
                   header for temporary locks). Returns `400` if either field is
                   missing, `401` on invalid credentials, and `403` when local
                   login is disabled and the account is not the pinned
                   break-glass admin (SSO-only). Writes a `user.login` audit
                   entry on success.
  me               Return the calling user, with permissions and tenant scope —
                   Return the decoded JWT claims (id, username, role) for the
                   currently authenticated operator, plus the caller's effective
                   role (`roleId`, `roleName`), `permissions` and tenant
                   `scope`. The last three are read from the database on each
                   call (cached for a few seconds), so they reflect a role or
                   scope change made since the token was issued. Any
                   authenticated operator may call this; useful for confirming a
                   token is valid and discovering what the caller may do.
                   Returns `401` if the token is missing or invalid.
  setup [options]  First-run admin bootstrap (only succeeds when no users exist)
                   — Bootstrap the first `admin` account on a fresh deployment
                   and return a JWT for it. Only succeeds while the user table
                   is empty — returns `409` once any user exists. When the
                   server is started with a `BOOTSTRAP_TOKEN`, the matching
                   token must be supplied in the `X-Bootstrap-Token` header
                   (else `401`), so a fresh or wiped deployment cannot be
                   claimed by an attacker. When NO token is configured, setup is
                   refused from non-loopback addresses (`403`) — a remote
                   first-run must carry a `BOOTSTRAP_TOKEN`; only a caller on
                   the deployment host may set up tokenless. The created admin
                   is auto-pinned as the break-glass account so SSO can be
                   locked down later without losing password access. Returns
                   `400` if username or password is missing.
  help [command]   display help for command
```

### `os company-info`

```text
Usage: os company-info [options] [command]

company-info subcommands

Options:
  -h, --help        display help for command

Commands:
  get               Read the company-info record (auth-required) — Read the full
                    company-info record (branding plus operator settings) so the
                    admin UI can render the navbar logo and settings forms. Any
                    authenticated operator. Returns `data: null` when no record
                    has been saved yet.
  get-public        Public branding subset (no auth) — Return only the public
                    branding subset (name, logo, colours, support email,
                    privacy/ToS links, base URL) with **no authentication**.
                    Consumed server-to-server by the hosted Connect Link page to
                    render the host's brand. Sensitive operator settings are
                    never exposed here.
  reset             Reset the company-info record to the defaults — Delete the
                    company-info record (branding and operator settings),
                    returning the deployment to the defaults it ships with: `GET
                    /api/company-info` answers `data: null` again and every
                    branded surface falls back to OpenSteward's own. Admin role
                    required. Idempotent — resetting when nothing is saved also
                    answers `204`. Writes a `company_info.reset` audit entry.
  update [options]  Upsert the company-info record — Create or replace the
                    single company-info record (branding and operator settings).
                    Admin role required. Returns `400` with validation issues if
                    the body fails schema validation. Writes a
                    `company_info.update` audit entry.
  help [command]    display help for command
```

### `os connect-link-templates`

```text
Usage: os connect-link-templates [options] [command]

connect-link-templates subcommands

Options:
  -h, --help             display help for command

Commands:
  create [options]       Create a Connect Link template — Create a Connect Link
                         template defining the link mode, allowed
                         verticals/platforms, scope group, expiry, and redirect
                         for links generated from it. Operator role or higher.
                         Returns `400` if `tenantId`/`name` is missing or
                         `linkMode` is invalid, and `409` if a template with
                         that name already exists for the tenant. Writes a
                         `connect_link_template.create` audit entry.
  delete <id>            Delete a Connect Link template — Delete a Connect Link
                         template by id. Operator role or higher. Returns `400`
                         for a non-numeric id and `404` if the template does not
                         exist. Writes a `connect_link_template.delete` audit
                         entry.
  get <id>               Read one Connect Link template — Read a single Connect
                         Link template by id. Any authenticated operator.
                         Returns `400` for a non-numeric id and `404` if the
                         template does not exist.
  list [options]         List Connect Link templates — List Connect Link
                         templates (reusable presets that define what a
                         generated link lets a customer connect), optionally
                         filtered by `tenantId`. Any authenticated operator.
  update [options] <id>  Update a Connect Link template — Update a Connect Link
                         template; omitted fields are left unchanged. Operator
                         role or higher. Returns `400` for a non-numeric id or
                         invalid `linkMode`, and `404` if the template does not
                         exist. Writes a `connect_link_template.update` audit
                         entry.
  help [command]         display help for command
```

### `os connect-sessions`

```text
Usage: os connect-sessions [options] [command]

connect-sessions subcommands

Options:
  -h, --help        display help for command

Commands:
  create [options]  Mint a Connect Link session — Mint a new Connect Link
                    session and return its hosted authorization URL to hand to
                    an end-user. Operator role or higher. The requesting
                    operator is recorded as `created_by`. Writes a
                    `connect_session.create` audit entry.
  delete <id>       Revoke a Connect Link session — Revoke a Connect Link
                    session by id, invalidating its authorization URL
                    immediately. Operator role or higher. Writes a
                    `connect_session.revoke` audit entry.
  get <id>          Read one Connect Link session — Read a single Connect Link
                    session by id, including its current status. Any
                    authenticated operator. Returns `404` if the session does
                    not exist.
  list [options]    List Connect Link sessions — List Connect Link sessions (the
                    hosted authorization flows end-users complete to link an
                    integration), with optional filters for `tenantId`,
                    `endUserId`, `status`, and `limit`/`offset` pagination. Any
                    authenticated operator.
  help [command]    display help for command
```

### `os connections`

```text
Usage: os connections [options] [command]

connections subcommands

Options:
  -h, --help                                   display help for command

Commands:
  delete <vertical> <id>                       Revoke a connection — Revoke a connection by vertical and id, deleting its stored credentials. Operator role or higher. Returns `404` if the vertical is unknown or the connection is not found. Writes a `connection.delete` audit entry.
  get <vertical> <id>                          Fetch a single connection — Fetch one connection by its vertical and id. Any authenticated operator. Returns `404` if the vertical is unknown, no connection with that id exists in it, or the connection belongs to a tenant outside the caller's scope.
  list [options]                               List connections across every configured vertical — List all active integration connections aggregated across every configured vertical, with optional filters for `vertical`, `status`, `platform`, per-column filters (`f_label`, `f_id`, `f_vertical`, `f_status`, `f_platform`, `f_tenant`), a `search` over connection id and label, and `sort`/`dir` to order the result. Filters apply before pagination, so `meta.total` reflects the filtered set, and sorting is applied before the slice, so every page reflects the requested order. A tenant-restricted caller sees only connections owned by its granted tenants (and verticals); connections with no tenant are hidden from it. Any authenticated operator.
  set-sync-schedule [options] <vertical> <id>  Set a connection's sync schedule — Choose how often a connection's data is re-synced: `default` (the deployment interval), `custom` (every `intervalMinutes`, 15–43200), `trigger_only` (only when a sync is requested — never automatically) or `once` (one sync when connected). Takes effect on the scheduler's next tick. Operator role or higher. Returns `404` if the vertical is unknown, the connection is not found, or it belongs to a tenant outside the caller's scope; `400` for an invalid schedule. Writes a `connection.sync_schedule` audit entry with the previous and new schedule.
  update [options] <vertical> <id>             Rename a connection — Rename a connection by vertical and id. The label is the only mutable field — it is what the admin UI and `GET /api/connections?search=` match on, so it is how an operator tells two connections to the same platform apart. Send `null` to clear it. Operator role or higher. Returns `404` if the vertical is unknown or the connection is not found, and `409` if another connection for the same tenant and platform already carries that label. Writes a `connection.update` audit entry.
  help [command]                               display help for command
```

### `os crm`

```text
Usage: os crm [options] [command]

crm subcommands

Options:
  -h, --help                         display help for command

Commands:
  create-activity [options]          Create activity
  create-company [options]           Create company
  create-contact [options]           Create contact
  create-deal [options]              Create deal
  create-note [options]              Create note
  delete-activity [options] <id>     Delete activity
  delete-company [options] <id>      Delete company
  delete-contact [options] <id>      Delete contact
  delete-deal [options] <id>         Delete deal
  delete-note [options] <id>         Delete note
  get-activity-by-id [options] <id>  Get activity
  get-company-by-id [options] <id>   Get company
  get-contact-by-id [options] <id>   Get contact
  get-deal-by-id [options] <id>      Get deal
  get-note-by-id [options] <id>      Get note
  get-pipeline-by-id [options] <id>  Get pipeline
  list-activities [options]          List activities
  list-companies [options]           List companies
  list-contacts [options]            List contacts
  list-deals [options]               List deals
  list-notes [options]               List notes
  list-pipelines [options]           List pipelines
  update-activity [options] <id>     Update activity
  update-company [options] <id>      Update company
  update-contact [options] <id>      Update contact
  update-deal [options] <id>         Update deal
  update-note [options] <id>         Update note
  help [command]                     display help for command
```

### `os customer-support`

```text
Usage: os customer-support [options] [command]

customer-support subcommands

Options:
  -h, --help                  display help for command

Commands:
  get-contact [options] <id>  Get contact — Fetches a single contact by id.
  get-macro [options] <id>    Get macro — Fetches a single macro by id.
  get-message [options] <id>  Get message — Fetches a single message by id.
  get-tag [options] <id>      Get tag — Fetches a single tag by id.
  get-team [options] <id>     Get team — Fetches a single team by id.
  get-ticket [options] <id>   Get ticket — Fetches a single ticket by id.
  get-user [options] <id>     Get agent — Fetches a single agent by id.
  list-contacts [options]     List contacts — Returns contacts. PII-minimal
                              (name + email + phone only).
  list-macros [options]       List macros (canned responses) — Returns
                              canned-response templates. Platforms without this
                              surface return [].
  list-messages [options]     List messages for a ticket — Returns messages
                              under the given ticket. Body text included
                              verbatim. Internal-note PII redaction is the
                              operator's responsibility at consume-time.
  list-tags [options]         List tags — Returns tags (ticket taxonomy).
  list-teams [options]        List agent teams — Returns agent groups / teams.
  list-tickets [options]      List tickets — Returns tickets visible to the
                              connection. Schema-firewall: no attachment
                              content, no voice recordings.
  list-users [options]        List agents — Returns support agents.
  help [command]              display help for command
```

### `os dashboard-tasks`

```text
Usage: os dashboard-tasks [options] [command]

dashboard-tasks subcommands

Options:
  -h, --help         display help for command

Commands:
  dismiss [options]  Clear dashboard tasks — Clear 1..50 dashboard tasks
                     deployment-wide. Also acknowledges the matching
                     unacknowledged notifications (`credential_expired` for
                     `conn:expired:*`, `platform_credentials_invalid` for
                     `platform:creds:*`), and the health poller will not
                     re-raise them while the fingerprint is unchanged. Operator
                     role or higher; Refused (`403 SCOPE_RESTRICTED`) for a user
                     restricted to specific tenants: it affects every tenant.
                     `platform:creds:*` and `wizard:*` keys need the admin role,
                     and one such key in the batch makes the whole request `403`
                     with nothing stored. Writes a `dashboard_task.dismiss`
                     audit entry.
  list-dismissals    List cleared dashboard tasks — Every dashboard task that
                     has been cleared, with the fingerprint it was cleared at.
                     The dashboard hides a task only when both the key and the
                     fingerprint match. Any authenticated operator. A
                     tenant-restricted user sees only the keys whose connection
                     or sync job is inside their scope.
  undismiss <key>    Un-clear a dashboard task — Remove one clear so the task
                     shows on the dashboard again (the Undo behind a clear).
                     Operator role or higher; Refused (`403 SCOPE_RESTRICTED`)
                     for a user restricted to specific tenants: it affects every
                     tenant. `platform:creds:*` and `wizard:*` keys need the
                     admin role (`403` otherwise). Returns `404` when the key
                     was not cleared. Writes a `dashboard_task.undismiss` audit
                     entry.
  help [command]     display help for command
```

### `os dashboards`

```text
Usage: os dashboards [options] [command]

dashboards subcommands

Options:
  -h, --help             display help for command

Commands:
  connections            connections subcommands
  create [options]       Create a dashboard — Create a dashboard from up to 24
                         widgets, each naming a catalog metric, a chart type and
                         a width (1–12 columns). Shared per `audience` (default
                         `private`); `everyone` needs `dashboards:share_all`,
                         and a caller with restricted access may share with and
                         pin only tenants in that access (`403`). Requires
                         `dashboards:edit`. `400` for a metric not in your
                         catalog, a chart that is not one of its metric's
                         `charts` (`Chart <chart> does not fit <metric>`) or an
                         unknown tenant. Writes `dashboard.create` and, when
                         shared or pinned, `dashboard.share` audit entries.
  currencies             currencies subcommands
  delete <id>            Delete a dashboard — Delete your own dashboard (admins
                         may delete any). Requires `dashboards:edit`. `409` for
                         a built-in, `403` for someone else’s, `404` when it
                         does not exist. Writes a `dashboard.delete` audit
                         entry.
  get <id>               Read one dashboard — A built-in dashboard, or one
                         shared with you. Requires `dashboards:view`. `404` for
                         an unknown id or a dashboard not shared with you.
  list                   List dashboards — The built-in dashboards, then every
                         dashboard shared with you (your own, those shared with
                         a tenant in your access, those shared with everyone; an
                         admin with access to every tenant sees all), most
                         recently updated first. Requires `dashboards:view`.
  metrics                metrics subcommands
  update [options] <id>  Edit a dashboard — Edit your own dashboard (admins may
                         edit any); omitted fields are unchanged. Requires
                         `dashboards:edit`. `409` for a built-in dashboard,
                         `403` for someone else’s or a sharing change you may
                         not make, `400` for an unknown tenant, a metric not in
                         your catalog or a chart that does not fit its metric,
                         `404` when it does not exist or is not visible to you.
                         Writes a `dashboard.update` audit entry, and
                         `dashboard.share` when the audience or pins change.
  help [command]         display help for command
```

### `os data`

```text
Usage: os data [options] [command]

data subcommands

Options:
  -h, --help                display help for command

Commands:
  records                   records subcommands
  schema <vertical> <type>  Describe a stored resource type — Fields of a stored
                            resource type with their classification (`public`,
                            `internal`, `pii`, `financial`, `secret`) and
                            whether you may filter on them. Requires
                            `data:read`. `404` for an unknown type or one
                            outside your scope.
  summary                   Summarise stored data per connection — List every
                            connection in your tenant scope with the resource
                            types the data store holds for it: record counts,
                            the newest change and when each type was last fully
                            synced. Requires `data:read`. Answers `409`
                            (`DATA_STORE_DISABLED`) when the deployment runs in
                            passthrough mode.
  help [command]            display help for command
```

### `os destinations`

```text
Usage: os destinations [options] [command]

destinations subcommands

Options:
  -h, --help                  display help for command

Commands:
  backfill [options] <id>     Backfill a destination — Reset the export cursors
                              — all of them, one vertical’s, or one resource
                              type’s — so the next run re-exports every stored
                              record in scope, then start a run unless `run:
                              false`. Consumers should deduplicate on `_pk`.
                              Requires `destinations:manage`; audited as
                              `destination.backfill`.
  create [options]            Create a destination — Create a destination.
                              `config` and `secrets` follow the type's schemas
                              (`GET /api/destinations/types`); secrets are
                              stored encrypted and never returned. `scope` must
                              lie inside your own (`403`
                              `SCOPE_EXCEEDS_CALLER`); `includePii` needs
                              `data:read_pii` (`403` `PII_NOT_PERMITTED`) and
                              records you as approver. Every host named must be
                              public unless allow-listed (`400`
                              `HOST_NOT_ALLOWED`). Requires
                              `destinations:manage`; audited as
                              `destination.create`.
  credentials [options] <id>  Replace (rotate) destination credentials — Replace
                              every secret of a destination with the ones given
                              (fields left out are cleared). Values are
                              write-only: the response lists only the names set,
                              and the audit row
                              (`destination.credentials_rotate`) records names
                              only. On a PII destination this needs
                              `data:read_pii`. Requires `destinations:manage`.
  delete <id>                 Delete a destination — Delete a destination with
                              its cursors and run history. Files and rows
                              already exported stay where they are. Requires
                              `destinations:manage`; audited as
                              `destination.delete`.
  get <id>                    Get a destination — One destination. `404` when
                              unknown or outside your scope. Requires
                              `destinations:manage`.
  list                        List destinations — Destinations whose scope lies
                              inside yours, with their last run. Requires
                              `destinations:manage`. `409` `DATA_STORE_DISABLED`
                              in passthrough mode.
  run <id>                    Run a destination now — Start an export run now,
                              outside the schedule. `202` with the run id; `409`
                              `RUN_IN_PROGRESS` when one is already running,
                              `409` `DESTINATION_DISABLED` when it is disabled.
                              Requires `destinations:manage`; audited as
                              `destination.run`.
  runs [options] <id>         List destination runs — Run history of a
                              destination, newest first: trigger, status, rows
                              and deletions written, files, and the error of a
                              failed run. Requires `destinations:manage`.
  test <id>                   Test a destination connection — Build the sink
                              with the stored credentials and prove it can
                              write: a probe object in the bucket, or `CREATE`
                              on the Postgres schema. A failed test still
                              answers `200` with `ok: false` and the reason.
                              Requires `destinations:manage`; audited as
                              `destination.test`.
  types                       List destination types — Every destination type
                              with its settings form: the non-secret config and
                              write-only secret fields as JSON Schema (types,
                              defaults, descriptions). Types flagged
                              `experimental` work but may still change; a type
                              listed with `available: false` cannot be created.
                              Requires `destinations:manage`.
  update [options] <id>       Change a destination — Change a destination’s
                              name, config, scope, PII setting, interval or
                              enabled state. Changing the config, scope or PII
                              of a PII destination needs `data:read_pii`;
                              turning it off or disabling it does not. Widening
                              the scope does not re-export skipped rows: run a
                              backfill. Requires `destinations:manage`; audited
                              as `destination.update`.
  help [command]              display help for command
```

### `os docsign`

```text
Usage: os docsign [options] [command]

docsign subcommands

Options:
  -h, --help                            display help for command

Commands:
  get-audit-trail-entry [options] <id>  Get audit-trail entry — Fetches a single
                                        audit-trail entry by id.
  get-document [options] <id>           Get document (metadata only) — Fetches
                                        document metadata by id. Body content is
                                        not returned.
  get-envelope [options] <id>           Get envelope — Fetches a single envelope
                                        by id.
  get-signer [options] <id>             Get signer — Fetches a single signer by
                                        id.
  get-template [options] <id>           Get template — Fetches a single template
                                        by id.
  list-audit-trail-entries [options]    List audit-trail entries for an envelope
                                        — Returns first-class audit-trail
                                        entries for the given envelope.
  list-documents [options]              List documents for an envelope (metadata
                                        only) — Returns document metadata
                                        (filename, size, page count) for the
                                        given envelope. Document content is
                                        intentionally not exposed.
  list-envelopes [options]              List envelopes — Returns
                                        signing-envelope records (subject,
                                        signer list, status, timestamps).
  list-signers [options]                List signers for an envelope — Returns
                                        signers (recipients) on the given
                                        envelope.
  list-templates [options]              List templates — Returns reusable
                                        envelope templates with signer roles and
                                        document counts.
  void-envelope [options] <id>          Void envelope — Voids an open envelope.
                                        Already-completed envelopes are
                                        immutable.
  help [command]                        display help for command
```

### `os ecommerce`

```text
Usage: os ecommerce [options] [command]

ecommerce subcommands

Options:
  -h, --help                                display help for command

Commands:
  adjust-inventory-level [options]          Adjust inventory level — Applies a signed delta to the current available quantity for a given variant at a given location. Positive delta adds stock, negative subtracts. Returns `501` for read-only adapters.
  cancel-fulfillment [options] <id>         Cancel fulfillment — Cancels a fulfillment. Many platforms only allow cancellation of fulfillments that have not yet shipped.
  cancel-order [options] <id>               Cancel order — Cancels an order. Some platforms reject cancellation of partially fulfilled orders; consult the adapter docs.
  create-collection [options]               Create collection — Creates a new collection. Returns `501` for adapters without write support.
  create-customer [options]                 Create customer — Creates a new customer record. Adapters that do not expose customer creation return `501`.
  create-discount [options]                 Create discount — Creates a new discount. Returns `501` for adapters without write support.
  create-fulfillment [options]              Create fulfillment — Creates a fulfillment for an existing order. The request body must include the parent `orderId` and the line items being fulfilled.
  create-order [options]                    Create order — Creates a new draft or confirmed order. Most headless platforms support this; storefront-only platforms return `501`.
  create-product [options]                  Create product — Creates a new product on the target platform. Not all platforms expose product creation — returns `501` for unsupported adapters.
  create-refund [options]                   Create refund — Creates a refund against an order. The request body must include the parent `orderId` and the refunded line items / amount.
  create-transaction [options]              Create transaction — Records a new transaction against an order (e.g. a manual capture or external payment). Not all platforms expose this — returns `501` otherwise.
  create-variant [options]                  Create product variant — Creates a new variant on an existing product. The request body must include the parent `productId`.
  delete-collection [options] <id>          Delete collection — Deletes a collection by ID. Product memberships are typically removed but the products themselves are preserved.
  delete-customer [options] <id>            Delete customer — Deletes a customer by ID. Many platforms anonymise rather than hard-delete for compliance reasons.
  delete-discount [options] <id>            Delete discount — Deletes a discount by ID. Historical usage on existing orders is preserved.
  delete-product [options] <id>             Delete product — Deletes a product by ID. Many platforms soft-delete or archive instead of hard-deleting; consult the adapter docs for semantics.
  delete-variant [options] <id>             Delete product variant — Deletes a variant by ID. Some platforms reject deleting the last variant of a product.
  get-collection-by-id [options] <id>       Get collection — Fetches a single collection by ID.
  get-customer-by-id [options] <id>         Get customer — Fetches a single customer by ID.
  get-discount-by-id [options] <id>         Get discount — Fetches a single discount by ID.
  get-fulfillment-by-id [options] <id>      Get fulfillment — Fetches a single fulfillment by ID.
  get-inventory-level-by-id [options] <id>  Get inventory level — Fetches a single inventory level. The `id` is typically a composite of `variantId:locationId` for platforms without first-class inventory IDs.
  get-location-by-id [options] <id>         Get location — Fetches a single location by ID.
  get-order-by-id [options] <id>            Get order — Fetches a single order including line items, fulfillments, and refunds.
  get-product-by-id [options] <id>          Get product — Fetches a single product by its platform-specific ID.
  get-refund-by-id [options] <id>           Get refund — Fetches a single refund by ID.
  get-transaction-by-id [options] <id>      Get transaction — Fetches a single transaction by ID.
  get-variant-by-id [options] <id>          Get variant — Fetches a single product variant by its platform-specific ID.
  list-collections [options]                List collections — Returns all collections (also known as categories or taxonomies on some platforms).
  list-customers [options]                  List customers — Returns customers visible to the authenticated connection. Supports incremental sync via `updated_after`.
  list-discounts [options]                  List discounts — Returns all discount codes and automatic discounts configured on the platform.
  list-fulfillments [options]               List fulfillments — Returns fulfillments across orders. Some adapters expose fulfillments only via their parent order — those return `501` on this endpoint.
  list-inventory-levels [options]           List inventory levels — Returns per-variant / per-location inventory quantities. Filter with `variantId` or `locationId` query parameters when supported by the adapter.
  list-locations [options]                  List locations — Returns all inventory locations / warehouses configured on the platform. Single-location platforms return a single synthetic entry.
  list-orders [options]                     List orders — Returns all orders (historical + open). Use `updated_after` for efficient incremental sync.
  list-products [options]                   List products — Returns all products visible to the authenticated connection. Supports incremental sync via `updated_after` and platform-native pagination (cursor or offset).
  list-refunds [options]                    List refunds — Returns refunds across orders. Supports incremental sync via `updated_after`.
  list-transactions [options]               List transactions — Returns payment transactions (authorisations, captures, voids, refunds) across orders.
  list-variants [options]                   List product variants — Returns variants across all products. Some platforms nest variants inside products — for those adapters this endpoint lists variants lazily and returns `501` if unsupported.
  set-inventory-level [options]             Set inventory level — Sets the absolute available quantity for a given variant at a given location. Prefer `/adjust` where possible to avoid race conditions between multiple writers.
  update-collection [options] <id>          Update collection — Partially updates a collection.
  update-customer [options] <id>            Update customer — Partially updates a customer record.
  update-discount [options] <id>            Update discount — Partially updates a discount.
  update-fulfillment [options] <id>         Update fulfillment — Partially updates a fulfillment — typically used to attach or update tracking information.
  update-order [options] <id>               Update order — Partially updates an order. Many platforms restrict which fields are mutable after payment or fulfillment.
  update-product [options] <id>             Update product — Partially updates a product. Only fields present in the request body are modified. Returns `501` for adapters without write support.
  update-variant [options] <id>             Update product variant — Partially updates a variant. Only fields present in the body are modified.
  help [command]                            display help for command
```

### `os end-user-tokens`

```text
Usage: os end-user-tokens [options] [command]

end-user-tokens subcommands

Options:
  -h, --help        display help for command

Commands:
  create [options]  Mint a per-end-user MCP token — Mint an MCP token scoped to
                    a single end-user. Operator role or higher. The response
                    includes the plaintext token **once** — it cannot be
                    retrieved again. Returns `400` if `endUserId` or `tenantId`
                    is missing. Writes an `end_user_token.mint` audit entry.
  delete <id>       Revoke a per-end-user MCP token — Revoke a per-end-user MCP
                    token by id, effective immediately. Operator role or higher.
                    Returns `404` if no token matches the id. Writes an
                    `end_user_token.revoke` audit entry.
  list [options]    List per-end-user MCP tokens — List MCP tokens scoped to
                    individual end-users, optionally filtered by `endUserId` or
                    `tenantId`. Operator role or higher. Returns token metadata
                    only; plaintext secrets are never included.
  help [command]    display help for command
```

### `os end-users`

```text
Usage: os end-users [options] [command]

end-users subcommands

Options:
  -h, --help             display help for command

Commands:
  create [options]       Create a new end-user — Create a new end-user record.
                         Operator role or higher. Writes an `end_user.create`
                         audit entry.
  delete <id>            Delete an end-user — Delete an end-user record. Admin
                         role required. Writes an `end_user.delete` audit entry.
  get [options] <id>     Read a single end-user — Read one end-user by id. Any
                         authenticated operator. Pass `include_pii=true` to
                         reveal sensitive personal-ID fields — that privileged
                         path requires the **admin** role (returns `403`
                         otherwise) and writes an `end_user.pii_reveal` audit
                         entry. Returns `404` if the end-user does not exist.
  list [options]         List end-users (Connect Link customers) — List
                         end-users (the customers who authorize integrations
                         through Connect Link), with optional `tenantId`,
                         free-text `q`, and `limit`/`offset` pagination. Any
                         authenticated operator. PII is omitted from the summary
                         view.
  update [options] <id>  Patch an end-user — Partially update an end-user; only
                         the supplied fields are changed. Operator role or
                         higher. Writes an `end_user.update` audit entry.
  help [command]         display help for command
```

### `os events`

```text
Usage: os events [options] [command]

events subcommands

Options:
  -h, --help      display help for command

Commands:
  list [options]  List inbound events — Returns verified inbound platform
                  webhook events for your tenant in `seq` order (oldest first).
                  `seq` is monotonic, so paging with `after_seq` = the previous
                  page's `meta.next_cursor` pulls only new events with no
                  clock-skew gaps. Requires scope `events:read`. In test mode
                  (`/test/v1/events`) the stream is a small deterministic
                  synthetic set.
  help [command]  display help for command
```

### `os identity-providers`

```text
Usage: os identity-providers [options] [command]

identity-providers subcommands

Options:
  -h, --help             display help for command

Commands:
  create [options]       Create an identity provider — Register a new SSO
                         identity provider with its protocol-specific config.
                         Admin role required. Returns `400` if the body or
                         protocol config is invalid, and `409` if the slug is
                         already taken. Writes an `sso.provider.create` audit
                         entry.
  default-scope          default-scope subcommands
  delete <id>            Delete an identity provider — Delete an identity
                         provider, disabling SSO logins through it. Admin role
                         required. Returns `404` if no provider matches the id.
                         Writes an `sso.provider.delete` audit entry.
  get <id>               Read one identity provider — Read a single identity
                         provider's configuration by id (secrets redacted).
                         Admin role required. Returns `404` if no provider
                         matches the id.
  list                   List configured identity providers — List the
                         configured SSO identity providers (SAML/OIDC) and their
                         enabled state. Admin role required. Secrets are not
                         returned.
  metadata <id>          SAML SP metadata XML (admin-only) — Return this
                         service's SAML service-provider metadata as
                         `application/xml`, to hand to the IdP during setup
                         (advertises the ACS URL and, when configured, the SP
                         signing certificate). Admin role required. Returns
                         `404` if the provider does not exist or is not a SAML
                         provider.
  role-mappings          role-mappings subcommands
  scim-tokens            scim-tokens subcommands
  scope-rules            scope-rules subcommands
  update [options] <id>  Update an identity provider — Update an identity
                         provider's settings, config, or secret; omitted fields
                         are left unchanged. Admin role required. Returns `404`
                         if the provider is missing, `400` if the protocol
                         config is invalid, and `409` if changing the slug
                         collides with another provider — or if the stored
                         secret bundle cannot be decrypted with the current
                         STORE_SECRET, in which case nothing is written, because
                         merging into an unreadable bundle would discard every
                         secret not resent. Recover by restoring the previous
                         STORE_SECRET (or running rotate-store-secret); or
                         resend every secret with `replaceUnreadableSecret` to
                         replace the bundle outright. Writes an
                         `sso.provider.update` audit entry.
  help [command]         display help for command
```

### `os inventory`

```text
Usage: os inventory [options] [command]

inventory subcommands

Options:
  -h, --help                           display help for command

Commands:
  get-location [options] <id>          Get location — Fetches a single location.
  get-product [options] <id>           Get product — Fetches a single product by
                                       id.
  get-purchase-order [options] <id>    Get purchase order — Fetches a single
                                       purchase order.
  get-stock-adjustment [options] <id>  Get stock adjustment — Fetches a single
                                       stock adjustment.
  get-stock-level [options] <id>       Get stock level — Fetches a single stock
                                       level.
  get-stock-transfer [options] <id>    Get stock transfer — Fetches a single
                                       stock transfer.
  get-supplier [options] <id>          Get supplier — Fetches a single supplier.
  list-locations [options]             List locations — Returns warehouses /
                                       stores / virtual locations. Hierarchy via
                                       parentLocationId.
  list-products [options]              List products — Returns products / SKUs.
                                       Variants flat-with-parent-pointer via
                                       parentProductId. Schema-firewall: no
                                       images.
  list-purchase-orders [options]       List purchase orders — Returns inbound
                                       stock orders with nested line items.
  list-stock-adjustments [options]     List stock adjustments — Cycle-counts,
                                       damage write-offs, audit moves.
  list-stock-levels [options]          List stock levels — Returns quantity per
                                       Product × Location. Id is synthetic
                                       <productId>:<locationId>.
  list-stock-transfers [options]       List stock transfers — Returns movements
                                       between Locations.
  list-suppliers [options]             List suppliers — Returns vendors /
                                       sources. PII-minimal — banking details
                                       refused.
  help [command]                       display help for command
```

### `os license`

```text
Usage: os license [options] [command]

license subcommands

Options:
  -h, --help      display help for command

Commands:
  get             The deployment's license status — The license as
                  integration-server evaluates it (state, who it is issued to,
                  expiry, enabled features, limits and usage), as admin-api last
                  read it — cached for a minute, served with `stale: true` while
                  integration-server is not answering. Never contains the
                  license token. Admin role required. 503
                  `LICENSE_STATUS_UNAVAILABLE` until integration-server has
                  answered once; its message names `ADMIN_SECRET` when that is
                  why.
  help [command]  display help for command
```

### `os logistics`

```text
Usage: os logistics [options] [command]

logistics subcommands

Options:
  -h, --help                                            display help for command

Commands:
  cancel-pickup [options] <id>                          Cancel a pickup — A POST action answering 200 with the pickup in its final state, not a DELETE: FedEx and DHL cannot cancel by id alone, so the request may carry a body.
  create-label [options]                                Purchase a shipping label
  create-manifest [options]                             Create a manifest
  create-order [options]                                Create an order
  create-pickup [options]                               Schedule a pickup
  create-shipment [options]                             Create a shipment
  delete-label [options] <id>                           Void a label
  delete-order [options] <id>                           Cancel an order
  delete-shipment [options] <id>                        Cancel a shipment
  get-carrier-by-id [options] <id>                      Get a carrier
  get-label-by-id [options] <id>                        Get a label
  get-manifest-by-id [options] <id>                     Get a manifest
  get-order-by-id [options] <id>                        Get an order
  get-pickup-by-id [options] <id>                       Get a pickup
  get-shipment-by-id [options] <id>                     Get a shipment
  get-tracking-event-by-id [options] <tracking-number>  Get tracking events by tracking number
  get-warehouse-by-id [options] <id>                    Get a warehouse
  list-carriers [options]                               List carriers
  list-labels [options]                                 List labels
  list-manifests [options]                              List manifests
  list-orders [options]                                 List orders
  list-pickups [options]                                List pickups — Only platforms that expose a pickup collection (EasyPost, AfterShip) implement this; carriers that schedule by confirmation number alone answer 501.
  list-shipments [options]                              List shipments
  list-tracking-events [options]                        List tracking events
  list-warehouses [options]                             List warehouses
  quote-rates [options]                                 Get shipping rate quotes
  update-order [options] <id>                           Update an order
  help [command]                                        display help for command
```

### `os logos`

```text
Usage: os logos [options] [command]

logos subcommands

Options:
  -h, --help      display help for command

Commands:
  logo-fetch      logo-fetch subcommands
  purge           Delete every stored logo — Remove all stored platform logos.
                  The catalog falls back to monogram tiles immediately. Provided
                  because storing logos is caching under Brandfetch’s terms, so
                  an operator needs a way to undo it.
  status          Stored logo statistics — How many platform logos this
                  deployment has stored, their total size, and when the newest
                  was fetched.
  help [command]  display help for command
```

### `os notifications`

```text
Usage: os notifications [options] [command]

notifications subcommands

Options:
  -h, --help        display help for command

Commands:
  acknowledge <id>  Acknowledge a single notification — Mark a single
                    notification as acknowledged so it drops out of the
                    unacknowledged list. Operator role or higher. Returns `404`
                    if no notification matches the id. Refused (`403
                    SCOPE_RESTRICTED`) for a user restricted to specific
                    tenants: it affects every tenant.
  acknowledge-all   Acknowledge every notification — Acknowledge every
                    outstanding notification in one call, clearing the
                    unacknowledged list. Operator role or higher. Refused (`403
                    SCOPE_RESTRICTED`) for a user restricted to specific
                    tenants: it affects every tenant.
  list              List unacknowledged notifications — List notifications that
                    have not yet been acknowledged (e.g. connection errors or
                    sync alerts surfaced to operators). Any authenticated
                    operator. A tenant-restricted user gets none (notifications
                    are not tenant-scoped yet).
  unread-count      Count unread notifications — The number of unacknowledged
                    notifications, excluding `credential_expiring` (it
                    auto-heals within a poll, so counting it would keep the
                    header bell from ever reading zero). Any authenticated
                    operator. A tenant-restricted user gets none (notifications
                    are not tenant-scoped yet).
  help [command]    display help for command
```

### `os oauth-clients`

```text
Usage: os oauth-clients [options] [command]

oauth-clients subcommands

Options:
  -h, --help                        display help for command

Commands:
  create-client [options] <id>      Register a service account — Binds a subject
                                    from this issuer to a tenant and a scope
                                    set. Deleting the row later cuts off a
                                    still-valid token immediately, which is what
                                    registry authority buys over reading scopes
                                    from the token.
  create-issuer [options]           Register an identity provider — Admin only.
                                    Audience is required: without it every token
                                    the issuer ever minted for any application
                                    would be accepted here.
  create-scope-rule [options] <id>  Add a scope-mapping rule — With no rules the
                                    token's scope claim passes through verbatim.
                                    Once any rule exists, only mapped values
                                    survive — an unmapped one is dropped rather
                                    than passed through raw.
  delete-issuer <id>                Delete an identity provider — Removes the
                                    issuer along with its registered clients and
                                    scope rules. Tokens from it stop being
                                    accepted immediately.
  delete-scope-rule <id>            Delete a scope-mapping rule
  discover [options]                Read an issuer discovery document — Fetches
                                    `{issuer}/.well-known/openid-configuration`
                                    and reports the signing-key endpoint,
                                    without saving anything, so an operator can
                                    check a URL before committing to it. The
                                    document's own issuer must match what was
                                    typed — otherwise a misconfigured or hostile
                                    endpoint could point the deployment at
                                    somebody else's signing keys.
  get-issuer <id>                   Get one issuer with its clients and scope
                                    rules
  list-issuers                      List registered identity providers — Every
                                    identity provider whose OIDC bearer tokens
                                    this deployment will accept on `/v1/*`.
                                    Operator role or higher — reading which
                                    service accounts can reach the deployment
                                    does not require the ability to add one.
  list-presets                      Claim-name defaults for known identity
                                    providers — Keycloak, Auth0, Okta and Entra
                                    ID name the subject and scope claims
                                    differently. These are the defaults the
                                    admin form seeds from; the verifier itself
                                    is identical for every issuer.
  readiness                         Whether OIDC bearer auth could admit anybody
                                    — Checked before allowing
                                    `auth.dev_api_keys_enabled` to be switched
                                    off, so that change cannot lock every
                                    developer out of a running deployment. Ready
                                    means an issuer is enabled, can admit
                                    somebody, and has already verified a real
                                    token.
  revoke-client <id>                Revoke a service account — Takes effect on
                                    the next request, mid-token: the client row
                                    is consulted on every call, so a revoked
                                    account stops working before its token
                                    expires.
  update-issuer [options] <id>      Update an identity provider
  help [command]                    display help for command
```

### `os payments`

```text
Usage: os payments [options] [command]

payments subcommands

Options:
  -h, --help                               display help for command

Commands:
  cancel-charge [options] <id>             Cancel an uncaptured charge — Voids an uncaptured authorisation. Already-captured charges must be refunded instead.
  cancel-subscription [options] <id>       Cancel subscription — Cancels a subscription immediately, or at the period end when `atPeriodEnd: true`.
  capture-charge [options] <id>            Capture an uncaptured charge — Captures funds previously authorised. Omit `amount` to capture the full authorisation.
  create-charge [options]                  Create charge — Creates a new charge. Some gateways require a separate `capture` step.
  create-invoice [options]                 Create invoice — Drafts a new invoice on the gateway.
  create-payments-customer [options]       Create customer — Creates a new customer in the upstream gateway.
  create-refund [options]                  Create refund — Issues a refund against an existing charge.
  create-subscription [options]            Create subscription — Subscribes a customer to one or more prices/plans.
  delete-payments-customer [options] <id>  Delete customer — Deletes a customer. Some gateways soft-delete and retain historical charges.
  detach-payment-method [options] <id>     Detach payment method — Detaches the payment method from the customer it is currently attached to.
  get-balance-transaction [options] <id>   Get balance transaction — Fetches a single balance transaction by ID.
  get-charge [options] <id>                Get charge — Fetches a single charge by ID.
  get-dispute [options] <id>               Get dispute — Fetches a single dispute by ID.
  get-invoice [options] <id>               Get invoice — Fetches a single invoice by ID.
  get-payment-method [options] <id>        Get payment method — Fetches a single payment method by ID.
  get-payments-customer [options] <id>     Get customer — Fetches a single customer by ID.
  get-payout [options] <id>                Get payout — Fetches a single payout by ID.
  get-plan [options] <id>                  Get plan — Fetches a single plan by ID.
  get-price [options] <id>                 Get price — Fetches a single price by ID.
  get-product [options] <id>               Get product — Fetches a single product by ID.
  get-refund [options] <id>                Get refund — Fetches a single refund by ID.
  get-subscription [options] <id>          Get subscription — Fetches a single subscription by ID.
  list-balance-transactions [options]      List balance transactions — Returns the per-line ledger of charges, refunds, payouts, fees, and adjustments that make up the gateway balance.
  list-charges [options]                   List charges — Returns charge / payment intent records with their refund + dispute references.
  list-disputes [options]                  List disputes — Returns chargeback / dispute records with evidence-submission deadlines.
  list-invoice-line-items [options] <id>   List invoice line items — Returns the line items on the given invoice.
  list-invoices [options]                  List invoices — Returns invoices including subscription-generated invoices and standalone invoices.
  list-payment-methods [options]           List payment methods — Returns saved payment methods (cards, bank accounts, wallets, mandates).
  list-payments-customers [options]        List customers — Returns all gateway customer records visible to the authenticated connection.
  list-payouts [options]                   List payouts — Returns gateway-to-bank settlement records.
  list-plans [options]                     List plans — Catalog: subscription plans. Returns `501` on gateways without a Plan resource.
  list-prices [options]                    List prices — Catalog: prices for products. Returns `501` on gateways without a Price resource.
  list-products [options]                  List products — Catalog: products sold under one or more prices.
  list-refunds [options]                   List refunds — Returns refund records — partial or full — issued against charges.
  list-subscriptions [options]             List subscriptions — Returns recurring-billing records with their items and dunning state.
  pay-invoice [options] <id>               Pay invoice — Charges the invoice's default payment method.
  submit-dispute-evidence [options] <id>   Submit dispute evidence — Uploads merchant evidence to contest a dispute.
  update-invoice [options] <id>            Update invoice — Updates a draft invoice. Finalised invoices are typically immutable.
  update-payments-customer [options] <id>  Update customer — Partially updates a customer.
  update-subscription [options] <id>       Update subscription — Adjusts items, payment methods, or scheduling on an active subscription.
  void-invoice [options] <id>              Void invoice — Marks an open invoice as void. Amount due drops to zero.
  help [command]                           display help for command
```

### `os platform`

```text
Usage: os platform [options] [command]

platform subcommands

Options:
  -h, --help      display help for command

Commands:
  capabilities    capabilities subcommands
  help [command]  display help for command
```

### `os platforms`

```text
Usage: os platforms [options] [command]

platforms subcommands

Options:
  -h, --help                          display help for command

Commands:
  config                              config subcommands
  disable <vertical> <slug>           Disable a platform — Disable a platform
                                      for a vertical so it can no longer be
                                      connected. Operator role or higher.
                                      Refused (`403 SCOPE_RESTRICTED`) for a
                                      user restricted to specific tenants: it
                                      affects every tenant. Returns `404` if the
                                      vertical is unknown and `502` if
                                      integration-server cannot be reached.
                                      Writes an `adapter.disable` audit entry.
  enable [options] <vertical> <slug>  Enable a platform with operator-supplied
                                      config — Enable a platform for a vertical,
                                      optionally applying operator
                                      credentials/config; omit `config` for
                                      adapters that need none. Operator role or
                                      higher. Refused (`403 SCOPE_RESTRICTED`)
                                      for a user restricted to specific tenants:
                                      it affects every tenant. Returns `404` if
                                      the vertical is unknown and `502` if
                                      integration-server cannot be reached.
                                      Writes an `adapter.enable` audit entry.
  list [options]                      List platforms across every vertical —
                                      List every available platform (integration
                                      adapter) across all verticals, with
                                      optional `vertical` and free-text `search`
                                      filters. Any authenticated operator.
                                      Includes each platform's `authType` and
                                      enabled state.
  list-by-vertical <vertical>         List platforms in one vertical — List the
                                      platforms available within a single
                                      vertical, with operator-facing
                                      enabled/config state. Any authenticated
                                      operator. Returns `404` if the vertical is
                                      unknown and `502` if integration-server
                                      cannot be reached.
  list-status                         List operator enable/config state for
                                      every platform — List every platform
                                      across every vertical with its
                                      operator-facing enabled/config state. The
                                      all-verticals counterpart of
                                      `/api/verticals/{vertical}/platforms`;
                                      each row carries the `vertical` it belongs
                                      to. Any authenticated operator. Returns
                                      `502` if integration-server cannot be
                                      reached.
  help [command]                      display help for command
```

### `os projects`

```text
Usage: os projects [options] [command]

projects subcommands

Options:
  -h, --help                    display help for command

Commands:
  get-comment [options] <id>    Get comment — Fetches a single comment by id.
  get-project [options] <id>    Get project — Fetches a single project by id.
  get-tag [options] <id>        Get tag — Fetches a single tag by id.
  get-task [options] <id>       Get task — Fetches a single task by id.
  get-user [options] <id>       Get user — Fetches a single user by id.
  get-workspace [options] <id>  Get workspace — Fetches a single workspace by
                                id.
  list-comments [options]       List comments for a task — Returns comments
                                under the given task.
  list-projects [options]       List projects — Returns projects visible to the
                                connection.
  list-tags [options]           List tags for a workspace — Returns tags in the
                                given workspace.
  list-tasks [options]          List tasks for a project — Returns tasks under
                                the given project. Use `metadata.platformType`
                                to distinguish platform-specific levels
                                (epic/story/subtask/etc.).
  list-users [options]          List users for a workspace — Returns members of
                                the given workspace. PII-minimal (name + email).
  list-workspaces [options]     List workspaces — Returns workspaces visible to
                                the connection.
  help [command]                display help for command
```

### `os roles`

```text
Usage: os roles [options] [command]

roles subcommands

Options:
  -h, --help             display help for command

Commands:
  create [options]       Create a custom role — Create a custom role from a base
                         role and a permission set. Requires `roles:manage`.
                         Refused (`403 SCOPE_RESTRICTED`) for a user restricted
                         to specific tenants: it affects every tenant. Returns
                         `403` when the role would grant a permission or base
                         role you do not hold yourself, and `409` when the name
                         is taken (case-insensitively). Writes a `role.create`
                         audit entry.
  delete <id>            Delete a custom role — Delete a custom role. Requires
                         `roles:manage`. Refused (`403 SCOPE_RESTRICTED`) for a
                         user restricted to specific tenants: it affects every
                         tenant. Returns `404` if it does not exist, `403` if it
                         grants more than you hold, and `409` for a built-in
                         role or one still in use — assigned to a user or named
                         by an identity-provider role-mapping rule. Reassign
                         those first. Writes a `role.delete` audit entry.
  get <id>               Read one role — Read a built-in or custom role by id.
                         Requires `roles:manage` or `users:manage`. Returns
                         `404` if no role matches.
  list                   List roles — List the three built-in roles followed by
                         every custom role, each with its effective permissions.
                         Requires `roles:manage` or `users:manage`.
  permissions            permissions subcommands
  update [options] <id>  Edit a custom role — Edit a custom role; omitted fields
                         are unchanged. A base-role change is applied to every
                         holder at once. A role cannot become admin-based while
                         any holder is limited to specific tenants (`409`):
                         admins always have every tenant. Requires
                         `roles:manage`. Refused (`403 SCOPE_RESTRICTED`) for a
                         user restricted to specific tenants: it affects every
                         tenant. Returns `404` if the role does not exist, `409`
                         for a built-in role (they are immutable) or a taken
                         name, and `403` when either the role as it stands or
                         the edit would grant a permission or base role you do
                         not hold. Holders see the change within seconds;
                         role-gated routes read the current base role from the
                         database, not the sign-in token. Writes a `role.update`
                         audit entry.
  users                  users subcommands
  help [command]         display help for command
```

### `os runtime-settings`

```text
Usage: os runtime-settings [options] [command]

runtime-settings subcommands

Options:
  -h, --help              display help for command

Commands:
  list                    List runtime settings — List all runtime settings
                          (tunables that can change without a redeploy) with
                          their current values. Any authenticated operator may
                          read — so the setup wizard can show the active mode —
                          but only admins may change them.
  reset <key>             Reset a runtime setting to its seeded default — Reset
                          a runtime setting back to its seeded default value.
                          Admin role required. Returns `404` if the key is
                          unknown. Writes a `runtime_setting.reset` audit entry
                          and invalidates the downstream settings cache.
  update [options] <key>  Update a runtime setting value — Update one runtime
                          setting; the value type is validated against the
                          seeded key. Admin role required. Returns `400` if the
                          body `key` does not match the path key or the value
                          fails validation, and `409` (break-glass) if disabling
                          local login would leave no password-usable local
                          admin. Takes effect promptly via cache invalidation
                          and writes a `runtime_setting.update` audit entry.
  help [command]          display help for command
```

### `os sandbox`

```text
Usage: os sandbox [options] [command]

sandbox subcommands

Options:
  -h, --help                                     display help for command

Commands:
  auth-callback [options] <vertical> <platform>  Complete the mock OAuth ceremony — Where the mock authorize page (or an `outcome`-driven redirect) lands. Consumes the one-time `state` — a replayed, expired, or unknown state answers `400 INVALID_STATE`, and a state started for a different vertical answers `400 STATE_MISMATCH`, mirroring the live CSRF guard.
  
  On success the response is `201` with the **derived** sandbox connection id — the same id `GET /test/v1/connections` lists for that tenant and vertical. The sandbox never mints new connection ids; denied/error outcomes return an error payload and no id. (A flow started from a sandbox Connect Link 302s to the hosted done page instead of returning JSON, mirroring the live Connect Link branch.)
  auth-connect [options] <vertical> <platform>   Start the mock OAuth ceremony — The sandbox stand-in for `GET /auth/{vertical}/{platform}/connect`. The live ceremony needs an enabled adapter with real OAuth client config and a live provider; the sandbox simulates the whole dance against the synthetic `sandbox` platform with **no outbound request**.
  
  Without `outcome`, responds `302` to a hosted mock authorize page (Approve / Deny buttons) — the browser journey. With `outcome`, skips the page and drives the flow programmatically:
  
  - `granted` → 302 straight to the callback with a valid `code` + `state` → the callback answers `201` with the **derived sandbox connection id**.
  - `denied` → callback answers `400 OAUTH_ACCESS_DENIED` (no id).
  - `error` → callback answers `400 OAUTH_PROVIDER_ERROR` (no id).
  - `expired` → the callback receives a state that was never stored → `400 INVALID_STATE`, exactly what an expired live state looks like.
  
  `tenant_id` is required — the ceremony derives the connection id from it, the same UUIDv5 derivation as `GET /test/v1/connections`. Only `platform = 'sandbox'` exists; any other slug answers the live-shaped `404 ADAPTER_UNAVAILABLE`. Unauthenticated by design (browser ceremony, like the live `/auth` GETs), gated by the test-mode flag and an IP rate limit.
  connections                                    List sandbox connections — Every sandbox connection for the calling tenant — one per mounted vertical. **Start here**: every other `/test/v1/*` request needs a `connection_id`, and these are the only ids the sandbox accepts.
  
  Requires a **test-mode** dev key (`osk_test_…`). A live key on this path is `403 KEY_MODE_MISMATCH`, and the reverse is true on `/v1/*` — the two surfaces never share a credential.
  oidc-discovery                                 Sandbox test issuer: OIDC discovery — Discovery document for this deployment’s own test issuer. `issuer` is `<public base>/test/oidc` — the exact string to register on /oauth-clients (preset “OpenSteward test issuer”); the “Test” button there reads `jwks_uri` from here. Unauthenticated.
  oidc-jwks                                      Sandbox test issuer: signing keys — The RS256 public key the test issuer signs with. Generated in memory when the server starts — a restart rotates it and every earlier test token stops verifying. Unauthenticated.
  oidc-token [options]                           Sandbox test issuer: mint a token (client_credentials) — Trades a **test API key** for an OIDC bearer token, the way an identity provider trades a client secret for one. `client_id` is the subject the token is minted for; `client_secret` is an `osk_test_…` key (a live key is refused). Also accepts HTTP Basic client authentication. The tenant claim is always the key’s tenant — nothing in the request can widen it.
  
  The token carries `iss` = this deployment’s test issuer and works on `/test/v1/*` only; `/v1/*` answers `403 KEY_MODE_MISMATCH`, as it does for a test key. Whether the token is *admitted* is the registered issuer’s configuration — registry (the subject must be a registered service account), intersect, or token-decides — exactly as on `/v1/*`. Requires the test issuer to be registered on /oauth-clients first; answers `400 invalid_request` naming the URL to register otherwise. Errors use the OAuth 2.0 shape (`error`, `error_description`). IP-rate-limited (60/hour).
  reset                                          Reset the sandbox — Deletes every sandbox record belonging to the calling tenant. The next read reseeds from the same documented examples the Unified API reference shows, so a suite can reset between runs and get identical data back.
  
  Scoped to the tenant on the verified key, never to anything in the request — one tenant cannot reset another's. `/v1/*` data is untouched: the sandbox lives in its own table.
  self-serve-key [options]                       Mint a sandbox API key, self-serve (operator opt-in) — Unauthenticated, and OFF by default — answers `403 SANDBOX_SELF_SERVE_DISABLED` until the operator enables `auth.sandbox_self_serve_enabled`. When enabled, mints an `osk_test_…` key (plaintext returned once) bound to a fresh throwaway tenant: it works only on the no-egress `/test/v1/*` sandbox, expires after 7 days, and minting is IP-rate-limited (3/hour). Start with `GET /test/v1/connections` using the new key.
  help [command]                                 display help for command
```

### `os schema-status`

```text
Usage: os schema-status [options] [command]

schema-status subcommands

Options:
  -h, --help      display help for command

Commands:
  list            Per-namespace _schema_migrations rows for every reachable
                  SQLite db — Report the applied `_schema_migrations` rows for
                  each SQLite database this admin-api can reach, grouped by
                  namespace. Admin role required (diagnostic detail not exposed
                  to operator/viewer). Developer diagnostics: migrations apply
                  when each service starts and a failed one stops the boot, so a
                  running service has applied its own. A missing db file is
                  reported as an empty row set rather than an error.
  help [command]  display help for command
```

### `os scim`

```text
Usage: os scim [options] [command]

scim subcommands

Options:
  -h, --help               display help for command

Commands:
  groups                   groups subcommands
  service-provider-config  SCIM 2.0 ServiceProviderConfig discovery doc — SCIM
                           2.0 `ServiceProviderConfig` discovery document
                           advertising the supported features. Authenticated by
                           a per-provider SCIM bearer token (not the admin JWT);
                           returns `401` if the token is missing or invalid.
                           Called by IdPs during SCIM setup.
  users                    users subcommands
  help [command]           display help for command
```

### `os scope-groups`

```text
Usage: os scope-groups [options] [command]

scope-groups subcommands

Options:
  -h, --help             display help for command

Commands:
  create [options]       Create a scope group — Create a named scope group for a
                         vertical/platform. Operator role or higher. Refused
                         (`403 SCOPE_RESTRICTED`) for a user restricted to
                         specific tenants: it affects every tenant. Scopes may
                         be supplied as an array or a delimited string and are
                         normalised to a deduped array. Returns `400` if
                         `vertical`, `platform`, `name`, or a non-empty scope
                         set is missing, and `409` if a group with that name
                         already exists for the platform. Writes a
                         `scope_group.create` audit entry.
  delete <id>            Delete a scope group — Delete a scope group by id.
                         Operator role or higher. Refused (`403
                         SCOPE_RESTRICTED`) for a user restricted to specific
                         tenants: it affects every tenant. Returns `400` for a
                         non-numeric id and `404` if the group does not exist.
                         Writes a `scope_group.delete` audit entry.
  list [options]         List scope groups — List named scope groups (reusable
                         bundles of platform permissions), optionally filtered
                         by `vertical` and/or `platform`. Any authenticated
                         operator.
  update [options] <id>  Update a scope group — Update a scope group's name
                         and/or scopes; omitted fields are left unchanged.
                         Operator role or higher. Refused (`403
                         SCOPE_RESTRICTED`) for a user restricted to specific
                         tenants: it affects every tenant. Returns `400` for a
                         non-numeric id and `404` if the group does not exist.
                         Writes a `scope_group.update` audit entry.
  help [command]         display help for command
```

### `os sql-access`

```text
Usage: os sql-access [options] [command]

sql-access subcommands

Options:
  -h, --help        display help for command

Commands:
  catalog           List the SQL views and columns — Every view a SQL login can
                    read, with each column’s type in the masked and unmasked
                    schemas and its classification. Requires `data:read`. `409`
                    `POSTGRES_REQUIRED` on SQLite.
  principals        principals subcommands
  provision         Provision the SQL views — Create or update the roles,
                    schemas and views now (managed mode only; `409`
                    `MANUAL_MODE` otherwise — use the provisioning script).
                    Deployment-wide, so it needs an all-tenant scope (`403`
                    `SCOPE_TOO_NARROW`). `409` `POSTGRES_REQUIRED` on SQLite.
                    Requires `sql_access:manage`; audited as
                    `sql_access.provision`.
  provision-script  Download the provisioning script — The provisioning SQL as
                    `text/plain` (one `BEGIN … COMMIT` transaction), for manual
                    mode: run it as a role with CREATEROLE. Needs an all-tenant
                    scope. `409` `POSTGRES_REQUIRED` on SQLite. Requires
                    `sql_access:manage`.
  status            Read-only SQL access status — Backend, provisioning mode,
                    deployed catalog version, advertised read host and warnings.
                    Answers on SQLite too (`backend: sqlite`), where SQL access
                    is unavailable. Requires `sql_access:manage`.
  help [command]    display help for command
```

### `os sso`

```text
Usage: os sso [options] [command]

sso subcommands

Options:
  -h, --help                   display help for command

Commands:
  acs [options] <slug>         SAML Assertion Consumer Service (form-POST) —
                               SAML Assertion Consumer Service: the form-encoded
                               `SAMLResponse` the IdP POSTs after
                               authentication. Unauthenticated and rate-limited
                               (10/min). Validates the assertion,
                               provisions/maps the user, then `302`-redirects to
                               the UI completion route with a one-time handoff
                               code. Returns `400` if `SAMLResponse` is missing,
                               `404` for a non-SAML/unknown provider, `500` if
                               the IdP certificate is unconfigured, and `401` on
                               validation failure. Writes an `sso.login` audit
                               entry.
  callback [options] <slug>    OIDC redirect-callback endpoint — OIDC
                               redirect-callback the provider sends the browser
                               back to after authentication. Unauthenticated and
                               rate-limited (10/min). Validates the `state`,
                               provisions/maps the user, then `302`-redirects to
                               the UI completion route with a one-time handoff
                               code. Returns `400` for missing/invalid/expired
                               state, `404` for an unknown provider, and `401`
                               if authentication fails. Writes an `sso.login`
                               audit entry.
  handoff                      handoff subcommands
  ldap-login [options] <slug>  LDAP direct username/password login → JWT —
                               Authenticate a username/password directly against
                               an LDAP provider and return a JWT (no browser
                               redirect). Unauthenticated and tightly
                               rate-limited (5/min). Returns `400` if a
                               credential is missing, `404` for an
                               unknown/disabled/non-LDAP provider, `401` on
                               invalid credentials, and `403` if JIT
                               provisioning is disabled for a first-time user.
                               Writes an `sso.login` audit entry.
  login [options] <slug>       Begin an OIDC / SAML login redirect — Begin an
                               SSO login by redirecting (`302`) to the OIDC or
                               SAML provider identified by `slug`; an optional
                               `return_to` is preserved through the round-trip.
                               Unauthenticated and rate-limited (10/min).
                               Returns `404` if the provider is unknown or
                               disabled, `400` if it does not support redirect
                               login (e.g. LDAP), and `502` if initiation fails.
  login-options                Public list of enabled SSO providers +
                               local-login flag — Public, **unauthenticated**
                               endpoint that returns the enabled SSO providers
                               (no secrets) and whether the local password form
                               should be shown. Consumed by the login page to
                               render its sign-in options.
  help [command]               display help for command
```

### `os superset`

```text
Usage: os superset [options] [command]

superset subcommands

Options:
  -h, --help      display help for command

Commands:
  dashboards      dashboards subcommands
  guest-token     guest-token subcommands
  status          Embedded Superset status — Whether embedded Apache Superset
                  dashboards are configured, and the browser-facing Superset URL
                  the admin UI embeds from. Requires `dashboards:view`.
  help [command]  display help for command
```

### `os sync-jobs`

```text
Usage: os sync-jobs [options] [command]

sync-jobs subcommands

Options:
  -h, --help        display help for command

Commands:
  cancel <id>       Cancel a running sync job — Request cancellation of an
                    in-flight sync job. Operator role or higher. Returns `404`
                    if the job does not exist or is not in a cancelable state.
                    Writes a `sync_job.cancel` audit entry.
  create [options]  Enqueue a one-off sync job — Enqueue a one-off data-sync job
                    for a connection, with an optional completion
                    `callback_url`. Operator role or higher. Responds `202
                    Accepted` with the queued job. Upstream refusals keep their
                    own status: `409` when a sync is already running for the
                    connection, `404` when the connection is unknown or the
                    deployment runs in `passthrough` mode (no sync engine),
                    `502` when integration-server cannot be reached. `400` if
                    `connection_id` is missing. Writes a `sync_job.create` audit
                    entry.
  get <id>          Read one sync job — Read a single sync job by id, including
                    its status and progress. Any authenticated operator. Returns
                    `404` if the job does not exist.
  list [options]    List sync jobs — List data-sync jobs, optionally filtered by
                    `vertical`, `connection_id`, `status`, `platform`,
                    `tenant_id`, `id` and `connection_id_contains`, ordered by
                    `sort`/`dir`, and paged with `page`/`limit`. `meta.total` is
                    the number of rows matching the filter across the whole
                    deployment — a real count, so a caller can page through
                    every one of them. A tenant-restricted caller sees only jobs
                    for its granted tenants. Any authenticated operator.
  metrics           Data-store metrics (resource counts, last sync timestamps,
                    etc.) — Return aggregate data-store metrics (resource
                    counts, last-sync timestamps, and similar) for dashboards.
                    Any authenticated operator; deployment-wide, so a
                    tenant-restricted caller gets `403 SCOPE_RESTRICTED`.
                    Responds with `data: null` when integration-server is
                    unreachable so the UI can show an offline banner rather than
                    erroring.
  help [command]    display help for command
```

### `os tenants`

```text
Usage: os tenants [options] [command]

tenants subcommands

Options:
  -h, --help             display help for command

Commands:
  create [options]       Create a tenant — Register a tenant. Operator role. 403
                         `SCOPE_RESTRICTED` for a tenant-restricted caller; 403
                         `LICENSE_LIMIT_EXCEEDED` (with `limitKey: 'tenants'`,
                         `limit` and `used`) when the license's tenant limit,
                         which counts `default`, is reached; 409 when the id
                         already exists. Existing tenants are never removed.
  delete <id>            Delete a tenant (not the default; must have no domains)
  list                   List tenants
  tenant-domains         tenant-domains subcommands
  update [options] <id>  Rename a tenant
  help [command]         display help for command
```

### `os users`

```text
Usage: os users [options] [command]

users subcommands

Options:
  -h, --help             display help for command

Commands:
  avatar                 avatar subcommands
  create [options]       Create a new user account — Create a new admin-console
                         user with the given username, password, and role
                         (`admin`, `operator`, or `viewer`), and optionally an
                         email address. Admin role required. Returns `400` for a
                         missing/invalid field (including a malformed email), an
                         over-long username, or a password that fails policy,
                         and `409` if the username is already taken. Writes a
                         `user.create` audit entry, which records that an email
                         was set but never the address.
  delete <id>            Delete a user account — Delete a user account and any
                         linked SSO identities. Admin role required. Returns
                         `400` if you attempt to delete your own account, `409`
                         if removing this user would leave no break-glass admin,
                         and `404` if no user matches the id. Writes a
                         `user.delete` audit entry.
  get <id>               Get one console account — Read one console account with
                         its identity-provider links and break-glass status.
                         Admin role required. Pass `include_identity=true` to
                         reveal each link’s `externalId` — the subject this
                         account maps to in the identity provider, which is
                         typically a work email. That privileged path writes a
                         `user.pii_reveal` audit entry; without the flag the
                         field is absent, not masked.
  list                   List admin / operator / viewer accounts — List all
                         admin-console user accounts with their roles and
                         timestamps. Admin role required. Credentials are never
                         returned.
  update [options] <id>  Change a console account’s role, password and/or email
                         — Update an existing account in place, preserving the
                         user id and any break-glass pin. Admin role required.
                         Refuses changing your own role (`400`), a demotion that
                         would leave no password-usable local admin (`409`), a
                         password that fails policy (`400`), a malformed email
                         (`400`), and any change to another account that holds
                         more than you (`403`). An email set here is owned by
                         the console and SSO no longer overwrites it; `null`
                         clears it. Writes a `user.update` audit entry (neither
                         the password nor the email address is ever recorded —
                         only `passwordChanged` / `emailChanged` flags).
  help [command]         display help for command
```

### `os verticals`

```text
Usage: os verticals [options] [command]

verticals subcommands

Options:
  -h, --help      display help for command

Commands:
  list            List enabled verticals + per-vertical health — List the
                  configured verticals along with a live health check for each
                  (e.g. whether its backing service is reachable). Any
                  authenticated operator. Useful for a system-status dashboard.
  help [command]  display help for command
```

### `os webhook-subs`

```text
Usage: os webhook-subs [options] [command]

webhook-subs subcommands

Options:
  -h, --help             display help for command

Commands:
  create [options]       Create a webhook subscription (secret returned once) —
                         Create a webhook subscription that delivers events to
                         the given URL. Admin role required. The response
                         includes the signing secret **once** — it is not stored
                         in retrievable form and cannot be fetched again.
                         Returns `400` if `tenantId` or `url` is missing. Writes
                         a `webhook_sub.create` audit entry.
  delete <id>            Delete a webhook subscription — Delete a webhook
                         subscription by id, stopping further deliveries
                         immediately. Admin role required. Returns `404` if no
                         subscription matches the id. Writes a
                         `webhook_sub.delete` audit entry.
  deliveries             deliveries subcommands
  list [options]         List tenant webhook subscriptions — List webhook
                         subscriptions (outbound delivery targets for
                         `customer.*` and `connect_link.*` events), optionally
                         filtered by `tenantId` and by a `search` over the label
                         and URL. Operator role or higher. Signing secrets are
                         not included.
  pause [options] <id>   Pause or resume a webhook subscription — Pause
                         (default) or resume a subscription. A paused
                         subscription is retained but receives no deliveries.
                         Admin role required. Writes a `webhook_sub.pause` audit
                         entry.
  rotate-secret <id>     Rotate a webhook subscription signing secret — Generate
                         a NEW signing secret, replacing the old one. The
                         plaintext is returned **once**. Admin role required.
                         Writes a `webhook_sub.rotate_secret` audit entry.
  test <id>              Send a test event to a webhook subscription — Sends one
                         synthetic `opensteward.test` event to this
                         subscription, rendered in its own format, signed with
                         its own secret and carrying its custom headers — so a
                         destination can be proven to work without creating real
                         data to trigger a real event. Nothing is queued and no
                         delivery row is written. A receiver that rejects the
                         payload is reported as `ok: false` with its status code
                         rather than as an error. Works on a paused
                         subscription. Admin role required. Writes a
                         `webhook_sub.test` audit entry.
  update [options] <id>  Change a webhook subscription label, payload format or
                         headers — Change the label, and how deliveries are
                         shaped and authenticated for this subscription. The URL
                         and event list are immutable — recreate the
                         subscription to change those. Headers are replaced
                         wholesale rather than merged, so an operator can remove
                         one; an empty object clears them. Header values are
                         stored encrypted and never returned. Admin role
                         required. Writes a `webhook_sub.update` audit entry.
  help [command]         display help for command
```

### `os webhook-subscriptions`

```text
Usage: os webhook-subscriptions [options] [command]

webhook-subscriptions subcommands

Options:
  -h, --help                 display help for command

Commands:
  create [options]           Create a webhook subscription (secret returned
                             once) — Registers an HTTPS endpoint for your
                             tenant’s events without an operator round-trip.
                             Requires scope `webhooks:write`. The response
                             carries the plaintext signing secret exactly once —
                             receivers verify `X-OI-Signature` by
                             HMAC-SHA256-ing the raw body with it. The
                             subscription is pinned to the tenant on your key;
                             there is no `tenantId` field. Destination URLs are
                             SSRF-guarded (public `https` hosts only), and one
                             tenant may hold at most 20 subscriptions (`403
                             WEBHOOK_SUB_QUOTA_EXCEEDED`).
  delete <id>                Delete a webhook subscription — Requires scope
                             `webhooks:write`.
  deliveries [options] <id>  One subscription's delivery log — Recent deliveries
                             with status, attempt count and receiver response —
                             the first place to look when events stop arriving.
                             Requires scope `webhooks:read`.
  get <id>                   Get one of your webhook subscriptions —
                             Cross-tenant lookups return 404 (not 403) so ids
                             cannot be probed. Requires scope `webhooks:read`.
  list                       List your tenant's webhook subscriptions — Requires
                             scope `webhooks:read`.
  rotate-secret <id>         Rotate the signing secret (returned once) — Mints a
                             new shared secret and returns it exactly once.
                             Deliveries sign with the new secret immediately —
                             update the receiver first. Requires scope
                             `webhooks:write`.
  set-paused [options] <id>  Pause or resume deliveries — Retains the
                             subscription but stops deliveries while paused.
                             Body `{ "paused": false }` resumes; omitting the
                             body pauses. Requires scope `webhooks:write`.
  test <id>                  Send one synthetic delivery — Proves a destination
                             works without creating real data. Synchronous,
                             never queued, never retried; a receiver rejection
                             is reported as a result, not an error. Requires
                             scope `webhooks:write`.
  update [options] <id>      Update format, headers or label — `url` and
                             `events` stay immutable, as on the operator surface
                             — this exists so a header credential can be rotated
                             or a subscription renamed without losing its
                             delivery history. Requires scope `webhooks:write`.
  help [command]             display help for command
```

## Offline tools

These four subcommands wrap the filesystem-level scripts in `packages/shared/src/scripts/`. They have no OpenAPI representation because they operate directly on docker volumes / SQLite files — but they ship in the same `os` binary so a single operator runbook covers both online (admin-api) and offline operations.

### `os backup`

```text
os backup — snapshot every docker volume + .env + config files into a single tarball

Usage:
  os backup [--repo-root <path>] [--out-dir <path>]

Run from the repo root. Stop services first — the tool refuses if a writer is still attached.

Output:
  backups/opensteward-<ISO timestamp>.tar.gz

Restore with:
  os restore backups/<file>.tar.gz

Test-only flags:
  --unsafe-allow-live-db   skip the WAL guard (CI/unit tests)
  --volumes-base <path>    resolve volumes under <path>/<name> instead of via docker
```

### `os restore`

```text
os restore — restore a backup tarball produced by `os backup`

Usage:
  os restore <tarball> [--repo-root <path>] [--volumes-base <path>] [--force]

Services must be stopped first. The tool refuses if a WAL/-shm sibling exists for any
live SQLite file inside any target volume mount path (same guard pattern as `os backup`).
```

### `os doctor`

```text
os doctor — preflight an OpenSteward deployment

Usage:
  os doctor [--repo-root <path>] [--env-file <path>] [--no-network] [--json]

Checks env vars, .env/.env.example drift, docker-compose volumes/free space, 
config-drift, schema versions, encrypted-blob round-trip, and compose-override hygiene,
and reports the license integration-server will run under (never a FAIL).
Exits non-zero on any FAIL.
```

### `os rotate-secret`

```text
os rotate-secret — rotate STORE_ENCRYPTION_KEY on every SQLite db

Usage:
  os rotate-secret --old-key <hex64> --new-key <hex64> [--data-dir <path>]

Offline operation. Refuses if any of the target db files has a fresh WAL sibling.
```
