ggui login

Coming soon

This page describes the managed hosted path (api.ggui.ai / console.ggui.ai), which is not yet live — it is not part of GGUI Preview 0.1.0. The self-hosted path is available today — start with the Quickstart; for connector keys without an account, see local keys below. This page is kept as a preview of the managed path and goes live when hosted ggui ships.

ggui login signs the open @ggui-ai/cli into api.ggui.ai so you can manage ggui_user_* connector keys from the terminal — list, mint, and revoke — without leaving your shell.

It uses the OAuth 2.0 Device Authorization Grant: the CLI prints a URL and a short code, you approve in any browser (even on a different machine), and tokens land on disk once approval completes.

ggui (protocol) vs guuey (platform)

This command targets the open ggui protocol CLI (@ggui-ai/cli) and the universal hosted MCP at mcp.ggui.ai. The closed guuey.com agent-hosting platform has its own CLI and auth — not configured by this flow.

Install

npm install -g @ggui-ai/cli
# or
pnpm add -g @ggui-ai/cli

Sign in

$ ggui login
Endpoint: https://api.ggui.ai (default)

Open this URL in your browser to approve:
  https://console.ggui.ai/cli-confirm/ABCD-EFGH

Verification code: ABCD-EFGH
(Confirm this matches what the browser shows.)

Waiting for approval…
Signed in. Tokens saved to ~/.ggui/auth.json.
Try `ggui whoami` or `ggui keys list`.

Under the hood:

1. Device code request — the CLI POSTs /v1/auth/device and prints the user-readable code plus URL.
2. Browser approval — console.ggui.ai/cli-confirm/<code> shows the same code, your account, and an Approve button. Confirm the codes match, then approve.
3. CLI polls /v1/auth/poll every few seconds until the server returns tokens.
4. Tokens land on disk — ~/.ggui/auth.json (mode 0600) holds the access bearer, the refresh bearer, and the API endpoint they were minted against.

The approval window is ~10 minutes. If it expires, just run ggui login again.

Flags

ggui login [--name <label>] [--no-open]

Flag	Purpose
--name	Device label shown in the console and ggui whoami. Defaults to ggui CLI on <hostname>. Lets you distinguish ggui CLI on laptop from ggui CLI on workstation.
--no-open	Skip auto-opening the verification URL. Implied when stdout isn’t a TTY, when BROWSER=none, or when CI=1 — so the flow stays sane in pipelines.

Configuration

Resolution order for the API endpoint:

1. GGUI_API_URL env var — operator override (sandbox / dev testing). Login prints (env).
2. ~/.ggui/auth.json#endpoint — captured at last login. Login prints (auth.json).
3. https://api.ggui.ai — production default. Login prints (default).

The suffix on the first Endpoint: line of ggui login tells you which tier won — useful when an unexpected GGUI_API_URL in your shell silently redirects the device flow at a sandbox.

For sandbox / non-prod testing:

GGUI_API_URL=https://abc123.execute-api.us-east-1.amazonaws.com ggui login

For an isolated dev shell that shouldn’t touch your real session, set GGUI_CONFIG_DIR:

GGUI_CONFIG_DIR=/tmp/ggui-test ggui login

Verify

$ ggui whoami
User ID:        <your-user-id>
Session ID:     <opaque-session-id>
Client:         ggui CLI on laptop
Access expires: 2026-04-26T18:09:14.000Z
Endpoint:       https://api.ggui.ai

Manage keys

Once signed in, you can mint connector keys from the terminal:

$ ggui keys create --name "my agent runtime"

API key:    ggui_user_AbCdEf...
ID:         a1b2c3d4-...
Prefix:     AbCdEfGh
Created:    2026-04-26T17:32:00.000Z

IMPORTANT: copy the API key now — it will NEVER be shown again.
Use it as the bearer token for the ggui-protocol-user MCP server.

The full secret is printed exactly once, GitHub-PAT-style. Lose it and you mint a new one.

Pass --expires-at <iso8601> to mint a key with a hard expiry.

$ ggui keys list
ID                                    PREFIX               NAME              STATUS  LAST USED
a1b2c3d4-...                          ggui_user_AbCdEfGh…  my agent runtime  active  —

$ ggui keys revoke a1b2c3d4-...
Revoked key a1b2c3d4-....

revoke is a soft-revoke — the row stays in the audit table, but every subsequent request from the key returns 401 Unauthorized. There’s no undo.

No account? Local keys

keys list / create / revoke also work with no account at all: pass --keys-file <path> to flip them to a local JSON store. The file format is the same one ggui serve --keys-file reads, so a locally minted bearer authenticates against your own server on the next boot — no ggui login needed:

ggui keys create --keys-file ./keys.json --name laptop
ggui serve --keys-file ./keys.json

This is the available-today path for GGUI Preview self-hosting.

See ggui keys register for publishing your author Ed25519 key to the marketplace (a different key, with a different purpose).

Sign out

$ ggui logout
Signed out. ~/.ggui/auth.json removed.

ggui logout deletes the local session. Server-side tokens stay valid until their TTL expires (~1h access, ~30d refresh). For sensitive scenarios, follow up with ggui keys revoke <id> for any keys minted during that session.

Troubleshooting

“Login window expired before approval” — you took longer than ~10 minutes. Run ggui login again.

“Session expired. Run ggui login again.” — both access and refresh tokens are dead (you’ve been away >30 days, or the server invalidated them). Re-authenticate.

“failed to start device flow” — check GGUI_API_URL, your network, and the troubleshooting page.

Browser didn’t open — fine. Copy the printed URL into any browser; the verification code in the URL matches the one printed beneath it.