CLI

The guuey CLI is the code path onto the platform: it scaffolds an agent project, runs it locally, and deploys it to Guuey hosting.

Note

Guuey is in public beta preview. The CLI is published and installable today, but you need a Guuey account to log in and deploy.

Install

The CLI ships on npm as @guuey/cli:

npm install -g @guuey/cli
guuey --version

The CLI talks to Guuey’s production API out of the box — no endpoint configuration needed. To point it somewhere else, set GUUEY_API_URL (keep the /v1 suffix — route paths are appended to it); the environment variable always wins over the built-in default.

Log in

guuey login

This opens your browser, authenticates you with your Guuey account, and delivers an API key back to the CLI via a localhost callback. On a remote or SSH session, guuey login --no-browser prints the auth URL instead — open it anywhere and paste the token back at the prompt. For headless or CI use, pass a pre-minted API key:

guuey login --token guuey_user_...

Check who you are with guuey whoami; clear credentials with guuey logout.

The agent definition: guuey.json

Every project is described by a single guuey.json at the project root. The agent section is the deployable definition — framework, model, system prompt, and MCP servers. A minimal valid file:

{
  "schema": "1",
  "agent": {
    "framework": "claude-agent-sdk",
    "model": "claude-sonnet-5",
    "systemPrompt": { "file": "prompts/system.md" }
  }
}

Everything else defaults. Notably, agent.mcpServers defaults to the ggui server at https://mcp.ggui.ai, which gives your agent generative UI out of the box — see the ggui docs for what that enables. Servers you declare merge on top of the default; the platform is otherwise MCP-server-agnostic.

guuey.json MCP servers with credential: 'oauth' accept authMode: 'upfront' | 'lazy'. 'upfront' schedules the broker’s sign-in before the first turn: the agent’s first ask carries metadata.authMode = "upfront", and @guuey/chat renders the connect-first step instead of an aside mid-conversation. Absent = today’s on-demand behaviour — an existing embedder sees no change unless its app’s builder opts a server in. Whatever the mode, the model reads each OAuth server’s state for the turn in the briefing’s Connected services section — see What wraps your prompt.

Choosing a model

agent.model takes a provider model id. Which vendor’s ids apply follows the framework your agent runs on: the Claude Agent SDK runs Anthropic models, the OpenAI Agents SDK runs OpenAI models, and Google ADK runs Gemini models. Every list below is checked against the platform’s model registry on every docs build, so an id you read here is one the registry lists — and a row marked announced is in the registry but not yet serving on Guuey; the console’s model rack shows it the same way.

Anthropic (Claude Agent SDK)

• Claude Fable 5.1 (claude-fable-5-1) — Anthropic’s model for the most demanding reasoning (adaptive thinking is always on); in Guuey’s Anthropic lineup.
• Claude Opus 5 (claude-opus-5) — Anthropic’s recommended starting point for most workloads.
• Claude Sonnet 5 (claude-sonnet-5) — Guuey’s default, and what the scaffold writes: the cost-per-quality call for a hosted agent that runs all day.
• Claude Haiku 4.5 (claude-haiku-4-5) — the cheapest of the family; also the earliest scheduled retirement in it (not before October 15, 2026).
• Claude Fable 5 (claude-fable-5) — legacy in Anthropic’s lineup but still active and available (retirement not before June 9, 2027) — the top of the lineup you can run on Guuey today.

OpenAI (OpenAI Agents SDK)

• GPT-6 Astra (gpt-6-astra) — in Guuey’s OpenAI lineup, served through the managed key; read the long-context heads-up below before you route large prompts to it.
• GPT-5.6 Terra (gpt-5.6-terra) — Guuey’s default for OpenAI-framework agents, and what the scaffold writes.
• GPT-5.6 Sol (gpt-5.6-sol) — in the lineup.
• Also available: GPT-5.6 Luna (gpt-5.6-luna), GPT-5.5 (gpt-5.5), GPT-5.4 (gpt-5.4), GPT-4o (gpt-4o), GPT-4o Mini (gpt-4o-mini).

Google (Google ADK)

