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, 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:
pnpm add -g @opensteward/cli# or, ad-hoc:npx @opensteward/cli --helpTop-level usage
Section titled “Top-level usage”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 commandGenerated command groups
Section titled “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 and docs/openapi/openapi.json for the source.
os accounting
Section titled “os accounting”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 commandos api-keys
Section titled “os api-keys”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 commandos audit
Section titled “os audit”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 commandos auth
Section titled “os auth”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 commandos company-info
Section titled “os company-info”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 commandos connect-link-templates
Section titled “os connect-link-templates”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 commandos connect-sessions
Section titled “os connect-sessions”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 commandos connections
Section titled “os connections”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 commandos crm
Section titled “os crm”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 commandos customer-support
Section titled “os customer-support”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 commandos dashboard-tasks
Section titled “os dashboard-tasks”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 commandos dashboards
Section titled “os dashboards”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 commandos data
Section titled “os data”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 commandos destinations
Section titled “os destinations”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 commandos docsign
Section titled “os docsign”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 commandos ecommerce
Section titled “os ecommerce”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 commandos end-user-tokens
Section titled “os end-user-tokens”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 commandos end-users
Section titled “os end-users”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 commandos events
Section titled “os events”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 commandos identity-providers
Section titled “os identity-providers”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 commandos inventory
Section titled “os inventory”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 commandos license
Section titled “os license”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 commandos logistics
Section titled “os logistics”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 commandos logos
Section titled “os logos”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 commandos notifications
Section titled “os notifications”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 commandos oauth-clients
Section titled “os oauth-clients”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 commandos payments
Section titled “os payments”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 commandos platform
Section titled “os platform”Usage: os platform [options] [command]
platform subcommands
Options: -h, --help display help for command
Commands: capabilities capabilities subcommands help [command] display help for commandos platforms
Section titled “os platforms”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 commandos projects
Section titled “os projects”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 commandos roles
Section titled “os roles”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 commandos runtime-settings
Section titled “os runtime-settings”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 commandos sandbox
Section titled “os sandbox”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 commandos schema-status
Section titled “os schema-status”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 commandos scim
Section titled “os scim”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 commandos scope-groups
Section titled “os scope-groups”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 commandos sql-access
Section titled “os sql-access”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 commandos sso
Section titled “os sso”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 commandos superset
Section titled “os superset”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 commandos sync-jobs
Section titled “os sync-jobs”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 commandos tenants
Section titled “os tenants”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 commandos users
Section titled “os users”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 commandos verticals
Section titled “os verticals”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 commandos webhook-subs
Section titled “os webhook-subs”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 commandos webhook-subscriptions
Section titled “os webhook-subscriptions”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 commandOffline tools
Section titled “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
Section titled “os backup”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 dockeros restore
Section titled “os restore”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 anylive SQLite file inside any target volume mount path (same guard pattern as `os backup`).os doctor
Section titled “os doctor”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
Section titled “os rotate-secret”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.opensteward.dev ·Plans and free license ·Terms ·Privacy ·support@opensteward.dev
© 2026 Falco Consulting AB. Built from open-steward/opensteward@a3961d8. This site sets no cookies, runs no analytics and loads nothing from other sites, except platform logos from Brandfetch on the Platforms page.