realm

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

ferris-ctl realm <subcommand>

get, create, and delete take the realm name as an argument. The role subcommands act on --realm, which defaults to the context’s realm. Every subcommand signs in to the context’s realm, so the context must have one. See Authentication.

realm list

List the realms the signed-in identity may access.

ferris-ctl realm list

Table columns: NAME, ID.

realm get

Show a single realm’s id and name.

ferris-ctl realm get <name>

realm create

Create a new realm and print its id and name.

ferris-ctl realm create <name>

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]

realm role

Manage the roles of a realm, or the roles scoped to one of its clients. Every subcommand takes --realm to target a realm other than the context default, and --client <client_id> to work on that client’s roles instead of the realm’s.

realm role create

ferris-ctl realm role create <name> [--description <text>] [--permission <name>]... [--realm <realm>] [--client <client_id>]

Permissions are passed by their snake_case name, for example manage_users. See the permissions reference for the full list.

ferris-ctl realm role create user-admin \
  --description "Create and update users" \
  --permission manage_users \
  --permission query_users \
  --permission view_users

ferris-ctl realm role create service-reader --client backend

realm role list

ferris-ctl realm role list [--realm <realm>] [--client <client_id>]

Lists realm roles, or the roles of --client when given. Table columns: NAME, ID.

realm role get

ferris-ctl realm role get <name> [--realm <realm>] [--client <client_id>]

Prints the id and name of the role.

realm role delete

ferris-ctl realm role delete <name> [--realm <realm>] [--client <client_id>] [--force]

realm import

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

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

Name of the created realm

When several Zitadel organizations resolve, --target-realm is ignored and the CLI prints note: --target-realm ignored (N realms resolved; keeping source names) on standard error. With exactly one organization it renames the realm as usual.

Supabase-only flags

--source-passwords and --source-preserve-ids are refused on any other source: the command stops with an error. The three --source-include-* flags are not checked, so on a source other than Supabase they are ignored without a message.

Each one is covered in From Supabase.

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

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

ferris-ctl realm import --from supabase \
  --source-url https://abcdefgh.supabase.co \
  --source-token "$SUPABASE_SERVICE_ROLE_KEY" \
  --source-passwords auth_users.csv \
  --source-preserve-ids \
  --target-realm acme

Dry run and report

--dry-run resolves the source and prints what it found without calling FerrisKey, so it needs no context and no login. It still reads the source, so the source credentials must be valid, and a --source-passwords file is read too. The table form shows counts: whether there are settings, and how many roles, clients, users, and passwords. With -o json or -o yaml you get the whole description as an array, with every password hash replaced by <redacted>.

A real import prints a report of what it created, any warnings, and the secrets of confidential clients. Import describes it.

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