`realm`

Manage realms, the isolated tenants that contain clients, users, roles, and credentials.

ferris-ctl realm <subcommand>

Read operations target the realm resolved from your context (or --realm). See Authentication.

`realm list`

List all realms.

ferris-ctl realm list

Table columns: NAME, ID.

`realm get`

Show a single realm’s details.

ferris-ctl realm get <name>

Argument	Required	Description
`<name>`	yes	Realm name

`realm create`

Create a new realm.

ferris-ctl realm create <name>

Argument	Required	Description
`<name>`	yes	Name of the realm to create

`realm delete`

Delete a realm. This prompts for confirmation, since it also removes the realm’s clients, users, and roles.

ferris-ctl realm delete <name> [--force]

Argument	Required	Description
`<name>`	yes	Name of the realm to delete
`--force` / `-f`	no	Skip the confirmation prompt

Confirmation in scripts

Without --force, the command refuses to run in a non-interactive shell rather than deleting silently. Pass --force (or -f) in CI and automation.

`realm import`

Import a realm (its settings, roles, clients, and users) from a description file, a live Keycloak, or a live Zitadel instance.

ferris-ctl realm import --from <kind> [source flags] [--target-realm <name>] [--dry-run]

Flag	Description
`--from`	Source kind: `config`, `keycloak`, or `zitadel` (optional if `--source-ref` is given)
`--source-ref`	Name of a stored source; inline flags below override its values
`--file`	Path to a realm description file (required for `--from config`); `.yaml`, `.yml`, or `.toml`
`--source-url`	Base URL of the source instance (Keycloak / Zitadel)
`--source-realm`	Source realm name (Keycloak)
`--source-org`	Source organization id (Zitadel); sent as the `x-zitadel-orgid` header
`--source-client-id`	Client id for source authentication (Keycloak client credentials)
`--source-client-secret`	Client secret for source authentication (Keycloak)
`--source-token`	Bearer token / personal access token (Zitadel PAT, or a ready Keycloak token)
`--target-realm`	Override the name of the realm created in FerrisKey (defaults to the source realm name)
`--dry-run`	Resolve and print the planned realm without calling the FerrisKey API

ferris-ctl realm import --from config --file examples/realm.yaml --dry-run -o yaml

ferris-ctl realm import --from keycloak \
  --source-url https://keycloak.example.com \
  --source-realm acme \
  --source-client-id admin-cli \
  --source-client-secret "$KC_SECRET" \
  --target-realm acme

The Import section covers each source in full, including what is and isn’t migrated.

Re-running imports is safe

Imports are idempotent: entities that already exist are skipped with a warning, so you can re-run an import after fixing the source.