Skip to content
Dashboard
Theme
Theme

CLI development and migration commands

The CLI's init, agent, dev, events, trigger, listen, migrate, import, export and scim commands, with every flag.

View Markdown

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.

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.

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://mcp.ohauthcat.com/mcp; HTTPS, or HTTP only on localhost.

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.

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.

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.

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.

Plans and manages server-side organization migrations. See Migrate for the full process.

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

Section titled “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.

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 and migrating from Auth0.

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.

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