# CLI development and migration commands

This page documents the `init`, `agent`, `dev`, `events`, `trigger`, `listen`, `migrate`, `import`, `export` and `scim` commands from the CLI's `--help` output. Install the CLI as described in [Install the CLI and sign in](/get-started/cli/), and check `--help` in your own build before relying on a flag. Every command accepts the global `--json` flag for machine-readable output.

Each command except `scim test` uses the credentials of the selected profile or `OHAUTHCAT_API_KEY`. Sandbox commands need a sandbox environment.

## `ohauthcat init`

Plans, reviews and applies integration edits to an existing project and registers your sandbox callback. See the [init quickstart](/get-started/quickstart-init/) and [what init reads](/get-started/init-security/).

Example: `ohauthcat init --dry-run`

| Flag              | Meaning                                                                                                             |
| ----------------- | ------------------------------------------------------------------------------------------------------------------- |
| `--project`       | Existing project directory. Default `.`.                                                                            |
| `--dry-run`       | Show the exact changes without applying them.                                                                       |
| `--app-origin`    | Loopback HTTP(S) app origin; the callback is `/auth/callback`. Default `http://127.0.0.1:3000`.                     |
| `--register-only` | Review the callback registration only, without reading or writing project files.                                    |
| `--no-open`       | Print the sandbox setup and one-time test sign-in URLs instead of opening a browser.                                |
| `--sandbox`       | Without saved credentials, create a claimable test sandbox without asking first.                                    |
| `--yes`           | Apply the reviewed plan without the confirmation prompt.                                                            |
| `--undo`          | Restore every file from the recorded change set. Never contacts the API; cannot be combined with `--register-only`. |

## `ohauthcat agent install`

Writes the OhAuthCat MCP server entry and integration rules for coding agents. See [AI-assisted integration](/get-started/ai-assisted-integration/).

Example: `ohauthcat agent install --editor cursor --dry-run`

| Flag        | Meaning                                                                                          |
| ----------- | ------------------------------------------------------------------------------------------------ |
| `--project` | Existing project directory. Default `.`.                                                         |
| `--editor`  | `claude-code`, `cursor`, `windsurf` or `vscode`; repeatable. Default: detected from the project. |
| `--dry-run` | Show the diff without writing files.                                                             |
| `--yes`     | Write without the confirmation prompt.                                                           |
| `--mcp-url` | The MCP endpoint. Default `https://mcp.ohauthcat.com/mcp`; HTTPS, or HTTP only on localhost.     |

## `ohauthcat dev signin`

Starts a test sign-in through an existing configured sandbox connection.

Example: `ohauthcat dev signin --org org_123 --connection conn_123`

| Flag           | Meaning                                                              |
| -------------- | -------------------------------------------------------------------- |
| `--org`        | Organization ID in the authenticated sandbox.                        |
| `--connection` | Configured connection ID; required when more than one can be tested. |
| `--no-open`    | Print the requested test URL instead of opening a browser.           |

The CLI opens the test URL in your browser. It does not verify that the sign-in completed. `OHAUTHCAT_AUTH_BASE` must be a trusted HTTPS broker origin when you set it. The test uses a connection you have already configured; `ohauthcat init` creates the sandbox test connection to the [test IdP](/get-started/sandbox-and-test-idp/) when none exists.

## `ohauthcat events tail`

Prints prior events, then polls for new ones. Each line shows the event ID, type and creation time.

Example: `ohauthcat events tail --after evt_123`

| Flag          | Meaning                                                                  |
| ------------- | ------------------------------------------------------------------------ |
| `--after`     | Resume after this event ID, in server dispatch order.                    |
| `--interval`  | Poll interval after existing events are drained. Default `2s`.           |
| `--page-size` | Events per bounded response. Default `100`; lower it for large payloads. |

