FerrisKey CLI

ferris-ctl is the official command-line interface for FerrisKey. It talks to the FerrisKey REST API, so from your terminal you can manage realms, OAuth2 clients, and users, import realms from Keycloak or Zitadel, and script administrative tasks.

What you can do

Manage contexts

Store connection profiles (URL, client, realm) and switch between environments.

Authenticate with the OAuth 2.0 Device Authorization Grant. No client secret required.

Administer resources

Create and inspect realms, clients, and users.

Import realms

Migrate realms from a file, a live Keycloak, or a live Zitadel instance.

Install

Cargo
cargo install ferris-ctl

From source
git clone https://github.com/ferriskey/ferriskey.git
cd ferriskey/cli
cargo build --release
# binary at target/release/ferris-ctl

Pre-built binaries for Linux, macOS, and Windows are also attached to every GitHub release. Download the archive for your platform, extract ferris-ctl, and place it on your PATH.

Verify the install:

ferris-ctl --help

How it works

CLI args → ferris-ctl → resolve context + credentials → FerrisKey REST API
                              ↑
                  config.toml / credentials.toml

Every command resolves three things in order:

Where to connect: the server URL, from the active context or a --url override.
Who you are: a saved login session or client credentials, resolved automatically.
Which realm to operate on: the context default, or a --realm override.

Global flags

These flags are available on every command and override values stored in your context.

Flag	Short	Values / default	Env var	Description
`--context`		active context		Use a specific context for this command
`--output`	`-o`	`table` (default), `json`, `yaml`		Output format
`--url`		context URL	`FERRISKEY_URL`	FerrisKey server URL
`--client-id`		context client	`FERRISKEY_CLIENT_ID`	Client ID used for authentication
`--client-secret`		context secret	`FERRISKEY_CLIENT_SECRET`	Client secret used for authentication
`--realm`		context realm	`FERRISKEY_REALM`	Realm to operate on

Next steps

Getting Started

Connect to a FerrisKey instance and run your first commands.

Authentication

Understand contexts, login sessions, and credential resolution.