Authenticating the CLI

The ForgeAI CLI authenticates to the cockpit with the OAuth Device Flow: the CLI shows you a short code, you approve it in your browser, and the CLI receives an access token that it stores encrypted on your machine. You need a working forge binary first — see Installing the CLI — and a cockpit account that belongs to at least one organization (see Organizations & members).

Point the CLI at your server first

The CLI's default server URL is http://localhost:3000. If your cockpit runs anywhere else, you must pass --server on your first login:

forge auth login --server https://forgeai-production-382c.up.railway.app

On successful login the URL is persisted to ~/.forgeai/config.json, so you only need the flag once. Every later command — including the background daemon started by forge connect — reads the persisted URL from that config file. There is no environment-variable override: if you skip --server, the CLI will try to authenticate against localhost:3000 and fail.

forge auth status also accepts --server if you want to check a different server without changing your saved configuration.

The device flow, step by step

1. Run forge auth login (with --server on first use). The CLI requests a device authorization from the cockpit and prints two things: a verification URL and a user code — an 8-character code such as ABCD2345 (the charset excludes easily confused characters like I, O, 0 and 1).
2. The CLI opens your browser automatically. If it cannot, open the printed URL yourself: the verification page lives at /device on the cockpit. When the URL already contains the code, the page forwards you straight to the approval step; otherwise type the code in.
3. Sign in to the cockpit if you are not already — you are redirected back to the approval page afterwards.
4. On /device/approve you see the code (shown grouped as XXXX-XXXX for readability) and the account email, and you select which organization(s) to link to this CLI. If you belong to exactly one organization it is pre-selected. Click Approve (or Deny to abort). You must be a member of at least one organization to approve a device.
5. Meanwhile the CLI polls the server every 5 seconds (backing off when asked to slow down) for up to 30 minutes. Once you approve, it prints Authentication successful! with your name, email, and the linked organizations.

After approval the CLI registers itself as a device in each linked organization, using a generated UUID as its cliId and your machine's hostname as its display name. The device then appears in the cockpit under Settings → CLI Devices. Registration counts against your plan's CLI-connection limit (1 on Free) — see Plans & billing. A limit failure is not reported during login itself — login still prints Authentication successful! — but the next forge connect surfaces the error and suggests upgrading your plan or unlinking an existing CLI.

Your default organization

The first organization in your approval selection becomes the CLI's default organization (with a single linked org, that org is the default). Commands that operate on a single org use it implicitly: forge cli list, forge cli unlink, forge journal status, and the open commands (forge task open, forge workflow open, forge release open). forge org list marks the default with a (default) tag, and forge auth status prints it as Org:.

There is currently no command to change the default organization: to switch it, run forge auth login again — the first organization linked by the new approval becomes the new default.

Where credentials are stored

File	Contents	Protection
~/.forgeai/config.json	Server URL, linked orgs, CLI id/name, agent settings	Plain JSON, file mode 0600, directory 0700
~/.forgeai/auth/credentials.json	Cloud access token	AES-256-GCM encrypted, file mode 0600

The token encryption key is derived (scrypt) from your machine's hostname and username, so the credentials file is not portable: copying it to another machine or user account produces an unreadable file, and you must log in again there. Note that this is a separate credential from the AI credentials used by agents (forge auth setup-claude / setup-codex / setup-opencode / setup-kilo) — see the CLI command reference and Security.

Checking your status

forge auth status

When authenticated, this prints your user name, email, server URL, and default organization, then sends a test heartbeat to the cockpit and reports Cloud: Connected or Cloud: Unreachable. If the token is invalid or expired, it tells you to run forge auth login again.

Tokens follow the cockpit's session lifetime: sessions last 20 days and are refreshed every 7 days of activity. A long-idle CLI will eventually need a fresh forge auth login. While connected, the CLI also detects repeated authentication failures on its WebSocket connection (3 in a row) and exits with a prompt to log in again.

Logging out

forge auth logout

Logout does three things:

1. Stops a running forge connect daemon (its connections are tied to the current token).
2. Deletes the encrypted credentials file.
3. Clears session-specific config — linked organizations, CLI identity, sync state — while preserving machine-level settings such as the server URL, agent type, and agent slots.

Your next forge auth login therefore reuses the saved server URL but starts with a clean organization link.

Security notes

• The access token is sent as a Bearer token in the Authorization header for REST calls, and in the connection auth payload for the Socket.io connection. It never appears in URLs.
• The CLI's Socket.io connection is WebSocket-only (no HTTP long-polling fallback). Always use an https:// server URL for remote cockpits: it protects the Bearer token in transit and upgrades the WebSocket to WSS. Self-hosted deployments must sit behind a WebSocket-capable HTTPS proxy — see Security.
• Anyone with access to your machine account could use the CLI as you; the encrypted-at-rest, machine-bound token limits exposure if the file itself leaks, but treat the machine as the security boundary.
• You can revoke a device at any time: run forge cli unlink <cliId> from any authenticated CLI, or unlink it in the cockpit under Settings → CLI Devices. Unlinking removes the device registration and unassigns its tasks.

Next steps

Once authenticated, run forge connect to bring your machine online and link a repository — see Connecting projects. If login fails, check Troubleshooting & FAQ or verify your server URL with forge auth status.