Ferriskey
clikubernetesdiscoverlearnmodules

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 Overview → Install)
  • A reachable FerrisKey server URL (e.g. http://localhost:3333)
  • A client ID to authenticate with

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.

Confirm it's active 

ferris-ctl context current

Where is the config stored?

Contexts live in $XDG_CONFIG_HOME/ferriskey/config.toml (typically ~/.config/ferriskey/config.toml). Run ferris-ctl context path to print the exact location.

Sign in

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

ferris-ctl login

Follow the prompt: confirm the user code in the browser, and the CLI stores the resulting tokens in credentials.toml (mode 0600 on Unix). Subsequent commands reuse that session automatically.

Service accounts

If you’d rather authenticate non-interactively, add a context with a --client-secret instead. The CLI then uses the OAuth2 client-credentials grant and you can skip login. See 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 switches output between table (default), json, and yaml for any command, which is handy for scripting and jq pipelines.

What’s next?

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, or Zitadel.