Skip to content

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:

Terminal window
pnpm add -g @opensteward/cli
# or, ad-hoc:
npx @opensteward/cli --help
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

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.

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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
Usage: os platform [options] [command]
platform subcommands
Options:
-h, --help display help for command
Commands:
capabilities capabilities subcommands
help [command] display help for command
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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

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 — 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 — 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 — 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 — 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.