CLI development and migration commands
The CLI's init, agent, dev, events, trigger, listen, migrate, import, export and scim commands, with every flag.
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, 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
Section titled “ohauthcat init”Plans, reviews and applies integration edits to an existing project and registers your sandbox callback. See the init quickstart and what init reads.
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
Section titled “ohauthcat agent install”Writes the OhAuthCat MCP server entry and integration rules for coding agents. See 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:; HTTPS, or HTTP only on localhost. |
ohauthcat dev signin
Section titled “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 when none exists.
ohauthcat events tail
Section titled “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 and the sandbox event relay.
ohauthcat trigger
Section titled “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.. Open ohauthcat listen first; samples are not recorded and reach only open relays.
ohauthcat listen
Section titled “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:
| 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
Section titled “ohauthcat migrate”Plans and manages server-side organization migrations. See Migrate for the full process.
ohauthcat migrate plan
Section titled “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:
| 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
Section titled “ohauthcat migrate run, status and rollback”Examples:
ohauthcat migrate status imp_123ohauthcat migrate run imp_123ohauthcat 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
Section titled “ohauthcat import”Previews an Auth0 or CSV/SAML import, then asks for confirmation before running it.
Example: ohauthcat import --from csv_saml --file .
| 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 and migrating from Auth0.
ohauthcat export
Section titled “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.
ohauthcat scim test
Section titled “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. 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>, 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. |