ggui CLI

ggui is the open CLI for the ggui protocol, shipped as @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.

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

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 <path>, 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)
ggui theme	Validate a DTCG theme file against the protocol’s theme schema (theme validate <path>)
ggui export-pool	Export this deployment’s reusable blueprints as a directory artifact, loadable elsewhere via ggui serve --seed-pool <dir>
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 <command> --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 — inner-loop dev hub. Loads ggui.ui.json manifests, serves the local gadget + blueprint registry, and (with --agent <entry>) supervises a local agent runtime. Default 127.0.0.1:6780. Use while iterating.
• ggui 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://<your-server>/ws once tunneled). See Reference deploys for Docker / Fly / Render manifests and OSS Quick Start 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 <path> 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 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 — 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

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 for what changes between major bumps.