---
title: CLI
description: Install the Guuey CLI, log in, define your agent in guuey.json, and deploy it to Guuey hosting.
---

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 early 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`](https://www.npmjs.com/package/@guuey/cli):

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

## Log in

```bash
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:

```bash
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:

```json
{
  "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](https://docs.ggui.ai) 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:

```bash
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:

```bash
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:

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

## Deploy

```bash
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:

```bash
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:

```bash
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

The CLI also manages apps (`guuey apps create|list|get|update|delete`), hosted MCP servers (`guuey mcp deploy|list|status|logs|delete|secrets`), environment variables (`guuey env set|list|unset`), and worker conformance (`guuey worker verify`). Run `guuey --help` for the full surface, and `guuey open dashboard` to jump to the console.