To pick up where an interrupted tail stopped, pass the last event ID you saw to `--after`. For live delivery to a local endpoint, use [`ohauthcat listen`](#ohauthcat-listen) and the [sandbox event relay](/events/dev-relay/).

## `ohauthcat trigger`

Emits a sample event of the given type in a sandbox and prints its ID. Takes no flags besides `--json`.

Example: `ohauthcat trigger organization.created`. Open `ohauthcat listen` first; samples are not recorded and reach only open relays.

## `ohauthcat listen`

Forwards sandbox relay events to a local endpoint until you stop it, reconnecting after a dropped connection.

Example: `ohauthcat listen --forward-to http://localhost:3000/webhooks/ohauthcat`

| Flag           | Meaning                                                                                                                     |
| -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `--forward-to` | Required. HTTP or HTTPS URL on `localhost` or a loopback IP that receives each event with its `OhAuthCat-Signature` header. |

## `ohauthcat migrate`

Plans and manages server-side organization migrations. See [Migrate](/migrate/) for the full process.

### `ohauthcat migrate plan`

Creates an import plan without running it.

Example, with `POLIS_API_KEY` set in the environment: `ohauthcat migrate plan --from polis --source-origin https://sso.example.com --product example-app`

| Flag                      | Meaning                                                                                    |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| `--from`                  | Source: `polis`, `workos`, `bundle`, `auth0` or `csv_saml`.                                |
| `--source-origin`         | HTTPS management API origin. Never contains a credential.                                  |
| `--product`               | Polis product to migrate. Polis only.                                                      |
| `--bundle`                | Explicit, non-ignored normalized JSON bundle file.                                         |
| `--domain`                | Canonical Auth0 tenant hostname.                                                           |
| `--file`                  | Explicit, non-ignored CSV/SAML ZIP archive.                                                |
| `--local-extract`         | Read Polis locally and upload only a normalized, secret-free bundle.                       |
| `--tenant`                | Limit local Polis extraction to exactly one tenant.                                        |
| `--organization-name`     | Explicit name for `--tenant`. Defaults to the exact tenant identifier.                     |
| `--sp-entity-id`          | Explicit legacy SAML audience for local extraction.                                        |
| `--external-origin`       | HTTPS customer-owned origin for a legacy shared ACS when the management API is plain HTTP. |
| `--allow-insecure-source` | Allow HTTP extraction only from localhost or a private or loopback IP literal.             |

Polis needs `--source-origin` and `--product`. The source API key comes from the environment only: `POLIS_API_KEY` for Polis, `WORKOS_API_KEY` for WorkOS. It is never a flag. The plan prints each legacy organization, its mapped organization, the chosen migration lever and any blockers.

### `ohauthcat migrate run`, `status` and `rollback`

Examples:

- `ohauthcat migrate status imp_123`
- `ohauthcat migrate run imp_123`
- `ohauthcat migrate rollback imp_123 org_123 --cleanup`

| Command                                 | Meaning                                                                                   |
| --------------------------------------- | ----------------------------------------------------------------------------------------- |
| `migrate status <import-id>`            | Show the import's state.                                                                  |
| `migrate run <import-id>`               | Run a planned import.                                                                     |
| `migrate rollback <import-id> <org-id>` | Roll back one organization. `--cleanup` also deactivates its active imported connections. |

## `ohauthcat import`

Previews an Auth0 or CSV/SAML import, then asks for confirmation before running it.

Example: `ohauthcat import --from csv_saml --file ./connections.zip`

| Flag       | Meaning                                     |
| ---------- | ------------------------------------------- |
| `--from`   | Source: `auth0` or `csv_saml`.              |
| `--domain` | Canonical Auth0 tenant hostname.            |
| `--file`   | Explicit, non-ignored CSV/SAML ZIP archive. |

The CLI prints the plan and asks you to type `yes`. Any other answer leaves the plan unchanged and does not run it. See [CSV and SAML imports](/migrate/csv-saml/) and [migrating from Auth0](/migrate/from-auth0/).

## `ohauthcat export`

Starts a new export, or downloads an existing one, without overwriting files.

Examples:

- `ohauthcat export --output ./export`
- `ohauthcat export exp_123 --output ./export`

| Flag                     | Meaning                                                                                    |
| ------------------------ | ------------------------------------------------------------------------------------------ |
| `[exp_id]`               | Resume or download an existing export instead of starting a new one.                       |
| `--org`                  | Export one organization instead of the whole environment.                                  |
| `--output`               | Existing, non-ignored output directory. Files are never overwritten.                       |
| `--allow-local-download` | Allow private or loopback HTTP(S) object storage. HTTPS certificate verification stays on. |

The CLI prints the export ID first; rerun with that ID if the download is interrupted. It then lists each file with its size, and the secrets you must re-enter after import. See [Export](/migrate/export/).

## `ohauthcat scim test`

Runs fifteen RFC 7643 and RFC 7644 conformance checks against your own SCIM server, the same checks as the browser [SCIM tester](/tools/scim-tester/). Use it when your server blocks requests from browsers (CORS). It talks only to the base URL you give; it never calls the OhAuthCat API and needs no sign-in.

Examples:

- `OHAUTHCAT_SCIM_TOKEN=<token> ohauthcat scim test --base-url https://api.example.com/scim/v2`
- `ohauthcat scim test --base-url https://api.example.com/scim/v2 --read-only --json`

| Flag          | Meaning                                                                                                                 |
| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `--base-url`  | Required. The SCIM base URL that `/Users` is relative to. HTTPS only; HTTP only for `localhost` and loopback addresses. |
| `--read-only` | Skip the checks that create, change and delete a test user.                                                             |
| `--timeout`   | Time limit for each request, from `1ms` to `5m`. Default `15s`.                                                         |

The base URL must not contain a user name or password, a query string, a fragment or a resource path such as `/Users` or `/ServiceProviderConfig`.

**Token.** The bearer token comes from `OHAUTHCAT_SCIM_TOKEN`, or from a hidden prompt when that is unset. There is no token flag. A pasted `Bearer ` prefix is dropped. The token is sent only in the `Authorization` header and is never printed, logged or put in a URL. Where the prompt cannot be hidden, set the environment variable.

**Test user.** Unless you pass `--read-only`, the run creates `ohauthcat-scim-test-<random>@example.invalid`, then reads, filters, duplicates, deactivates and deletes it. It is always deleted at the end, including after a lost request or Ctrl-C, together with any duplicate your server wrongly accepted. If deletion fails, the output names the user and its IDs.

**Network.** Redirects are never followed; the run stops as unreachable. Response bodies are capped at 1 MiB.

**Output.** Each check prints one line with its verdict (`pass`, `warn`, `fail` or `skip`), the RFC section and the request it sent. With `--json` the command prints one report instead:

| Field               | Meaning                                                                                    |
| ------------------- | ------------------------------------------------------------------------------------------ |
| `base_url`          | The base URL tested.                                                                       |
| `read_only`         | Whether `--read-only` was set.                                                             |
| `outcome`           | `completed`, `unreachable`, `unauthorized` (the token was rejected) or `interrupted`.      |
| `results`           | One entry per check: `id`, `title`, `spec`, `status`, `detail` and, where sent, `request`. |
| `cleanup`           | `none`, `deleted` or `failed`.                                                             |
| `test_user_name`    | The test user's `userName`, when one was created.                                          |
| `leftover_user_ids` | IDs of users that could not be deleted.                                                    |
| `failed_request`    | The request whose response could not be read.                                              |
| `summary`           | Counts of `pass`, `warn`, `fail` and `skip`.                                               |

| Exit code | Meaning                                                                                                        |
| --------- | -------------------------------------------------------------------------------------------------------------- |
| `0`       | Every check passed or warned.                                                                                  |
| `1`       | A check failed, the token was rejected, the server was unreachable, the run was interrupted or cleanup failed. |
| `2`       | Usage error, such as a missing or refused `--base-url`, an invalid `--timeout` or an empty token.              |
