Authentication

The CLI never holds your password. It holds an API key, stored in the active profile, and every command that talks to the Flui API sends it.

That is why this page has four commands. Your own terminal needs a key that can do everything you can do. A build pipeline or an agent needs a key that can do far less, and you need to see what you have handed out and take it back.

A key only ever narrows what its issuer could already do. You cannot mint a key with more permissions than you have.

`flui auth login`

Use this on your own machine. The CLI opens a browser, runs an OIDC sign-in against the identity provider inside your installation, then uses the resulting token to mint an API key and saves it in the active profile.

flui login is the same command, shorter.

flui auth login              # opens a browser
flui auth login --headless   # prints the authorization URL instead
flui auth login --key-name my-laptop

Flag	Description
`--headless`	Print the authorization URL instead of opening a browser. Useful over SSH.
`--key-name <name>`	Name attached to the generated key, shown later in listings. Default: `cli`.
`--prompt <mode>`	How the identity provider greets you. `select_account` (the default) shows the account picker, so you confirm or switch user before a key is minted; `login` forces re-authentication; an empty value reuses the current session silently.
`--profile <name>`	Profile to save the key into. Default: the active profile.

After login, every command uses the saved key with no further prompts. The key is long-lived. To rotate it, run flui auth login again, or mint a new one with flui auth generate-api-key.

The key login mints is unscoped. It carries all of your permissions, because it is you at your own terminal. Do not hand it to anything else; for that, use the next command.

About the OAuth callback

The CLI listens for the redirect on http://localhost:8899, with fallbacks through 8900, 8901, 8902 and 8910. There is a 120-second window between opening the URL and receiving the callback.

`flui auth generate-api-key`

Use this for a key that is not you at a terminal: a build pipeline, a script or an agent.

flui auth generate-api-key --name agent \
  --scope mcp:app:read --scope mcp:obs:read

flui auth generate-api-key --name ci-pipeline \
  --expires 365 --unscoped

It refuses to guess

If you pass neither --scope nor --unscoped, the command is refused before anything else happens, before it touches the network or the profile and before you need a token. It prints:

Say what this key may do.
  --scope <mcp:...>   a limited key; repeat the flag for more than one
  --unscoped          a key carrying your full weight
Omitting both used to mean --unscoped, silently.

The widest credential the installation can issue has to be asked for explicitly, with --unscoped.

It needs a session token

This command mints a key from a browser session token, not from an existing key. Pass it with --token, or set FLUI_SESSION_TOKEN.

Flag	Default	Description
`--token <jwt>`	`FLUI_SESSION_TOKEN`	Session bearer token to mint with.
`--name <name>`	`cli`	Human-readable name for the key.
`--expires <days>`	no expiry	Expiry in whole days from now.
`--scope <scope>`	none	A scope for the key. Repeat for more than one. Cannot be combined with `--unscoped`.
`--unscoped`	`false`	Issue a key with no scope ceiling, carrying your full weight.
`--profile <name>`	active profile	Profile to save the key into.

The key is shown once, and never again

The plaintext key is written straight into the profile. The command prints the key’s id, name, expiry and scopes, followed by this line:

⚠  The plaintext key is not shown and cannot be retrieved again.

The installation stores a digest of the key, not the key itself, so there is nothing to hand back later, to you or to anyone else.

From the CLI you never see the value. It goes straight into the profile, encrypted, and every later command reads it from there. If you need the literal string, to paste into a CI secret or an agent’s configuration, mint the key in the dashboard instead: the API returns the plaintext once to whoever asked for it, and the dashboard shows it to you.

A key minted here replaces the key already in that profile. Pass --profile to write it somewhere else if you do not want to log out of the profile you are working in.

Scopes

A scope is one permission a key carries, in the form mcp:<area>:<depth>. The full set:

mcp:onboarding:read      mcp:catalog:read
mcp:app:read             mcp:app:write             mcp:app:destructive
mcp:obs:read             mcp:spec:validate
mcp:backup:read          mcp:backup:write
mcp:migration:read       mcp:migration:write       mcp:migration:destructive
mcp:mail:read
mcp:iam:read             mcp:iam:write
mcp:infra:read           mcp:infra:write           mcp:infra:destructive
mcp:platform:update

A scope you do not hold yourself is refused. The whole request fails and names the scope that caused it, instead of returning a smaller key than you asked for.

Every scoped key also gets mcp:onboarding:read, whether you ask for it or not. That is the scope that lets an agent read the “how this installation is operated” document before it does anything. An unscoped key already reaches everything, so nothing is added to it.

There is no `--groups` flag

The API and the dashboard offer a friendlier unit than raw scopes: permission groups. There are sixteen of them, on two axes, each described in one sentence written for a person, and each is granted or refused as a whole.

The CLI does not have them: from the terminal you mint by raw scope or with --unscoped.

If you are deciding what an agent should be allowed to do, read Choose what your agent may do first, then come back and name the scopes by hand, or mint the key from the dashboard instead.

`flui auth api-keys`

Lists the keys issued for the identity you are signed in as, not everyone’s keys.

flui auth api-keys
flui auth api-keys --output json

-o, --output is text (the default) or json; --profile reads the credential from another profile.

Each row shows a name, a state, the scopes the key carries, and its id. The state is one of:

active: usable now.
expired: past the expiry it was minted with.
revoked: switched off, and still listed, so a key that once existed does not vanish from the record.

A key with no scopes prints as (unscoped — the full weight of the issuer).

`flui auth revoke-api-key <id>`

Takes a key back. It stops working immediately.

flui auth revoke-api-key 6f1c2d34-...

The id is the one printed by flui auth api-keys; it is not the key itself, which the installation never keeps. You can only revoke keys you minted. An id that belongs to someone else, is already revoked or matches no key answers as not found. --profile acts with another profile’s credential.

Revoking does not remove the row. It marks the key revoked, so the listing still shows that the key existed and was turned off.

Environment variables

Variable	Effect
`FLUI_API_KEY`	Overrides the key stored in the profile for this invocation. The API URL still comes from the profile.
`FLUI_SESSION_TOKEN`	Session bearer token used by `generate-api-key`, instead of `--token`.
`FLUI_PROFILE`	Active profile selector. See Profiles and config.

The full inventory of FLUI_* variables is in Environment variables.