---
title: ggui login
description: Sign the @ggui-ai/cli into ggui.ai via OAuth 2.0 Device Authorization Grant to manage hosted connector keys.
---

:::caution[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](/oss-quickstart/); for connector keys without an account, see [local keys](#no-account-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`](https://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](https://datatracker.ietf.org/doc/html/rfc8628): 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.

:::note[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`](https://guuey.com) agent-hosting platform has its own CLI and auth — not configured by this flow.
:::

## Install

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

## Sign in

```bash
$ 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

```text
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:

```bash
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`:

```bash
GGUI_CONFIG_DIR=/tmp/ggui-test ggui login
```

## Verify

```bash
$ 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:

```bash
$ 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.

```bash
$ 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:

```bash
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`](/cli/keys-register/) for publishing your **author** Ed25519 key to the marketplace (a different key, with a different purpose).

## Sign out

```bash
$ 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](/troubleshooting/).

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