# Command line reference

> Every command the ots command line registers, with what it writes, the flag that lets it write, its external effects and what it needs to run.

This reference lists every command the `ots` command line registers, what each one writes, the flag that lets it write, the effects that leave the host and what has to be available for it to run. This reference reflects Onetime Secret v0.26.19 (`e98a88c9`).

## Reading the tables

**Writes** names what a command changes: the datastore, the authentication database, Stripe, the message broker, or a file. **Gate** is the flag or prompt that stands between the command and that change. **External effects** covers anything that leaves the host, including mail, DNS and TLS lookups, broker traffic and Stripe calls. **Privileges** lists what the command needs to get that far.

Many commands share one write gate: a bare run is a preview that writes nothing, `--apply` is the only flag that writes, and `-y`, `--yes` and `-f` are aliases for `--apply` unless a row says otherwise. `--dry-run` restates the default, so passing it together with `--apply` is an error rather than a guess. A piped `y` is not a confirmation on these commands.

No registered command requires root. The command base classes define a privilege check, and no command at this release calls it.

Where a cell reads “not determined from source”, reading the pinned source did not settle it, and no value is guessed in its place.

## Global switches

These are parsed before the command runs, so they work with any command.

| Switch  | Effect                                                                                                                                                                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-v`, `--verbose` | Turns on verbose output.                                                                                                                                                                                      |
| `-D`, `--debug`   | Turns on debug mode, including backtraces on failure.                                                                                                       |
| `--safe-boot`       | Sets `SAFE_BOOT` so a configuration error that is fatal at boot can be bypassed to reach the console. |

## Core and process control

| Command  | Writes                                                                                                                                                                                                      | Gate | External effects                                                                                                              | Privileges                                                                                                                   | Description                                                                                                                                                                 |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ots apitoken`         | datastore; the Rodauth account row in Full mode                                                                                         | none | none                                                                                                                                                | configuration, datastore, auth database in Full mode | Generate or display Basic Auth API credentials for a customer                             |
| `ots audit`            | none                                                                                                                                                                                                            | none | none                                                                                                                                                | configuration, datastore                                                                           | Read the operator audit trail                                                                                                                   |
| `ots audit list`       | none                                                                                                                                                                                                            | none | none                                                                                                                                                | configuration, datastore                                                                           | List recent operator audit events (newest first)                                                              |
| `ots boot-test`        | none: boots and initializes the application registry                                                                        | none | none                                                                                                                                                | configuration, datastore                                                                           | Test application boot and registry initialization                                                         |
| `ots completion`       | none; prints a completion script to standard output                                                                             | none | none                                                                                                                                                | no boot: the command registry only                                                     | Generate a shell completion script (bash, zsh, fish)                                                    |
| `ots console`          | none itself; replaces the process with `irb` (an interactive session can write)           | none | none                                                                                                                                                | configuration, datastore unless `--delay-boot`                                         | Ruby irb with Onetime preloaded                                                                                                             |
| `ots help`             | none                                                                                                                                                                                                            | none | none                                                                                                                                                | no boot: files and environment only                                                  | Display help information                                                                                                                              |
| `ots install check`    | none                                                                                                                                                                                                            | none | none                                                                                                                                                | configuration, datastore                                                                           | Exit 0 if environment has been initialized, 1 otherwise                                             |
| `ots install mark`     | datastore: increments the `onetime:install:init_count` counter                                                                                              | none | none                                                                                                                                                | configuration, datastore                                                                           | Record that bin/setup --init has completed (increments counter)                   |
| `ots load-path`        | none                                                                                                                                                                                                            | none | none                                                                                                                                                | no boot: files and environment only                                                  | Lists the first 5 paths in the load path                                                                                          |
| `ots passwords`        | none                                                                                                                                                                                                            | none | none                                                                                                                                                | configuration, datastore                                                                           | Password hash statistics                                                                                                                              |
| `ots scheduler`        | scheduler run records, a PID file with `--daemonize`, and whatever the enabled jobs write | none | whatever the enabled jobs reach (mail, broker, Stripe)        | configuration, datastore                                                                           | Start Rufus job scheduler                                                                                                                             |
| `ots scheduler status` | none                                                                                                                                                                                                            | none | none                                                                                                                                                | configuration, datastore                                                                           | Show scheduled jobs: last run, next due, last error, scheduler liveness |
| `ots server`           | none itself; serves the application                                                                                                                       | none | listens on `--bind` and `--port`                                                                                                    | configuration, datastore                                                                           | Start the web server (Puma or Thin)                                                                                                     |
| `ots status`           | none                                                                                                                                                                                                            | none | probes the datastore, the Rodauth database and the broker | configuration, datastore                                                                           | Show system-wide service status                                                                                                           |
| `ots test-data`        | datastore: creates fixture records, or deletes them with `--cleanup`                                                  | none | none                                                                                                                                                | configuration, datastore                                                                           | Create or cleanup test data for a customer                                                                                  |
| `ots totp`             | none                                                                                                                                                                                                            | none | none                                                                                                                                                | configuration, datastore                                                                           | Generate or verify TOTP codes for MFA testing                                                                         |
| `ots version`          | none                                                                                                                                                                                                            | none | none                                                                                                                                                | no boot: files and environment only                                                  | Display version information                                                                                                                     |
| `ots worker`           | whatever the consumed jobs write                                                                                                                                | none | consumes broker messages; the email worker delivers mail  | configuration, datastore, broker                                                     | Start Sneakers job workers                                                                                                                          |

Aliases: `build` is an alias of `ots version`; `workers` is an alias of `ots worker`.

## Configuration

