Getting started

This guide takes you from a fresh ferris-ctl install to listing realms and creating your first user. It assumes you have a running FerrisKey instance. If you don’t, follow the deployment getting-started first.

Prerequisites

ferris-ctl installed and on your PATH (see Install)
A reachable FerrisKey server URL, such as http://localhost:3333
A user who can administer the realms you will touch, for example the admin user of the master realm
Access to the admin console, to create the client the CLI signs in with

Create a client for the CLI

ferris-ctl login signs in with the OAuth 2.0 device authorization grant, so it needs a client that allows that grant. FerrisKey does not ship one, and ferris-ctl client create cannot make one: it always creates clients with the grant off and has no flag to change that. Create the client in the admin console, in the realm you will sign in to (master in this guide):

Open Clients and choose New client.
Set Client ID to ferris-ctl and Client authentication to Public.
Turn on Client enabled. A disabled client cannot authenticate anyone.
Under Capability config, turn on OAuth 2.0 device authorization grant.
Choose Create client.

To reuse a client you already have, open it, go to the Settings tab, and turn on the same switch under Capability config.

Add a context

A context stores how to reach a FerrisKey instance so you don’t repeat the URL and client on every command. The first context you add becomes the active one.

Create the context

ferris-ctl context add local \
  --url http://localhost:3333 \
  --client-id ferris-ctl \
  --realm master

This writes a profile named local to your config file and marks it active. Keep --realm: it is the realm the CLI signs in to, and the realm, client, and user commands fail without it.

Confirm it's active

ferris-ctl context current

Where is the config stored?

Contexts live in $XDG_CONFIG_HOME/ferriskey/config.toml, which is typically ~/.config/ferriskey/config.toml. Run ferris-ctl context path to print the exact location. The file is plain text; see Authentication before you store a secret in it.

Authenticate with the OAuth 2.0 Device Authorization Grant. The CLI prints a URL and a code, opens your browser, and waits while you approve the sign-in.

ferris-ctl login

Confirm the user code in the browser. The CLI then stores the resulting tokens in credentials.toml (mode 0600 on Unix), and later commands reuse that session. If the server answers unauthorized_client, the client does not allow the device grant yet: go back to the previous section.

Service accounts

To authenticate without a browser, add a context with --client-secret and skip login. The CLI then uses the OAuth2 client-credentials grant. There is a known incompatibility between this mode and FerrisKey 0.10.0, described in Authentication.

Run your first commands

ferris-ctl realm list

ferris-ctl user create alice \
  --email alice@example.com \
  --firstname Alice \
  --lastname Doe

ferris-ctl user get alice -o json

The -o flag selects table (the default), json, or yaml, which is handy for scripting and jq pipelines. It applies to every command except login, logout, and client secret, which always print plain text.

A new user has no password. Set one with user set-password.

Authentication

Contexts, login sessions, and how credentials are resolved.

Command reference

Every command, subcommand, and flag.

Import a realm

Bring a realm in from a file, Keycloak, Zitadel, or Supabase.