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.

Choosing a model

agent.model takes a provider model id. For the Claude Agent SDK framework, the current Anthropic family on Guuey:

• Claude Fable 5.1 (claude-fable-5-1) — announced: Anthropic’s model for the most demanding reasoning (adaptive thinking is always on), in the registry but not yet available to run on Guuey; it becomes selectable when the registry marks it current.
• 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.

Current prices are on Anthropic’s pricing page; managed-model usage is metered per Plans & billing. The list above is checked against the platform’s model registry on every docs build, so an id you read here is one the registry lists.

One thing to know for when Fable 5.1 becomes available and you switch a code-mode agent to it: 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

The CLI stamps the app’s appId into the file after your first deploy — you don’t write it by hand. (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.

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

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.

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).

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

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: POST /agent/invoke against localhost before you deploy. (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.
• 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.
• 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).

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.