| Command | Writes | Gate | External effects | Privileges                                                                  | Description                                                                                                                                                      |
| --------------------- | ------------------ | ------------ | ---------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ots config`          | none       | none | none                                   | no boot: files and environment only | Manage and validate application configuration                                                        |
| `ots config brand`    | none       | none | none                                   | configuration, datastore                          | Diagnose brand-pack resolution (#3822 neutral-branding incident) |
| `ots config validate` | none       | none | none                                   | no boot: files and environment only | Validate config.defaults.yaml against the generated JSON Schema      |

## Customers

| Command                 | Writes                                                                                                                                                                                | Gate                                                        | External effects                                                                           | Privileges                                                                                                                   | Description                                                                                                                                                                                                   |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ots customers`                       | none                                                                                                                                                                                      | none                                                        | none                                                                                                             | configuration, datastore                                                                           | Manage customer records                                                                                                                                                                   |
| `ots customers change-email`          | datastore and auth database: every store keyed on the address                             | `--apply`; `--yes` has no effect            | mails the old and the new address unless `--no-notify` | configuration, datastore, auth database in Full mode | Change a customer’s account email across every store keyed on it                                                        |
| `ots customers create`                | datastore; the Rodauth account row in Full mode                                                                   | none                                                        | none                                                                                                             | configuration, datastore, auth database in Full mode | Create a new customer with the specified email address                                                                                  |
| `ots customers dates`                 | datastore: temporary sorted sets cached for 30 minutes                                              | none                                                        | none                                                                                                             | configuration, datastore                                                                           | Report customer record dates and age distribution                                                                                             |
| `ots customers diagnose`              | none                                                                                                                                                                                      | none                                                        | none                                                                                                             | configuration, datastore, auth database in Full mode | Diagnose login, signup, and default-workspace provisioning failures                                       |
| `ots customers doctor`                | datastore when `--repair` is given; audit only otherwise                                                            | `--repair`                                                          | none                                                                                                             | configuration, datastore                                                                           | Check customer data integrity                                                                                                                                                   |
| `ots customers finish-closures`       | datastore and auth database: deletes the records a stopped closure left | `--confirm`                                                         | none                                                                                                             | configuration, datastore, auth database in Full mode | Finish account closures that stopped before the customer record was deleted (#4830) |
| `ots customers list`                  | none                                                                                                                                                                                      | none                                                        | none                                                                                                             | configuration, datastore                                                                           | List all customers grouped by domain                                                                                                                                  |
| `ots customers normalize-emails`      | auth database: rewrites mixed-case `accounts.email` rows                                                                    | `--confirm`                                                         | none                                                                                                             | configuration, datastore, auth database in Full mode | Bring mixed-case account emails to their canonical form (#4726)                                                       |
| `ots customers plan`                  | none                                                                                                                                                                                      | none                                                        | none                                                                                                             | configuration, datastore                                                                           | Manage a customer’s plan                                                                                                                                                                  |
| `ots customers plan set`              | datastore: the customer plan id                                                                                                             | prompt, or `--yes`                                | none                                                                                                             | configuration, datastore                                                                           | Set a customer’s plan (validated against the billing catalog)                                                             |
| `ots customers prune-closed-accounts` | auth database: deletes closed account rows and their audit logs                       | `--confirm`                                                         | none                                                                                                             | configuration, datastore, auth database in Full mode | Delete closed Rodauth account rows and their audit logs (#4819)                                                         |
| `ots customers purge`                 | datastore and auth database: permanently deletes one customer                         | prompt, or `--yes`                                | none                                                                                                             | configuration, datastore, auth database in Full mode | Purge (permanently delete) a single customer account                                                                                    |
| `ots customers purge-inactive`        | datastore: deletes selected customer records                                                                      | `--purge`                                                           | none                                                                                                             | configuration, datastore                                                                           | Purge inactive customer records by last activity date                                                                                   |
| `ots customers role`                  | datastore: the customer role and role index (promote, demote)                           | prompt, or `--force`                              | none                                                                                                             | configuration, datastore                                                                           | Manage customer roles (promote, demote, list; reconcile is a subcommand)                              |
| `ots customers role reconcile`        | datastore: repairs `customer:role_index:*`                                                                                                                      | `--apply`, and `-f` is not an alias | none                                                                                                             | configuration, datastore                                                                           | Report role-index drift (dry run unless --apply)                                                                                                |
| `ots customers set-default-org`       | datastore: the customer default organization                                                                      | `--apply`                                                           | none                                                                                                             | configuration, datastore                                                                           | Set a customer’s default organization (must already be an active member)                                |
| `ots customers show`                  | none                                                                                                                                                                                      | none                                                        | none                                                                                                             | configuration, datastore                                                                           | Show detailed customer information                                                                                                                                    |
| `ots customers suspend`               | datastore: suspension state and audit event                                                                           | prompt, or `--yes`                                | not determined from source                                                 | configuration, datastore                                                                           | Suspend a customer account (trust & safety pause)                                                                                               |
| `ots customers sync-auth-accounts`    | auth database: creates account rows for existing customers                                  | `--run`                                                             | none                                                                                                             | configuration, datastore, auth database in Full mode | Synchronize customer records from Redis to Auth SQL database                                                                |
| `ots customers unsuspend`             | datastore: suspension state and audit event                                                                           | prompt, or `--yes`                                | not determined from source                                                 | configuration, datastore                                                                           | Unsuspend (reinstate) a suspended customer account                                                                                        |
| `ots customers unverify`              | datastore; the Rodauth account row in Full mode                                                                   | none                                                        | none                                                                                                             | configuration, datastore, auth database in Full mode | Mark an existing customer account as unverified                                                                                                   |
| `ots customers verify`                | datastore; the Rodauth account row in Full mode                                                                   | none                                                        | none                                                                                                             | configuration, datastore, auth database in Full mode | Mark an existing customer account as verified                                                                                                         |

Aliases: `customer` is an alias of `ots customers`.

## Memberships

| Command                | Writes                                                                                                                                                          | Gate | External effects                           | Privileges                                         | Description                                                                                                                                                                 |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ots memberships`                    | none                                                                                                                                                                | none | none                                                             | configuration, datastore | Manage organization membership records                                                                                      |
| `ots memberships add`                | datastore: the membership and its materialized entitlements       | `--apply`    | not determined from source | configuration, datastore | Add a customer to an organization (materializes entitlements)                         |
| `ots memberships doctor`             | datastore when `--repair` is given; audit only otherwise                                      | `--repair`   | none                                                             | configuration, datastore | Check organization membership data integrity                                                                      |
| `ots memberships entitlement`        | none                                                                                                                                                                | none | none                                                             | configuration, datastore | Manage a member’s operator entitlement overrides                                                            |
| `ots memberships entitlement clear`  | datastore: removes every entitlement override on the member         | `--apply`    | none                                                             | configuration, datastore | Clear ALL entitlement overrides on an org member (destructive)                        |
| `ots memberships entitlement grant`  | datastore: an entitlement override on the member                                        | `--apply`    | none                                                             | configuration, datastore | Grant an entitlement to an org member (operator override)                                       |
| `ots memberships entitlement revoke` | datastore: an entitlement override on the member                                        | `--apply`    | none                                                             | configuration, datastore | Revoke an entitlement from an org member (operator override)                              |
| `ots memberships entitlement show`   | none                                                                                                                                                                | none | none                                                             | configuration, datastore | Show a member’s baseline / override / materialized entitlements + drift |
| `ots memberships remove`             | datastore: removes the membership and clears its entitlements   | `--apply`    | none                                                             | configuration, datastore | Remove a member from an organization (clears their entitlements)                  |
| `ots memberships set-role`           | datastore: the member role, then re-materializes entitlements | `--apply`    | none                                                             | configuration, datastore | Set an organization member’s role (re-materializes entitlements)              |

Aliases: `membership` is an alias of `ots memberships`.

## Organizations

| Command                  | Writes                                                                                                                                                                    | Gate                                            | External effects                                                                                                                      | Privileges                                         | Description                                                                                                                                                                          |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ots organizations`                    | none                                                                                                                                                                          | none                                            | none                                                                                                                                                        | configuration, datastore | Manage organization records                                                                                                                              |
| `ots organizations create`             | datastore: the organization and the owner membership                                      | `--apply`                                               | not determined from source                                                                                            | configuration, datastore | Create an organization owned by an existing customer                                                             |
| `ots organizations delete`             | datastore: permanently deletes the organization                                                 | `--apply`                                               | refuses an organization with a subscription unless `--force-subscription`   | configuration, datastore | Permanently delete an organization                                                                                                           |
| `ots organizations doctor`             | datastore when `--repair` is given; audit only otherwise                                                | `--repair`                                              | none                                                                                                                                                        | configuration, datastore | Check organization data integrity                                                                                                              |
| `ots organizations entitlement`        | none                                                                                                                                                                          | none                                            | none                                                                                                                                                        | configuration, datastore | Manage an organization’s operator entitlement overrides                                                |
| `ots organizations entitlement clear`  | datastore: removes every entitlement override on the organization | `--apply`                                               | none                                                                                                                                                        | configuration, datastore | Clear ALL entitlement overrides on an organization (destructive)                         |
| `ots organizations entitlement grant`  | datastore: an entitlement override on the organization                                | `--apply`                                               | none                                                                                                                                                        | configuration, datastore | Grant an entitlement to an organization (operator override)                                        |
| `ots organizations entitlement revoke` | datastore: an entitlement override on the organization                                | `--apply`                                               | none                                                                                                                                                        | configuration, datastore | Revoke an entitlement from an organization (operator override)                               |
| `ots organizations entitlement show`   | none                                                                                                                                                                          | none                                            | none                                                                                                                                                        | configuration, datastore | Show an organization’s plan / override / materialized entitlements + drift |
| `ots organizations list`               | none                                                                                                                                                                          | none                                            | none                                                                                                                                                        | configuration, datastore | List organizations (filter by owner email or plan)                                                                   |
| `ots organizations reconcile`          | datastore: billing and entitlement state                                                                      | `--apply`                                               | reconciles against Stripe; the result reports a `stripe_error` status | configuration, datastore | Reconcile an organization’s billing + entitlement state                                                  |
| `ots organizations show`               | none                                                                                                                                                                          | none                                            | none                                                                                                                                                        | configuration, datastore | Show organization details, billing, members and domains                                                  |
| `ots organizations transfer-ownership` | datastore: owner and member roles                                                                                           | `--apply`                                               | not determined from source                                                                                            | configuration, datastore | Transfer an organization to a different existing member                                                    |
| `ots organizations unarchive`          | datastore: restores the archived organization                                                       | `--apply`, also spelled `--run` | none                                                                                                                                                        | configuration, datastore | Restore an archived organization (dry run unless --apply)                                              |

Aliases: `organization` is an alias of `ots organizations`; `org` is an alias of `ots organizations`.

## Custom domains

| Command              | Writes                                                                                                                                                                           | Gate                                                                          | External effects                                                                                         | Privileges                                         | Description                                                                                                                                                                                                                                                     |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ots domains`                      | none                                                                                                                                                                                 | none                                                                          | none                                                                                                                           | configuration, datastore | Manage custom domain records                                                                                                                                                                                                        |
| `ots domains backfill-ascii-index` | datastore: enters missing records in the ASCII name index                                  | `--apply` and a prompt, or `--yes`                          | none                                                                                                                           | configuration, datastore | Audit and backfill the custom-domain ASCII name index (stop the app before --apply)                                                     |
| `ots domains bulk-repair`          | none: the verb is retired                                                                                                                          | not applicable                                              | none                                                                                                                           | no boot                                                    | DEPRECATED: use `domains doctor --all --repair`                                                                                                                                                                                                           |
| `ots domains create`               | datastore: the domain record and its indexes                                                                     | prompt, or `--yes`                                                  | requests a certificate after creating unless `--no-cert` | configuration, datastore | Register a custom domain against an organization                                                                                                                                                  |
| `ots domains doctor`               | datastore when `--repair` is given; audit only otherwise                                                       | `--repair`                                                                            | none                                                                                                                           | configuration, datastore | Check custom domain data integrity                                                                                                                                                                                        |
| `ots domains info`                 | none                                                                                                                                                                                 | none                                                                          | not determined from source                                                               | configuration, datastore | Show detailed information about a domain                                                                                                                                                                        |
| `ots domains list`                 | none                                                                                                                                                                                 | none                                                                          | none                                                                                                                           | configuration, datastore | List all custom domains with organization info                                                                                                                                                        |
| `ots domains orphaned`             | none                                                                                                                                                                                 | none                                                                          | none                                                                                                                           | configuration, datastore | List domains without organization ownership                                                                                                                                                             |
| `ots domains probe`                | none                                                                                                                                                                                 | none                                                                          | makes an HTTPS request to the domain                                       | configuration, datastore | Make HTTPS request to verify domain serves traffic                                                                                                                                              |
| `ots domains reconcile-sender`     | the local mailer config record for the domain                                                                    | `--dry-run` previews                                                  | contacts the mail provider                                                               | configuration, datastore | Reconcile a sender domain with its local mailer config                                                                                                                                    |
| `ots domains remove`               | datastore: permanently deletes the domain record                                                       | `--apply`                                                                             | none                                                                                                                           | configuration, datastore | Remove (permanently delete) a custom domain                                                                                                                                                               |
| `ots domains repair`               | datastore: domain and organization relationships                                                     | `--apply`                                                                             | not determined from source                                                               | configuration, datastore | Fix domain relationship issues                                                                                                                                                                                                  |
| `ots domains resolve-collisions`   | datastore: keeps one record per colliding name; `--write` writes a plan file | `--apply` and a prompt, or `--yes`                          | not determined from source                                                               | configuration, datastore | Plan and apply which record to keep for each custom-domain name collision (stop the app before --apply) |
| `ots domains transfer`             | datastore: moves the domain between organizations                                                    | `--apply`                                                                             | not determined from source                                                               | configuration, datastore | Transfer a custom domain between organizations                                                                                                                                                      |
| `ots domains verify`               | datastore: verification and resolving state                                                                    | `--dry-run` previews; a bare run writes | performs DNS and TLS lookups against the domain        | configuration, datastore | Verify domain ownership and SSL status                                                                                                                                                                              |

Aliases: `domain` is an alias of `ots domains`; `ots domains add` runs `ots domains create`; `ots domains show` runs `ots domains info`; `ots domains reassign` runs `ots domains transfer`.

## Email

| Command     | Writes                                                                                                                | Gate                                                                          | External effects                                                                                                                                                                                       | Privileges                                         | Description                                                                                                                                                                                                |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ots email config`        | none                                                                                                                      | none                                                                          | none                                                                                                                                                                                                                         | configuration, datastore | Show current email delivery configuration                                                                                                              |
| `ots email preview`       | none; renders a template                                                                | none                                                                          | `--open` launches a local viewer                                                                                                                                                             | configuration, datastore | Render a template for visual inspection                                                                                                                      |
| `ots email send`          | none in the datastore; `--execute` delivers the message | `--execute`                                                                           | delivers through the configured mail backend                                                                                                           | configuration, datastore | Send a transactional email (dry-run by default)                                                                                                |
| `ots email sync-feedback` | datastore: the suppression list                                           | `--dry-run` previews; a bare run writes | pulls suppression feedback from the configured provider (SES, Lettermint, SMTP2GO) | configuration, datastore | Pull ESP suppression feedback (SES/Lettermint/SMTP2GO) into the suppression list |
| `ots email templates`     | none                                                                                                                      | none                                                                          | none                                                                                                                                                                                                                         | configuration, datastore | List available email templates                                                                                                                                             |
| `ots email test`          | publishes to the email queue with `--enqueue`                             | `--dry-run` previews; a bare run sends    | sends a test message, or enqueues it for a worker with `--enqueue`                                                                           | configuration, datastore | Send a test email to verify delivery connectivity                                                                                            |
| `ots email validate`      | none                                                                                                                      | none                                                                          | `--mx` and `--smtp` make DNS and SMTP probes                                                                                                                                           | configuration, datastore | Validate an email address using Truemail                                                                                                                   |

## Queues and dead letters

| Command   | Writes                                                                                                                                                                                                     | Gate                                                                   | External effects                                                                                                                                                                | Privileges                                                               | Description                                                                                                                                                                           |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ots queue dlq discard` | permanently drops one dead-letter message                                                                                                    | prompt, or `--force`; `--dry-run` previews | acknowledges and drops a broker message                                                                                                   | configuration, datastore, broker | Discard (permanently drop) one message from a Dead Letter Queue                                 |
| `ots queue dlq list`    | none                                                                                                                                                                                                           | none                                                                   | reads the dead-letter queues                                                                                                                                | configuration, datastore, broker | List messages in Dead Letter Queues                                                                                                             |
| `ots queue dlq purge`   | deletes messages from a dead-letter queue                                                                                                      | prompt, or `--force`                                         | purges a broker queue                                                                                                                                                     | configuration, datastore, broker | Purge (delete) messages from a Dead Letter Queue                                                                          |
| `ots queue dlq replay`  | republishes messages to their original queue, where workers process them again | none at all                                                  | publishes to the broker; replayed work runs again, including email delivery | configuration, datastore, broker | Replay messages from DLQ back to original queue; workers process them again |
| `ots queue dlq show`    | none                                                                                                                                                                                                           | none                                                                   | reads one dead-letter message                                                                                                                             | configuration, datastore, broker | Show details of a specific DLQ message                                                                                                      |
| `ots queue init`        | RabbitMQ topology: vhost, exchanges and queues                                                                                       | prompt, or `--force`; `--dry-run` previews | declares topology on the broker                                                                                                                         | configuration, datastore, broker | Initialize RabbitMQ vhost, exchanges, and queues                                                                      |
| `ots queue ping`        | publishes ping messages to the selected queues                                                                                         | `--dry-run` previews                                           | publishes to the broker                                                                                                                                               | configuration, datastore, broker | Test job queue communication by sending ping messages                                                           |
| `ots queue reset`       | deletes queues and the messages in them                                                                                                              | prompt, or `--force`; `--dry-run` previews | deletes topology on the broker                                                                                                                            | configuration, datastore, broker | Reset RabbitMQ queues (WARNING: destroys pending messages)                                          |
| `ots queue status`      | none                                                                                                                                                                                                           | none                                                                   | reads queue depths from the broker                                                                                                                  | configuration, datastore, broker | Show job system status                                                                                                                                                |

Aliases: `ots queues dlq discard` runs `ots queue dlq discard`; `ots queues dlq list` runs `ots queue dlq list`; `ots queues dlq purge` runs `ots queue dlq purge`; `ots queues dlq replay` runs `ots queue dlq replay`; `ots queues dlq show` runs `ots queue dlq show`; `ots queues init` runs `ots queue init`; `ots queues ping` runs `ots queue ping`; `ots queues reset` runs `ots queue reset`; `ots queues status` runs `ots queue status`.

## Migrations

| Command                         | Writes                                                                                                                                                | Gate                                        | External effects                                                    | Privileges                                                                         | Description                                                                                                                                                                                                   |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ots migrate`                                 | datastore: whatever the selected migration writes                         | `--run`; `--rollback ID` reverses | none                                                                                      | configuration, datastore                                 | Run Familia-based data migrations                                                                                                                                       |
| `ots migrations backfill-email-hash`          | datastore: `email_hash` on organizations                                                                        | `--run`                                             | none                                                                                      | configuration, datastore                                 | Backfill email_hash for existing organizations                                                                                                  |
| `ots migrations backfill-secret-counts`       | datastore: per-customer `secrets_active` counters                                                     | `--run`                                             | none                                                                                      | configuration, datastore                                 | Backfill per-customer live-secret counters (secrets_active)                                                           |
| `ots migrations backfill-stripe-email-hash`   | Stripe customer metadata                                                                                              | `--run`                                             | writes metadata on Stripe customers | configuration, datastore, Stripe key | Backfill email_hash metadata for Stripe customers                                                                                           |
| `ots migrations backfill-subscription-status` | datastore: subscription status and period end                                     | `--run`                                             | reads subscriptions from Stripe           | configuration, datastore, Stripe key | Backfill subscription_status and subscription_period_end from Stripe                                  |
| `ots migrations dedupe-instances`             | datastore: class-level instance collections                                       | `--run`                                             | none                                                                                      | configuration, datastore                                 | Deduplicate and normalize JSON-quoted members in class-level instance collections |
| `ots migrations dedupe-participations`        | datastore: per-instance participation sets                                          | `--run`                                             | none                                                                                      | configuration, datastore                                 | Remove JSON-quoted duplicates from per-instance participation sets                                          |
| `ots migrations dedupe-relationships`         | datastore: per-instance relationship sorted sets                          | `--run`                                             | none                                                                                      | configuration, datastore                                 | Remove JSON-quoted duplicates from per-instance relationship sorted sets                          |
| `ots migrations grant-probono-entitlements`   | datastore: entitlements on legacy identity-plan customers | `--run`                                             | none                                                                                      | configuration, datastore                                 | Grant pro-bono entitlements to legacy identity-plan customers                                                         |

## Sessions

| Command    | Writes                                                                                                                      | Gate                           | External effects | Privileges                                                                  | Description                                                               |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `ots session`            | none                                                                                                                            | none                           | none                                   | no boot: files and environment only | Session management and inspection   |
| `ots session delete`     | datastore: deletes one session                                                    | prompt, or `--force` | none                                   | configuration, datastore                          | Delete a session                                                    |
| `ots session inspect`    | none                                                                                                                            | none                           | none                                   | configuration, datastore                          | Show detailed session information   |
| `ots session list`       | none                                                                                                                            | none                           | none                                   | configuration, datastore                          | List active sessions                                        |
| `ots session revoke-all` | datastore: revokes every session for the customer | prompt, or `--force` | none                                   | configuration, datastore                          | Revoke every session for a customer |
| `ots session search`     | none                                                                                                                            | none                           | none                                   | configuration, datastore                          | Find sessions for a user                                |

Aliases: `sessions` is an alias of `ots session`.

## Banner

| Command | Writes                                                                       | Gate                                                        | External effects | Privileges                                         | Description                                                                                                                    |
| --------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ots banner`          | none                                                                             | none                                                        | none                                   | configuration, datastore | Manage the global broadcast banner                                                       |
| `ots banner clear`    | datastore: deletes the `global_banner` key | `--apply`                                                           | none                                   | configuration, datastore | Clear the global broadcast banner (dry-run by default) |
| `ots banner set`      | datastore: the `global_banner` key                       | `--apply`, and `-f` is not an alias | none                                   | configuration, datastore | Set the global broadcast banner (dry-run by default)       |
| `ots banner show`     | none                                                                             | none                                                        | none                                   | configuration, datastore | Show the current global broadcast banner                                       |

## Housekeeping

| Command   | Writes                                                                                                                        | Gate | External effects | Privileges                                         | Description                                                                                                   |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `ots housekeeping`      | none                                                                                                                              | none | none                                   | configuration, datastore | Run Familia model housekeeping chores                             |
| `ots housekeeping list` | none                                                                                                                              | none | none                                   | configuration, datastore | List models with registered housekeeping chores |
| `ots housekeeping run`  | datastore: whatever the registered chores persist | none | none                                   | configuration, datastore | Run housekeeping chores for a model                                     |

## Rate limits

| Command | Writes                                                                                                                                    | Gate | External effects | Privileges                                         | Description                                                                                                                                              |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ots ratelimit`       | none                                                                                                                                          | none | none                                   | configuration, datastore | List known rate limiters and their subject types                                             |
| `ots ratelimit keys`  | none; prints the datastore commands an operator can run | none | none                                   | configuration, datastore | Emit valkey-cli commands to inspect and clear a rate-limit entry |

## Notifications

| Command          | Writes | Gate | External effects | Privileges                                         | Description                                                                                                                                                   |
| ------------------------------ | ------------------ | ------------ | ---------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ots notifications deliveries` | none       | none | none                                   | configuration, datastore | List delivery events for outbound email and webhook notifications |

## Single sign-on

| Command     | Writes                                       | Gate | External effects                           | Privileges                                                                                                                   | Description                                                                                                                                                         |
| ------------------------- | -------------------------------------------------------- | ------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ots sso`                 | none                                             | none | none                                                             | configuration, datastore                                                                           | Maintain SSO identity records (issuer backfill)                                                       |
| `ots sso backfill-issuer` | SSO identity records | `--confirm`  | not determined from source | configuration, datastore, auth database in Full mode | Backfill the authoritative issuer onto legacy tenant SSO identities |

## Diagnostics

| Command                    | Writes | Gate | External effects                                                                                 | Privileges                                                                  | Description                                                                                                                            |
| ---------------------------------------- | ------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ots diagnostics sentry check-dsn`       | none       | none | probes the Sentry host named in the DSN                        | no boot: files and environment only | Parse and probe a Sentry DSN for validity and connectivity |
| `ots diagnostics sentry doctor`          | none       | none | `--send-event` captures a test exception through the SDK | no boot: files and environment only | Report Sentry configuration and connectivity health              |
| `ots diagnostics sentry send-test-event` | none       | none | sends an event to one or both Sentry projects        | no boot: files and environment only | Send a test event to Sentry to verify end-to-end delivery    |

## Billing

| Command                     | Writes                                                                                                                                                                                                                                 | Gate                                                                                        | External effects                                                                                                                                                                | Privileges                                                                         | Description                                                                                                                                                                                        |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ots billing`                             | none                                                                                                                                                                                                                                       | none                                                                                        | none                                                                                                                                                                                                  | configuration, datastore                                 | Manage billing, products, and prices                                                                                                                     |
| `ots billing catalog`                     | none                                                                                                                                                                                                                                       | none                                                                                        | none                                                                                                                                                                                                  | configuration, datastore                                 | Manage the billing plan catalog                                                                                                                                    |
| `ots billing catalog drift`               | none                                                                                                                                                                                                                                       | none                                                                                        | none                                                                                                                                                                                                  | configuration, datastore                                 | Compare the configured plan catalog against the live Stripe cache                                        |
| `ots billing catalog generate-docs`       | a Markdown file at `--output`                                                                                                                                                                                        | none                                                                                        | none                                                                                                                                                                                                  | configuration, datastore                                 | Generate plan-definitions.md from billing.yaml                                                                                     |
| `ots billing catalog pull`                | datastore: the plan cache                                                                                                                                                                              | none                                                                                        | reads products and prices from Stripe                                                                                                         | configuration, datastore, Stripe key | Pull products and prices from Stripe to Redis cache                                                                                |
| `ots billing catalog push`                | Stripe products and prices                                                                                                                                                                           | prompt, or `--force`; `--dry-run` previews                      | creates and updates Stripe products and prices                                                                                | configuration, datastore, Stripe key | Push billing catalog to Stripe (create/update products)                                                                |
| `ots billing catalog sync`                | Stripe products and prices, then datastore: the plan cache and materialized plans                      | prompt, or `--force`; `--dry-run` previews                      | pushes to and pulls from Stripe                                                                                                                           | configuration, datastore, Stripe key | Full catalog sync: push to Stripe, pull to cache, materialize plans                                    |
| `ots billing catalog validate`            | none                                                                                                                                                                                                                                       | none                                                                                        | none                                                                                                                                                                                                  | configuration, datastore                                 | Validate plan catalog YAML structure (schema validation only)                                                |
| `ots billing checkout-links`              | none                                                                                                                                                                                                                                       | none                                                                                        | none                                                                                                                                                                                                  | configuration, datastore                                 | Manage support-issued Stripe Checkout links                                                                                                |
| `ots billing checkout-links create`       | a Stripe Checkout session                                                                                                                                                                              | `--dry-run` resolves without calling Stripe | creates a Checkout session at Stripe                                                                                                            | configuration, datastore, Stripe key | Create a Stripe Checkout link for a specific customer                                                                          |
| `ots billing config`                      | none                                                                                                                                                                                                                                       | none                                                                                        | none                                                                                                                                                                                                  | configuration, datastore                                 | Display Stripe configuration information (securely masked)                                                     |
| `ots billing coupon`                      | none                                                                                                                                                                                                                                       | none                                                                                        | none                                                                                                                                                                                                  | configuration, datastore                                 | Inspect or validate a single coupon / promotion code                                                                             |
| `ots billing coupon validate`             | none                                                                                                                                                                                                                                       | none                                                                                        | reads the coupon from Stripe                                                                                                                                  | configuration, datastore, Stripe key | Check whether a coupon or promotion code is currently valid                                                          |
| `ots billing coupons`                     | none                                                                                                                                                                                                                                       | none                                                                                        | reads coupons from Stripe                                                                                                                                         | configuration, datastore, Stripe key | List Stripe coupons and their promotion codes                                                                                              |
| `ots billing customers`                   | none                                                                                                                                                                                                                                       | none                                                                                        | reads customers from Stripe                                                                                                                                   | configuration, datastore, Stripe key | List Stripe customers                                                                                                                                                              |
| `ots billing customers create`            | a Stripe customer                                                                                                                                                                                                    | prompt in `--interactive` mode, otherwise none  | creates a Stripe customer                                                                                                                                         | configuration, datastore, Stripe key | Create a new Stripe customer                                                                                                                                             |
| `ots billing customers delete`            | deletes a Stripe customer                                                                                                                                                                              | prompt, or `--yes`                                                                | deletes the customer at Stripe                                                                                                                            | configuration, datastore, Stripe key | Delete a Stripe customer                                                                                                                                                       |
| `ots billing customers show`              | none                                                                                                                                                                                                                                       | none                                                                                        | reads the customer from Stripe                                                                                                                            | configuration, datastore, Stripe key | Show detailed customer information                                                                                                                         |
| `ots billing diagnose`                    | none                                                                                                                                                                                                                                       | none                                                                                        | none                                                                                                                                                                                                  | configuration, datastore                                 | Diagnose entitlement resolution for a user or organization                                                         |
| `ots billing events`                      | none                                                                                                                                                                                                                                       | none                                                                                        | reads events from Stripe                                                                                                                                            | configuration, datastore, Stripe key | View recent Stripe events                                                                                                                                                    |
| `ots billing invoices`                    | none                                                                                                                                                                                                                                       | none                                                                                        | reads invoices from Stripe                                                                                                                                      | configuration, datastore, Stripe key | List Stripe invoices                                                                                                                                                                 |
| `ots billing orgs`                        | none                                                                                                                                                                                                                                       | none                                                                                        | none                                                                                                                                                                                                  | configuration, datastore                                 | Inspect organization billing state                                                                                                                         |
| `ots billing orgs stripe`                 | none                                                                                                                                                                                                                                       | none                                                                                        | none                                                                                                                                                                                                  | configuration, datastore                                 | List organizations that have a Stripe customer id (index-backed)                                         |
| `ots billing orgs validate`               | none                                                                                                                                                                                                                                       | none                                                                                        | none                                                                                                                                                                                                  | configuration, datastore                                 | Detect orgs whose planid doesn’t resolve in cache or config                                                          |
| `ots billing payment-methods`             | none                                                                                                                                                                                                                                       | none                                                                                        | none                                                                                                                                                                                                  | configuration, datastore                                 | Manage customer payment methods                                                                                                                                  |
| `ots billing payment-methods set-default` | the default payment method on a Stripe customer                                                                                                                    | prompt                                                                                  | updates the customer at Stripe                                                                                                                            | configuration, datastore, Stripe key | Set default payment method                                                                                                                                                 |
| `ots billing plans`                       | datastore: refreshes the plan cache with `--refresh`                                                                                                                         | `--refresh`                                                                                         | `--refresh` reads from Stripe                                                                                                                                                   | configuration, datastore                                 | List product plan cache from Redis                                                                                                                             |
| `ots billing plans materialize`           | datastore: materialized entitlements on organizations and, with `--include-memberships`, their members | `--run`                                                                                             | none                                                                                                                                                                                                  | configuration, datastore                                 | Materialize entitlements on organizations from plan definitions                                        |
| `ots billing plans validate`              | none                                                                                                                                                                                                                                       | none                                                                                        | reads products and prices from Stripe                                                                                                         | configuration, datastore, Stripe key | Validate plan production readiness (products + prices)                                                                   |
| `ots billing prices`                      | none                                                                                                                                                                                                                                       | none                                                                                        | reads prices from Stripe                                                                                                                                            | configuration, datastore, Stripe key | List all Stripe prices                                                                                                                                                             |
| `ots billing prices create`               | a Stripe price                                                                                                                                                                                                             | prompt                                                                                  | creates a price at Stripe                                                                                                                                           | configuration, datastore, Stripe key | Create a new Stripe price                                                                                                                                                      |
| `ots billing prices generate`             | none; prints the price-creation commands                                                                                                                                   | none                                                                                        | looks products up at Stripe unless `--no-lookup`                                                                                                    | configuration, datastore, Stripe key | Generate price creation commands from billing.yaml                                                                             |
| `ots billing prices validate`             | none                                                                                                                                                                                                                                       | none                                                                                        | reads prices from Stripe                                                                                                                                            | configuration, datastore, Stripe key | Validate Stripe prices (Stripe API only)                                                                                                           |
| `ots billing products`                    | none                                                                                                                                                                                                                                       | none                                                                                        | reads products from Stripe                                                                                                                                      | configuration, datastore, Stripe key | List all Stripe products and manage product operations                                                                     |
| `ots billing products create`             | a Stripe product                                                                                                                                                                                                       | prompt, or `--yes`                                                                | creates or updates a product at Stripe                                                                                                        | configuration, datastore, Stripe key | Create a new Stripe product                                                                                                                                                |
| `ots billing products events`             | none                                                                                                                                                                                                                                       | none                                                                                        | reads events from Stripe                                                                                                                                            | configuration, datastore, Stripe key | Show product-related Stripe events                                                                                                                         |
| `ots billing products show`               | none                                                                                                                                                                                                                                       | none                                                                                        | reads the product from Stripe                                                                                                                               | configuration, datastore, Stripe key | Show detailed product information                                                                                                                            |
| `ots billing products update`             | Stripe product metadata                                                                                                                                                                                  | prompt                                                                                  | updates the product at Stripe                                                                                                                               | configuration, datastore, Stripe key | Update Stripe product metadata (delete via: stripe products delete PRODUCT_ID) |
| `ots billing products validate`           | none                                                                                                                                                                                                                                       | none                                                                                        | reads products from Stripe                                                                                                                                      | configuration, datastore, Stripe key | Validate Stripe product metadata completeness                                                                                          |
| `ots billing refunds`                     | none                                                                                                                                                                                                                                       | none                                                                                        | reads refunds from Stripe                                                                                                                                         | configuration, datastore, Stripe key | List Stripe refunds                                                                                                                                                                    |
| `ots billing refunds create`              | a Stripe refund                                                                                                                                                                                                          | prompt, or `--yes`                                                                | refunds a charge at Stripe                                                                                                                                        | configuration, datastore, Stripe key | Create a refund for a charge                                                                                                                                               |
| `ots billing sigma`                       | none                                                                                                                                                                                                                                       | none                                                                                        | none                                                                                                                                                                                                  | configuration, datastore                                 | Stripe Sigma analytics commands                                                                                                                                  |
| `ots billing sigma queries`               | none                                                                                                                                                                                                                                       | none                                                                                        | reads Sigma queries from Stripe                                                                                                                         | configuration, datastore, Stripe key | List Stripe Sigma queries                                                                                                                                                    |
| `ots billing sigma run`                   | a file at `--output` when given                                                                                                                                                                                    | none                                                                                        | retrieves a Sigma scheduled query run from Stripe                                                                         | configuration, datastore, Stripe key | Execute a Sigma query                                                                                                                                                                |
| `ots billing subscriptions`               | none                                                                                                                                                                                                                                       | none                                                                                        | reads subscriptions from Stripe                                                                                                                       | configuration, datastore, Stripe key | List Stripe subscriptions                                                                                                                                                  |
| `ots billing subscriptions cancel`        | cancels a Stripe subscription                                                                                                                                                                  | prompt, or `--yes`; `--dry-run` previews                        | cancels at Stripe, immediately with `--immediately`                                                                                             | configuration, datastore, Stripe key | Cancel a subscription                                                                                                                                                              |
| `ots billing subscriptions pause`         | pauses a Stripe subscription                                                                                                                                                                     | prompt, or `--yes`                                                                | pauses collection at Stripe                                                                                                                                   | configuration, datastore, Stripe key | Pause a subscription                                                                                                                                                                 |
| `ots billing subscriptions resume`        | resumes a Stripe subscription                                                                                                                                                                  | prompt, or `--yes`                                                                | resumes collection at Stripe                                                                                                                                | configuration, datastore, Stripe key | Resume a paused subscription                                                                                                                                           |
| `ots billing subscriptions update`        | the price or quantity on a Stripe subscription                                                                                                                       | prompt                                                                                  | updates the subscription at Stripe                                                                                                                | configuration, datastore, Stripe key | Update subscription price or quantity                                                                                                                  |
| `ots billing sync-billing-email`          | datastore: organization billing email, and contact email with `--update-contact-email`                                                 | `--apply`                                                                                           | reads customers from Stripe                                                                                                                                   | configuration, datastore, Stripe key | Sync organization billing emails from Stripe customer records                                                |
| `ots billing sync-org`                    | datastore: organization subscription state                                                                                                                           | `--dry-run` previews                                                                | reads subscriptions from Stripe                                                                                                                       | configuration, datastore, Stripe key | Sync organization subscription state from Stripe                                                                                   |
| `ots billing test`                        | none                                                                                                                                                                                                                                       | none                                                                                        | none                                                                                                                                                                                                  | configuration, datastore                                 | Testing utilities for billing integration                                                                                                      |
| `ots billing test create-customer`        | a Stripe test customer, with a test card when `--with-card`                                                                                                              | none                                                                                        | creates a customer and attaches a payment method at Stripe                                                  | configuration, datastore, Stripe key | Create test customer with payment method (test mode only)                                                              |
| `ots billing test trigger-webhook`        | none directly; the emitted event is processed by the application                                                                     | none                                                                                        | shells out to the Stripe CLI, which emits a test event                                                                | the Stripe CLI on `PATH`                                                   | Trigger a test webhook event (requires Stripe CLI)                                                                                 |
| `ots billing update-stripe-metadata`      | Stripe customer metadata for organizations in this region                                                                                      | `--apply`                                                                                           | updates customers at Stripe                                                                                                                                   | configuration, datastore, Stripe key | Read or update a Stripe customer metadata key for orgs in this region                                  |
| `ots billing validate`                    | none                                                                                                                                                                                                                                       | none                                                                                        | runs the catalog, product, price and plan validations as separate processes | configuration, datastore, Stripe key | Run all billing validations (convenience command)                                                                                |
| `ots billing webhooks`                    | datastore: rewrites stored events when `--migrate` is given; read-only otherwise                                           | `--migrate`                                                                                         | none                                                                                                                                                                                                  | configuration, datastore                                 | Inspect webhook event processing status                                                                                                            |
| `ots billing webhooks replay`             | reprocesses stored webhook events                                                                                                                                                      | prompt, or `--force`/`--yes`; `--dry-run` previews            | reprocessing contacts Stripe and can send notifications unless `--skip-notifications`           | configuration, datastore, Stripe key | Replay stored webhook events with filtering                                                                                                  |

## Shell entry points

The scripts operators run directly. Each one either dispatches to `ots` or to a tool package under `tools/`.

| Script        | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bin/ots`                 | The Ruby entry point for every `ots` command. Parses the global `-v`/`--verbose`, `-D`/`--debug` and `--safe-boot` switches, then dispatches to the command registry.                                                                                                                                                                                              |
| `bin/install`             | Operator front door for installing from a checkout. Wraps `bin/setup`; `--reconcile` re-derives child keys and re-applies broker policies. Idempotent, and it never regenerates a live `SECRET`.                                                                                         |
| `bin/setup`               | Prepares a checkout. A shim that runs the lanes in `tools/setup/setup.sh`; `bin/setup --help` lists them.                                                                                                                                                                                                                                                                                                                                                      |
| `bin/doctor`              | Checks the environment against the manifest and runs live probes. Wraps `bin/setup --doctor`; `--operator` restricts the checks to production concerns and `--operator --bundle` writes a sanitized diagnostic archive of variable names only. |
| `bin/scheduler`           | Starts the scheduler daemon. Sources `.env` when present, then runs `bin/ots scheduler`.                                                                                                                                                                                                                                                                                                                                                                     |
| `bin/worker`              | Starts the job workers. Sources `.env` when present, then runs `bin/ots worker`.                                                                                                                                                                                                                                                                                                                                                                                       |
| `bin/console`             | Opens the application console through `bin/ots console`. Takes the environment from the shell rather than sourcing `.env`.                                                                                                                                                                                                                                                                     |
| `bin/envref`              | Entry point for the configuration-annotation tooling. Starts `tools/envref` through its locked runtime; `envref --help` lists the subcommands.                                                                                                                                                                                                                     |
| `bin/irb`                 | Loads models, applications and test helpers into `irb` without booting. Selects the applications by `AUTHENTICATION_MODE`.                                                                                                                                                                                                                                                                         |
| `bin/dev`                 | Development process runner for the Procfile services (contributor tooling).                                                                                                                                                                                                                                                                                                                                                      |
| `bin/backend`             | Starts only the backend service through the development process runner (contributor tooling).                                                                                                                                                                                                                                                                                                      |
| `bin/frontend`            | Starts only the frontend service through the development process runner (contributor tooling).                                                                                                                                                                                                                                                                                                   |
| `bin/host-seam`           | Runs the proxy-simulation matrix for the public-host seam (contributor tooling).                                                                                                                                                                                                                                                                                                                                         |
| `bin/stripe-dev-webhook`  | Forwards Stripe webhook events to a local development server through the Stripe CLI (contributor tooling).                                                                                                                                                                                                                                                                     |
| `bin/testsuite`           | Runs the test suite through `tools/testsuite` (contributor tooling).                                                                                                                                                                                                                                                                                                                                                                                                           |
| `bin/testsuite-installer` | Runs the installer test suite through `tools/testsuite-installer` (contributor tooling).                                                                                                                                                                                                                                                                                                                                                                     |
| `bin/visual`              | Runs the visual regression suite, seeding fixtures and booting a server (contributor tooling).                                                                                                                                                                                                                                                                                                     |

## See also

* [Verify your install](/en/install/verify)
* [Configuration Reference](/en/reference/configuration-files-and-precedence)
* [Upgrade Guides](/en/self-hosting/upgrade-guides)