• Gemini 3.8 Flash (gemini-3.8-flash) — in Guuey’s Google lineup, served through the managed key.
• Gemini 3.6 Flash (gemini-3.6-flash) — Guuey’s default for Google-framework agents, and what the scaffold writes.
• Gemini 3.5 Flash Lite (gemini-3.5-flash-lite) — in the lineup.
• Also available: Gemini 3.5 Flash (gemini-3.5-flash), Gemini 3.1 Pro (gemini-3.1-pro), Gemini 2.5 Flash (gemini-2.5-flash), Gemini 2.5 Pro (gemini-2.5-pro).

On the Google ADK facet, outputTokens now counts every generated token including reasoning (Gemini’s candidatesTokenCount + thoughtsTokenCount, guarded against double-counting where the provider’s total already balances on candidates); reasoningTokens carries the thoughts breakdown separately. Exception: @google/adk’s Interactions-API route reports no thoughts, so there outputTokens stays exclusive and reasoningTokens is absent (upstream gap). Re-baseline any per-token budget you set against the new count.

Managed-model usage is metered per Plans & billing; each vendor’s list prices are on its own pricing page (Anthropic’s is here).

Long-context heads-up for GPT-6 Astra: OpenAI prices prompts above 272K input tokens at 2×; Guuey’s usage meter has no long-context tier yet, so those prompts are billed at the model’s base per-token rate until the tier lands (guuey#818).

One thing to know if you switch a code-mode agent to Fable 5.1: it rejects non-default sampling parameters (temperature, top_p, top_k), forced tool_choice, and manual thinking budgets — adaptive thinking is always on. Guuey’s own runners send none of those; if your worker code sets them, drop them first.

Create the file in an existing directory with:

guuey config init

On a code-mode project, your first guuey deploy from an interactive terminal asks for an app name, creates the app and stamps its appId into the file — you don’t write it by hand. That auto-create is TTY-only and code-mode-only: in CI or any non-interactive run, and for a declarative project, bind the app first — pass --app-id <id>, run guuey pull --app-id <id> to bind an existing app, or create one with guuey apps create --name "My App". (workspaceId is only needed when you deploy hosted MCP servers, supplied via guuey.json, --workspace, or $GUUEY_WORKSPACE.) Secrets never go in guuey.json; use guuey env set KEY=VALUE. As of @guuey/cli 0.19.0 every deploy names its target and where it came from — Deploying to app <id> (from --app-id | GUUEY_APP_ID | guuey.json | global-config). — in that precedence: --app-id wins for that deploy only, then the GUUEY_APP_ID environment variable, then the guuey.json binding, then the global default in ~/.guuey/config.json (used only when there is no guuey.json at all). A project whose guuey.json carries no appId is unbound: GUUEY_APP_ID is ignored there (GUUEY_APP_ID=<id> ignored: this project has no binding of its own — pass --app-id <id> to target it. Creating a new app instead.) and the global default is deliberately not used — an interactive deploy of a code-mode project offers to create and link a new app; a non-interactive run — or a declarative project, whatever the terminal — stops with No app linked, naming the ways out (--app-id <id>, guuey pull --app-id <id>, or an interactive code-mode deploy).

Create a project

Start from a working scaffold:

guuey create my-agent --framework claude-agent-sdk

Supported frameworks for create are claude-agent-sdk and openai-agents-sdk. You can also scaffold without installing the CLI first:

npx @guuey/create-agentic-app my-agent

The scaffold carries zero analytics bytes by default; --analytics posthog opts a project into PostHog, reading VITE_POSTHOG_KEY (and an optional VITE_POSTHOG_HOST) at build time — nothing is sent without that key. The Google ADK template scaffolds @google/adk ^2.0.0. After scaffolding, pnpm bootstrap writes the brand, copy and the chat theme document locally; pnpm bootstrap -- --link pushes them to the platform — the allowed origins you name, then the brand accent, then the chat theme (theme.json, kept in step with guuey.app.json’s mode and accent); each push prints ✓ or a named refusal, and the run keeps going. See Your first agentic app.

Prefer a guided walkthrough? Your first agentic app takes the scaffold from npx to a deployed agent step by step.

Built your agent without code? guuey pull --app-id <id> brings its live definition into a local guuey.json, externalizing the system prompt to prompts/system.md so the project stays editable. Check that into your repo and it round-trips losslessly through guuey deploy — or manage it with guuey agent apply from then on (see Agents as code).

Deploy

guuey deploy

deploy auto-detects which of two modes your project uses:

• Declarative mode — guuey.json only, no build step. Your agent is the definition: prompt, model, MCP servers.
• Code mode — builds and deploys your guuey.worker.js worker bundle (or uses a root Dockerfile if present), deploying your MCP servers, generative UI registration, and the agent itself in one command.

In code mode, the worker bundle implements the Guuey Worker Protocol v1 — @guuey/worker on npm ships the contract types and the tiered worker SDK (typed interpreter + serve loop), and guuey worker verify checks a built guuey.worker.js for conformance before you deploy. The create-agentic-app scaffold above is a working code-mode starting point.

When nothing binds an app, deploy stops with a remedy for the mode you are in — set appId in guuey.json, pass --app-id <id>, or guuey pull --app-id <id> to bind an existing app; in code mode it adds “run guuey deploy in an interactive terminal to create one”, in declarative mode “guuey apps create --name <name> and put its id in guuey.json”. An app that deploy creates carries the manifest’s framework and model. After Live at <url>, a one-time Look: line prints when the app renders the Guuey theme (no chat theme of its own), naming the two write paths — the console’s Design → Chat theme, or app.theme in guuey.json, which guuey deploy (code apps) and guuey agent apply both apply; it never prints when the app has a theme. When guuey.json carries app.theme and the app has no chat theme yet, deploy writes it right after Live at and prints a Theme: line; an app that already has a theme is never overwritten by a deploy — the line names guuey apps update --chat-theme-file and the console as the doors that change it (a refused document prints the field and the door; the deploy itself still succeeds).

Force a mode with --declarative or --code. Pick a runtime pod size with --size (xs | sm | md | lg | xl, default xs — see Plans & billing for what each size buys) and tag the version with --label. Code-mode builds run in a separate build job sized by --build-size (sm | md | lg | xl, default md). In code mode the deploy first checks for node_modules at the project root; without it the deploy installs for you (corepack pnpm install, before anything is pushed) and then builds. Pass --no-install to stop instead — No node_modules in <root> — you passed --no-install; run "corepack pnpm install" and re-run guuey deploy. (auto-install as of @guuey/cli 0.20.0 — there is no 0.19.1 on npm; the 0.19.0 --install flag is gone and a stale --install is silently ignored; the scaffold installs by default too, --no-install to skip).

Scaling and runtime updates

Two live knobs ride guuey deploy and also stand alone on guuey agent config, which reads and patches the hosted app without a redeploy (changes converge within ~5 minutes):

• --max-pods <n> sets the app’s pod count. Your plan sets the ceiling — the server refuses more, naming the limit. With no scaling mode chosen, a hand-set count runs as a fixed count — the auto-scaler is off; guuey agent config --scaling auto keeps n as the ceiling the platform may grow to. See Plans & billing.
• --runtime-auto-update on|off — on (the default) keeps the agent on the platform’s current runtime image; off pins it at the image captured by each deploy.

A third knob stands on guuey agent config alone: --worker-reservation-mib <n> sets the per-turn worker memory reservation in MiB — the memory each concurrent conversation is given (platform default 256 MiB; your plan’s ceiling is on the readout and the server gates at it; the clamped value is decided at deploy time, and a live app takes it without a redeploy). --clear-worker-reservation returns to the platform default. The readout prints it as Worker memory: … — ceiling … MiB on this plan.

--scaling auto|fixed also stands on guuey agent config alone, and it is what the pod count means. Under auto the platform adds a pod when every turn slot is busy, up to the pod count — the default for an app that never hand-set a count. Under fixed the app runs exactly that many pods and the auto-scaler is off. Setting --max-pods without ever choosing a mode lands fixed; guuey agent config with no flags prints the mode the platform runs.

guuey agent config with no flags prints the app’s current hosting config; add --json for machine-readable output.

After deploying:

guuey test "hello"          # send a test message, print the response
guuey logs --follow          # live-tail runtime logs
guuey deployments list       # list deployment builds
guuey undeploy               # tear down the deployment (keeps the app)

Local dev

Run your built worker locally behind the same SSE endpoint the hosted pod serves:

guuey dev --serve --port 6790

This gives you pod-parity iteration: GET /readyz answers 200 while it is serving; 503 means it is draining or degraded (retry); a refused connection means it isn’t listening yet, and POST /agent/invoke streams against localhost before you deploy — the same two routes the hosted pod serves. (Plain guuey dev — a device bridge with a QR code — is coming soon; the CLI says so itself.)

Deploying from CI: service tokens

Your own login (guuey login) mints a user key — it belongs to you, and it stops working if you log out or rotate. A CI pipeline needs a credential that belongs to the app, not to a person:

guuey tokens create --label "github-actions" --app-id <appId>

This mints an app-scoped service token (guuey_svc_*). The secret is printed once — store it as a CI secret and pass it through GUUEY_API_KEY. Service tokens don’t expire; guuey tokens revoke <tokenId> is the kill switch (auth stops within seconds), and guuey tokens list shows prefix, label, and lifecycle — never the secret.

A service token is deliberately narrow: it can call guuey agent apply / guuey agent status / guuey agent rollback (the reconcile routes) and read deployment history for its one app — nothing else. guuey deploy needs a user key. The CI verb is guuey agent apply — one idempotent call that converges the hosted agent to your checked-in guuey.json, never rolls the pod for unchanged bytes, and answers with content hashes your pipeline can gate on. See Agents as code for the manifest, the drift gate, and a GitHub Actions example.

Service tokens are for personal apps: an app owned by a workspace can’t mint one. A workspace-owned app authenticates CI with a workspace API key (guuey_wkz_*) instead, passed through the same GUUEY_API_KEY variable — see Workspace-owned apps.

Beyond the basics

The rest of the surface, briefly:

• Apps — guuey apps create|list|get|update|delete|recover|access|publish|unpublish. apps delete starts a 30-day pending deletion; apps recover cancels it inside the window (the widget signing key comes back with it, but billing does not resume on its own). apps list and apps get show an app’s trial status and end date — see the 7-day trial. apps access sets the guest-chat policy (--guests on|off, --guest-limit), and apps publish|unpublish manage the store listing. apps create also reports the app’s first impression — the greeting and suggestion chips ggui prepares for a fresh app before anyone types, a paid-plan feature: on an entitled account it is requested at creation; on a free wallet the command prints one line saying so with a link to choose a plan (firstImpression in --json, with entitled and, when refused, the message and billingUrl). apps list shows each app’s Status and hides archived apps unless you pass --all (--json follows the same filter, so a script that relied on archived rows adds --all). apps update --chat-theme-file <path> sets the app’s chat theme from a theme JSON document (--clear-chat-theme removes it) — the write goes through the same validator as the console’s Design → Chat theme editor, and a refusal names the offending key or token. apps get <appId> prints the theme’s name and light accent (the effective theme); apps get <appId> --theme-json prints the stored chat theme document as JSON — what a write actually put on the app, courts included — and round-trips into apps update --chat-theme-file. See Theme the hosted surfaces.
• Custom domains and the slug — guuey domains add|list|verify|remove serves your agent on your own domain (see Custom domains); guuey slug claim|release manages the free short name every plan gets.
• Hosted MCP servers — guuey mcp new <name> scaffolds a server, guuey mcp deploy|list|status|logs|delete runs it on Guuey, guuey mcp secrets set|list|unset manages its secrets, and guuey mcp state list|export|wipe inspects or erases a user’s stored state.
• Third-party MCP authorizations — guuey mcp connections [revoke], guuey mcp connect <server> --app <id> — see Connecting third-party accounts.
• Provider keys (BYOK) — add your own model key in the console (Behavior → Model, or the workspace Provider keys panel), or supply it as an app environment variable (guuey env set ANTHROPIC_API_KEY=…); a dedicated guuey byok command is on the roadmap. See Credential custody.
• Environment variables — guuey env set|list|unset.
• Billing — guuey billing shows the plan per app, the saved card on file, and the account’s next invoice (total, issue date, per-agent shares) plus recent invoices; guuey billing invoice [--json] shows the next invoice alone. guuey billing topup --app <appId> --amount <usd> adds credits that pre-pay your next invoices: the amount is a whole-dollar figure from the account’s offered list (guuey billing prints it; any other amount is refused by name), the command prints the Checkout URL and opens it, and the balance is credited only once Stripe confirms that checkout — never at the command. When the account holds bonus credit, guuey billing prints that too (Bonus credit: $X — applied to usage lines on your next invoices, never the plan fee), and while a top-up promotion is open, the bonus percentage and its end date. Plan changes stay in the console — see Plans & billing. guuey billing movements [--json] lists the wallet’s credit movements newest first (the latest 50) — paid (credits purchased, applied to invoices) beside bonus (earned, applied to usage). guuey billing auto-recharge shows the wallet’s auto-recharge setting; --on --amount <usd> --threshold <usd> --cap <usd> turns it on — the platform adds that amount of credit whenever the balance would fall under the threshold, never past the monthly cap — after printing the terms and asking you to type yes (--yes answers for scripts; --receipts on|off sets whether each recharge emails a receipt — leave it out to keep the current setting); --off turns it off. The console’s Billing page carries the same setting.
• Housekeeping — guuey config show|set|unset for CLI configuration (see Configuration and environment variables for how the layers resolve), guuey status for connectivity, guuey pull to refresh guuey.json from hosted state, and guuey worker verify for worker conformance.

Run guuey --help for the full surface, and guuey open dashboard to jump to the console.

Configuration and environment variables

The CLI resolves its configuration through layers — the first layer that supplies a value wins:

1. Environment variables — always win.
2. A repo-local amplify_outputs.json — picked up when your project sits inside a checkout that has one; most projects don’t, and then this layer simply isn’t there.
3. ~/.guuey/config.json — user-level defaults, managed with guuey config show|set|unset.
4. Built-in production defaults — a fresh install talks to Guuey’s production API and console with zero setup.

Two environment variables cover the endpoints:

• GUUEY_API_URL — the REST API base every API call targets. Keep the /v1 suffix — route paths are appended to it.
• GUUEY_HOST — the platform console URL that guuey login opens and guuey open dashboard jumps to.

If you override one, override both together: an API key is minted by a console, and a key minted by one console does not authenticate against a different endpoint’s API (that mismatch surfaces as an authentication error — see Troubleshooting).

GUUEY_APP_ID overrides the configured app ID (see the deploy precedence above). As of @guuey/cli 0.19.0 this is the variable’s name — it was GGUI_APP_ID before, and there is no alias: scripts that exported GGUI_APP_ID must export GUUEY_APP_ID; the old name is ignored. (Breaking under 0.x, hence the 0.19.0 minor.)

Per-invocation credentials: GUUEY_API_KEY

GUUEY_API_KEY overrides the stored login for every authenticated command — set it and that invocation runs as that key, no guuey login involved. It accepts any key the platform mints: your user key, a service token (guuey_svc_*), or a workspace API key (guuey_wkz_*).

Two properties make it the right tool for switching identities or endpoints:

• The stored login is a single slot. guuey login writes one credential to ~/.guuey/auth.json; it is not keyed by host, so logging in against a different endpoint replaces what was there. GUUEY_API_KEY sidesteps the slot entirely.
• --config <path> moves configuration only, never credentials. The flag relocates config.json (non-secret defaults); the stored login stays where it is. Don’t reach for --config to isolate credentials — set GUUEY_API_KEY instead.

GUUEY_API_KEY="$MY_CI_KEY" guuey agent status

Troubleshooting

• A deploy is refused with TRIAL_EXPIRED — the app’s 7-day trial ended without a plan, so the app is paused. Choosing a plan resumes it automatically, no redeploy needed — see Plans and the 7-day trial.
• Requests fail with an authentication error — check guuey whoami (who you are) and guuey status (connectivity); a key minted against one environment does not work against another’s API URL.