Early preview — you found Guuey before launch · official launch soon

CLI

read as .md

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

Install

The CLI ships on npm as @guuey/cli:

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

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. For headless or CI use, pass a pre-minted API key instead:

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.

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

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.

Force a mode with --declarative or --code. Pick a runtime pod size with --size (xs | sm | md | lg | xl, default xs) and tag the version with --label.

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

Beyond the basics