CLI reference

The identsphere binary handles the operational tasks that sit outside the HTTP API: migrations, data export, first-admin provisioning, and a preflight health check. Every command takes its Postgres connection from --database-url (or the DATABASE_URL env var) and its schema from --schema (or IDENTSPHERE_SCHEMA, default identsphere).

identsphere <command> [options]

Commands:
  migrate   Run database migrations (up / down / status)
  export    Export SDK-owned tables for portability or backup
  admin     Platform-admin provisioning (grant roles)
  doctor    Preflight + health check

---

identsphere migrate

Apply, roll back, or inspect schema migrations.

# Apply all pending migrations
identsphere migrate up --database-url postgres://… --schema identsphere

# Roll back the most recently applied migration
identsphere migrate down --database-url postgres://…

# Print which migrations have been applied
identsphere migrate status --database-url postgres://…

Subcommand	Effect
up	Apply all pending migrations.
down	Roll back the most recently applied migration.
status	Print applied vs. pending migrations.

Option	Env	Default
--database-url	DATABASE_URL	(required)
--schema	IDENTSPHERE_SCHEMA	identsphere

::: tip Auto-migrate Setting IDENTSPHERE_AUTO_MIGRATE=true runs migrate up on server boot, so a single-container deployment never needs a separate migration step. Migrations are idempotent. :::

---

identsphere export

Dump SDK-owned tables in a portable format — for backups or migrating off the SDK. Sensitive columns (password_hash, mfa_secret, refresh_token_hash, token_hash) are omitted by default.

identsphere export \
  --database-url postgres://… \
  --format jsonl \
  --output ./export

Option	Env	Default	Notes
--database-url	DATABASE_URL	(required)
--schema	IDENTSPHERE_SCHEMA	identsphere
--format	—	jsonl	jsonl, csv, or pgdump.
--output	—	(required)	Output directory; one file per table is written here.
--include-secrets	—	false	Include sensitive columns. Opt in explicitly.
--tables	—	all	Comma-separated allowlist of tables to export.

::: warning --include-secrets writes password hashes and MFA secrets to disk in plaintext files. Use only for a trusted, encrypted destination, and delete the output when done. :::

---

identsphere admin grant

Grant a platform-admin role to an already-registered user, by email. This is the explicit, scriptable path for bootstrapping the first owner (preferred over the IDENTSPHERE_INITIAL_OWNER_EMAIL env bootstrap).

identsphere admin grant owner@example.com --role account_owner \
  --database-url postgres://…

Argument / option	Env	Default	Notes
<email>	—	(required)	The user to promote. They must have registered first.
--role	—	account_owner	One of account_owner, admin, viewer.
--database-url	DATABASE_URL	(required)
--schema	IDENTSPHERE_SCHEMA	identsphere

The roles map to the platform RBAC hierarchy used by the admin endpoints: viewer < admin < account_owner.

---

identsphere doctor

A preflight / health check for a self-hosted install. Verifies required secrets, database connectivity, applied migrations, whether a platform owner exists, and provider-config status. Exits non-zero when a hard requirement is missing — suitable as a container HEALTHCHECK or CI gate.

identsphere doctor --database-url postgres://…

What it checks:

Check	Severity	Detail
IDENTSPHERE_JWT_SECRET set	hard	Required to sign tokens.
IDENTSPHERE_PUBLIC_BASE_URL set	hard	Required for OAuth callbacks + email links.
Database connection	hard	Exits 1 immediately if unreachable.
Migrations applied	hard	Prompts identsphere migrate up if not.
Platform owner exists	warning	Prompts IDENTSPHERE_INITIAL_OWNER_EMAIL or admin grant.
IDENTSPHERE_CONFIG_KEY set	info	Whether dashboard-managed secrets are enabled; lists enabled providers.

Option	Env	Default
--database-url	DATABASE_URL	(required)
--schema	IDENTSPHERE_SCHEMA	identsphere

See Operations for how doctor fits into a deploy.