ggui login

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

It uses the OAuth 2.0 Device Authorization Grant flow: the CLI prints a URL plus a short code, you approve in any browser (even on a different machine), and the CLI lands tokens on disk once you’re done.

ggui.ai vs guuey.com

This command is for the open ggui CLI (@ggui-ai/cli) and the universal MCP at mcp.ggui.ai. The closed guuey CLI (agent-store ops on guuey.com) has its own auth and is 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?user_code=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`.

What happens, step by step:

1. Device code request — the CLI POSTs /v1/auth/device and prints the short user-readable code plus the URL.
2. You approve in the browser — console.ggui.ai/cli-confirm/<code> shows the same code, your account, and an Approve button. Sign in if you aren’t already, 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 login window is roughly 10 minutes. If you walk away from the terminal, just run ggui login again.

Flags

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

Flag	Purpose
--name	Friendly device label shown in the console + ggui whoami output. Defaults to ggui CLI on <hostname>. Useful when you want to tell ggui CLI on laptop apart from ggui CLI on workstation.
--no-open	Skip the auto-open of the verification URL. Implied automatically 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).
2. ~/.ggui/auth.json#endpoint — captured at last login.
3. https://api.ggui.ai — production default.

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-cognito-sub>
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.

$ 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 our audit table, but every subsequent request from the key returns 401 invalid_grant. There’s no undo.

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 that were minted during the session.

Troubleshooting

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

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

“failed to start device flow” — check GGUI_API_URL, your network, and the api.ggui.ai status page.

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