Authenticate Figena CLI

Overview

Figena CLI supports two kinds of credentials, stored separately for each profile:

• A browser sign-in for work you do yourself. It’s required for agents, runs, specs, knowledge bases, the console, and OpenPort approvals.
• An Agent Key for automations such as CI jobs. It’s required for OpenPort data commands: manifest, workspaces, transactions, preflight, action, and draft get.

Sign in through the browser

1. 1Run figena auth login. The profile needs an API address, from figena config init or the --api-base-url option.
2. 2The CLI opens the approval page in your default browser and prints the address and a code.
3. 3Check that the code on the page matches the one in your terminal, then approve the request.
4. 4The CLI checks for approval every few seconds and prints “Logged in as” followed by your email address when it succeeds.

Open this URL to sign in to Figena CLI:<approval URL>Code: <code>Waiting for approval...

A sign-in request is valid for the time set by the server, usually about 10 minutes. If the request is declined, the CLI stops with “CLI authorization was denied”; if it expires or was already used, with “CLI authorization expired or was already used”; and if nobody approves it in time, with “CLI authorization timed out”. Run figena auth login again to start over.

Use an Agent Key for automations

Automations shouldn’t rely on a person’s browser session. Use an Agent Key issued for your workspace by its administrator, in one of two ways:

figena auth login --agent-key <agent-key>

Saving the key stores it in the current profile and prints “Stored Agent Key for profile” followed by the profile name. With the environment variable, the key is used without being written to disk, which suits CI systems that inject secrets at run time. When both are available, the environment variable wins.

Check, refresh, and sign out

• figena auth status shows the profile, whether it is authenticated, the credential type (user or service), the signed-in user, and which sources are available.
• figena auth refresh exchanges the stored refresh token for new credentials. It works only for browser sign-ins.
• figena auth logout removes the credentials stored for the profile. It doesn’t unset FIGENA_AGENT_KEY in your shell.

{  "ok": true,  "code": "common.success",  "data": {    "profile": "production",    "authenticated": true,    "authType": "user",    "user": { "id": "<user-id>", "email": "you@example.com" },    "sources": { "storedUserToken": true, "storedAgentKey": false, "envAgentKey": false }  }}

Where credentials are stored

The CLI keeps its files in the .figena folder in your home directory: config.json for profiles and credentials.json for sign-ins and Agent Keys. Set FIGENA_HOME to use a different folder. The CLI creates the folder so only your user can open it and the files so only your user can read them, and figena doctor reports whether existing files are still private.