--- title: ggui CLI description: Open command-line tool for the ggui protocol — local dev, self-host, marketplace authoring, and (coming soon) ggui.ai cloud provisioning. --- `ggui` is the open CLI for the ggui protocol, shipped as [`@ggui-ai/cli`](https://www.npmjs.com/package/@ggui-ai/cli). It does three jobs: 1. **Local protocol dev + self-host** — `ggui dev` (iterate gadgets and blueprints against a local registry + dev hub), `ggui serve` (run a self-hosted personal-mode app), `ggui keys … --keys-file` (mint local bearers, no account), and `ggui export-pool` (share blueprints across deployments). Account-free; runs entirely on your machine. **Available now.** 2. **Marketplace authoring** — `ggui gadget` / `ggui blueprint` author and publish marketplace artifacts; `ggui theme validate` checks DTCG theme files. 3. **ggui.ai cloud provisioning** _(Preview — managed cloud, coming soon)_ — `ggui login` / `keys` / `create` / `deploy` / `push` / `provider-key` provision apps and `ggui_user_*` connector keys against the managed ggui.ai cloud. :::note[ggui vs guuey] `ggui` is the open CLI for the **ggui protocol** (`@ggui-ai/cli`). The closed `guuey` CLI drives the **guuey.com** SaaS platform (agent deploys, logs, secrets) and has its own auth — none of the commands below configure it. ::: ## Install ```bash npm install -g @ggui-ai/cli # or pnpm add -g @ggui-ai/cli ``` ## Commands at a glance | Command | Purpose | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ggui dev` | Boot the local UI registry server, open the dev hub, optionally supervise an agent | | `ggui serve` | Run the open self-hosted personal-mode app (MCP server + supervised agent) | | `ggui keys` | List / create / revoke connector keys. With `--keys-file `, keys are minted into a local JSON store (no account) that `ggui serve --keys-file` reads — the self-host path. Without it, keys target the ggui.ai cloud _(Preview — coming soon)_. Also registers publisher Ed25519 public keys (see [`ggui keys register`](/cli/keys-register/)) | | `ggui theme` | Validate a DTCG theme file against the protocol's theme schema (`theme validate `) | | `ggui export-pool` | Export this deployment's reusable blueprints as a directory artifact, loadable elsewhere via `ggui serve --seed-pool ` | | `ggui gadget` | Author and consume marketplace gadgets (`create` / `publish` / `install` / `search`) | | `ggui blueprint` | Author UI blueprints for the marketplace (`create` / `publish` / `install` / `uninstall` / `search`) | | `ggui login` | _(Preview — coming soon)_ Sign into `api.ggui.ai` via the OAuth Device Authorization Grant | | `ggui logout` | _(Preview — coming soon)_ Discard the local `api.ggui.ai` session | | `ggui whoami` | _(Preview — coming soon)_ Print the authenticated user | | `ggui create` | _(Preview — coming soon)_ Provision a ggui.ai cloud app (`create app`) | | `ggui deploy` | _(Preview — coming soon)_ Idempotent ggui.ai cloud provisioning; `--push-keys` also pushes provider keys | | `ggui push` | _(Preview — coming soon)_ Compile and upload local-pool blueprints to a ggui.ai cloud app | | `ggui provider-key` | _(Preview — coming soon)_ Push an LLM provider key to a ggui.ai cloud app (`provider-key set`) | | `ggui --version` | Print the installed `@ggui-ai/cli` version | Run `ggui --help` for the per-command flag list. `ggui --help` prints the full surface. ## Local dev & self-host `ggui dev` and `ggui serve` are the two ways to run the protocol locally: - **[`ggui dev`](/cli/dev/)** — inner-loop dev hub. Loads `ggui.ui.json` manifests, serves the local gadget + blueprint registry, and (with `--agent `) supervises a local agent runtime. Default `127.0.0.1:6780`. Use while iterating. - **[`ggui serve`](/cli/serve/)** — production-shaped self-host. Boots an MCP server with a supervised agent (`ggui.json#agent.entry`), ready to put behind your own auth on a public URL. Default `127.0.0.1:6781`; clients connect over WebSocket at `ws://127.0.0.1:6781/ws` (or `wss:///ws` once tunneled). See [Reference deploys](/self-hosted/reference-deploys/) for Docker / Fly / Render manifests and [OSS Quick Start](/oss-quickstart/) for the bootstrap. Run `ggui dev --help` or `ggui serve --help` for the full flag list. ## Bearer keys — local first The available-now path is account-free: `ggui keys list / create / revoke --keys-file ` mints bearer keys into a local JSON store — the same file format `ggui serve --keys-file` reads — so a locally minted bearer authenticates on the next serve boot. No account involved. ### ggui.ai auth & keys (Preview — coming soon) The managed ggui.ai cloud is coming soon. Once live, agent runtimes pointed at the universal MCP at `mcp.ggui.ai` authenticate with a `ggui_user_*` connector key, and `ggui login` signs the CLI into `api.ggui.ai` so you can mint and revoke those keys from the terminal — see [`ggui login`](/cli/login/) for the device-flow walkthrough plus `whoami`, `keys list / create / revoke`, and `logout`. ## Pairing a client app `ggui` has no `pair` subcommand. To pair a client to a `ggui serve` instance, follow [Self-hosted pairing](/self-hosted/pairing/) — tunnel setup, QR handshake, and the AuthAdapter swap-in for production. ## Configuration Two environment variables control where the CLI talks and stores state: | Variable | Default | Purpose | | ----------------- | --------------------- | -------------------------------------------------------------------------------------------------------- | | `GGUI_API_URL` | `https://api.ggui.ai` | Override the auth + key-management endpoint. Useful for sandbox / dev testing. | | `GGUI_CONFIG_DIR` | `~/.ggui` | Override the `~/.ggui` root (`auth.json`, BYOK `credentials.json`, embedding-model cache, publisher keypairs). Useful for isolated dev shells. | ## Versioning ```bash ggui --version ``` Versions track the `@ggui-ai/cli` npm package. Protocol semantics are pinned to the `@ggui-ai/protocol` major version it bundles — see [Protocol version policy](/protocol/version-policy/) for what changes between major bumps.