`login`

Sign in to FerrisKey using the OAuth 2.0 Device Authorization Grant (RFC 8628). On success, tokens are saved to credentials.toml and reused by subsequent commands.

ferris-ctl login [--scope <scope>] [--no-browser]

Flag	Default	Description
`--scope`	`openid profile email`	OAuth scope (space-separated)
`--no-browser`	`false`	Don’t open the verification URL in a browser

The command reads the active context, or the one you pick with --context. It also honors --url, --client-id, and --realm, each replacing the matching field of the context on its own, so it can run with no context at all when you give --url and --client-id. The realm is --realm, then the context’s realm, then master. login never reads the --client-secret flag; if the context stores a secret, the CLI sends it while polling for the token.

Before you log in

The client must allow the device authorization grant, or the server refuses the request with unauthorized_client. FerrisKey ships no such client, and the CLI cannot create one: ferris-ctl client create always turns the grant off and has no flag for it. Enable it in one of these ways:

In the admin console, create the client with OAuth 2.0 device authorization grant switched on, or open an existing client, go to its Settings tab, and switch it on under Capability config.
In a realm description file, set device_authorization_grant_enabled: true on the client and import it with an identity that is already signed in.

Getting started walks through the console steps.

The flow

Request a device code

The CLI asks FerrisKey for a device code and receives a verification URL and a user code.

Approve in the browser

The CLI prints the URL and the user code, then opens your browser on the complete verification URL when the server provides one (use --no-browser to skip that and open the URL yourself). Confirm the user code and sign in.

Poll for the token

The CLI polls FerrisKey at the interval the server gives (5 seconds when it gives none), until you approve or the code expires. An authorization_pending answer means keep waiting, and slow_down adds 5 seconds to the interval. A network error or a server error is retried after 1 second, doubling up to 30 seconds, until the code expires.

Save the session

Tokens are written to credentials.toml (mode 0600 on Unix), and the CLI prints Logged in as <name> on realm <realm>.. The name comes from the ID token (preferred_username, then email, then name) and falls back to the client ID. Other commands reuse this session automatically.

ferris-ctl login --no-browser

credentials.toml keeps one session, for one server, realm, and client. A new login replaces it. A later command uses the session only when the context points at the same server URL, sign-in realm, and client ID; see Authentication.

If you deny the request, the code expires, or the server rejects the client, the command exits with status 1 and a message naming the cause.

Cancelling

Press Ctrl-C while the CLI is waiting to abort the login. The command exits with status 130 and writes no credentials.

login prints plain text whatever -o says.

Authentication covers the rest: how credentials are resolved, when to use client credentials instead, and the file format.