---
sidebar_position: 4
title: CLI Reference
---

# CLI Reference

Every command lives under `zibby agent <verb>` for consistency. The bare top-level forms (`zibby start`, `zibby deploy`, `zibby trigger`, `zibby logs`) are kept as backward-compat aliases — they call the same handlers — but new code should use the namespaced forms.

## Agent commands

| Command | What it does |
|---|---|
| [`zibby agent new <name>`](#agent-new) | Scaffold a new custom agent under `.zibby/workflows/<name>/`. |
| [`zibby agent run <name>`](#agent-run) | One-shot local execution. Same input flags as `trigger`. |
| [`zibby agent list`](#agent-list) | List local + deployed agents. |
| [`zibby agent deploy [name]`](#agent-deploy) | Deploy to Zibby Cloud. Interactive picker if name omitted. |
| [`zibby agent trigger [uuid]`](#agent-trigger) | Run a deployed agent remotely. UUID is canonical. |
| [`zibby agent logs [uuid] -t`](#agent-logs) | Tail logs from a run, Heroku-style. |
| [`zibby agent download <uuid>`](#agent-download) | Pull a deployed agent back to local. Edit + redeploy. |
| [`zibby agent delete <uuid>`](#agent-delete) | Delete a deployed agent. |
| [`zibby agent start <name>`](#agent-start) | Long-lived dev server (Studio integration). Most users want `run`. |
| [`zibby agent update <uuid>`](#agent-update) | One-shot edit of a deployed agent: model, review @mention, trigger events, name, max runtime. |
| [`zibby agent env <verb>`](#agent-env) | Manage per-agent encrypted env vars: `list`, `set`, `unset`, `push`. |

Plus the test recipe + memory + project setup:

| Command | What it does |
|---|---|
| [`zibby test [spec]`](#test) | Run a test spec (or inline string). Drives the browser via Cursor / Claude / Codex / Gemini. |
| [`zibby memory <verb>`](#memory) | Local + remote test-memory DB: `init`, `stats`, `cost`, `compact`, `reset`, `pull`, `push`, `remote …`. |
| [`zibby init [project]`](#init) | Bootstrap a Zibby project (config + creds). `-t <template>` to also scaffold an agent. |
| [`zibby template <verb>`](#template) | List or add agent templates: `list`, `add <name>`. |

Auth + admin:

| Command | What it does |
|---|---|
| `zibby login` | OAuth in browser. Writes session to `~/.zibby/config.json`. |
| `zibby logout` | Clear session. |
| `zibby status` | Show current auth state. |
| `zibby list` | List projects + API tokens you have access to. |

## agent new {#agent-new}

```bash
zibby agent new [name]
```

Scaffolds `.zibby/workflows/<name>/` with a starter `graph.mjs`, `nodes/example.mjs`, `package.json`, and `workflow.json` manifest. Auto-runs `npm install` in the new folder unless `--skip-install`.

Options:
- `--skip-install` — skip `npm install`
- If `name` is omitted, the CLI generates one (`zealous-otter`, etc.)

## agent run {#agent-run}

```bash
zibby agent run <agent-name>
```

Loads `graph.mjs`, instantiates the entry class, runs the graph **once** in-process, prints results, and exits. Output → `.zibby/output/sessions/<sessionId>/`.

Mirrors `zibby agent trigger` so the same input flags work locally and in the cloud — flip the verb and the project, and your local dev loop is exactly the same call shape your CI/CD uses.

Options:
- `-p, --param <key=value>` — input param (repeatable, highest precedence). Example: `-p ticket=BUG-123 -p priority=high`
- `--input <json>` — input as JSON string
- `--input-file <path>` — input as JSON file (lowest precedence)

Examples:
```bash
zibby agent run my-agent
zibby agent run my-agent -p ticket=BUG-123
zibby agent run my-agent --input '{"ticket":"BUG-123","priority":"high"}'
zibby agent run my-agent --input-file payload.json -p priority=urgent
```

## agent start {#agent-start}

```bash
zibby agent start <agent-name>
```

Long-lived local dev server (default port 3848). Listens on `POST /trigger` for input payloads and runs the agent in-process. Used today by the Studio desktop app — for plain CLI use, prefer `agent run`.

Options:
- `-p, --port <port>` — override the default port (3848)

## agent list {#agent-list}

```bash
zibby agent list
```

Shows both local agents (folders under `.zibby/workflows/`) and deployed ones (from cloud, scoped to projects you have access to). Output is a table with UUID, Name, Project, Version. `-` in any column means "not applicable" (e.g. local-only agents have no UUID yet).

Options:
- `--local-only` — skip the cloud query
- `--remote-only` — skip the local scan
- `--project <id>` — filter to one project

## agent deploy {#agent-deploy}

```bash
zibby agent deploy [agent-name]
```

Two phases:
1. Upload sources to S3 (presigned PUT). The CLI also resolves your `.zibby.config.mjs` (if present at project root) and includes it in the bundle as `zibby.config.json` — see [Bundle build](./cloud/bundles).
2. CodeBuild downloads, runs `npm install --omit=dev`, packages a tarball, uploads it. The tarball is what each cloud execution downloads at trigger time.

After success, the CLI writes `.zibby/workflows/<name>/.zibby-deploy.json` with the canonical UUID. Commit this file.

Options:
- `--project <id>` — skip the project picker
- `--api-key <key>` — auth via API key (or set `ZIBBY_API_KEY`)
- `--env <path>` — sync a `.env` file into per-agent env vars after deploy. Repeatable (later files override). See [Per-agent env vars](./cloud/env-vars).
- `--verbose` — show raw CodeBuild logs during the bundle build

## agent trigger {#agent-trigger}

```bash
zibby agent trigger <uuid>
```

UUID is required (or omit for interactive picker). Names aren't accepted — pass the UUID from `.zibby-deploy.json` or `agent list`.

Options:
- `-p, --param <key=value>` — input param (repeatable, highest precedence)
- `--input <json>` — input as JSON string
- `--input-file <path>` — input as JSON/YAML file (lowest precedence)
- `--idempotency-key <key>` — prevent duplicate executions
- `--api-key <key>` — auth via API key

## agent logs {#agent-logs}

```bash
zibby agent logs <uuid>          # dump latest run
zibby agent logs <uuid> -t       # tail live (Heroku-style)
```

When `-t` is set and the agent finishes, the stream waits for the next trigger of the same agent and auto-switches to streaming it. Ctrl+C to exit.

Options:
- `-t, --follow` — live tail
- `--lines <n>` — max log lines per fetch (default: 500)
- `--all --workflow <name>` — interleaved logs from all runs (requires `--workflow`)
- `--api-key <key>` — auth via API key

**Storage & retention.** Live logs are kept in CloudWatch for 30 days. Beyond that, the per-run session folder (uploaded to S3 at the end of every execution) is the long-term archive — pull it back with `zibby agent download <uuid>`.

## agent update {#agent-update}

```bash
zibby agent update <uuid> --model claude:sonnet-4.6     # switch vendor:model
zibby agent update <uuid> --mention @zibby              # review @mention token
zibby agent update <uuid> --triggers mention,comment    # WHICH events fire a review
zibby agent update <uuid> --name "FE Review Bot" --max-runtime 30
```

The ONE consolidated editor for per-agent settings that used to be
dashboard-only. Flags can be combined; the command echoes the updated
settings so you can confirm what changed.

`--triggers` takes friendly names and controls **when a review agent runs**:

| Name | Fires on |
|---|---|
| `opened` | a new PR/MR is opened |
| `commit` | new commits are pushed to an open PR/MR |
| `mention` | someone @-mentions the agent, or replies in one of its threads |

`--triggers mention` is the cost-saving mode — the agent reviews **only when
asked**. New review agents deploy mention-only by default; existing agents keep
their current behaviour until you change it.

Driving Zibby from an AI editor instead of a shell? The MCP twin is
**`zibby_update_agent`** with the same fields (`model`, `mentionToken`,
`triggerEvents`, `displayName`, `maxRuntimeMinutes`).

Env vars, custom MCP servers and stores are separate surfaces:
`zibby agent env …`, `zibby_add_mcp`, `zibby_set_node_stores`.

## agent env {#agent-env}

Per-agent encrypted env vars — KMS-stored on the agent record, injected into the Fargate task at trigger time. Agent env wins over project secrets on conflict.

```bash
zibby agent env list <uuid>                       # show key names (no values)
zibby agent env set <uuid> ANTHROPIC_API_KEY=sk-…  # add or rotate one
zibby agent env unset <uuid> OLD_KEY               # remove one
zibby agent env push <uuid> --file .env [--file .env.prod]   # bulk replace from .env files
```

`push` accepts repeatable `--file` (later files override). `list` only ever returns key names — values never leave the encrypted blob.

The shortcut for first-time setup is `zibby agent deploy --env .env`, which runs `push` automatically against the new UUID. Full guide: [Per-agent env vars](./cloud/env-vars).

## agent download {#agent-download}

```bash
zibby agent download <uuid>
```

Pulls the deployed agent's sources back into `.zibby/workflows/<name>/`, including the `.zibby-deploy.json` manifest. Useful when collaborators need the source from cloud.

Options:
- `--type <type>` — for built-in agents (`analysis`, `implementation`, `run_test`)
- `--output <dir>` — alternate output base
- `--include-default` — pull the built-in default graph if no custom one exists

## agent delete {#agent-delete}

```bash
zibby agent delete <uuid>
```

Removes the agent from cloud (and its trigger URL). Local files are not touched.

## test {#test}

```bash
zibby test [spec-path]
zibby test "go to example.com and verify the title is 'Example Domain'"   # inline
```

Built-in browser-test recipe. Reads a `.txt` spec (or inline string), drives a real browser via the configured agent, generates a Playwright script + verification video. See [Recipes → Test](./recipes/test) for the long form.

Common options:
- `--agent <claude|cursor|codex|gemini>` — override the configured agent for this run
- `--workflow <name>` — use a non-default workflow (e.g. `QuickSmokeWorkflow`)
- `--headless` — run headless (default is headed)
- `-m, --mem` — enable test memory (Dolt-backed knowledge from prior runs)
- `--sources <ids> --execution <id>` — run cloud-stored test cases (comma-separated IDs)
- `--node <name> --session <id|last>` — re-execute one phase from a prior session
- `--sync` / `--no-sync` — force / skip cloud upload
- `--collection <id|name>` and `--folder <path>` — categorize the run on the cloud dashboard
- `--verbose` / `--debug` — escalate log levels
- `-o, --open` — open results in browser after completion
- `--auto-approve` — auto-approve MCP tools (CI/CD)

## memory {#memory}

Test memory is a local-first Dolt SQL DB at `.zibby/memory/.dolt/` that learns selectors, page model, navigation, and run history from every `zibby test` run. See [Test memory](./tests/memory) for the deeper explainer.

```bash
zibby memory init        # initialize the local DB (auto-runs on first `zibby test -m`)
zibby memory stats       # row counts, last commit, per-spec breakdown
zibby memory cost        # real LLM token spend per spec / per domain
zibby memory compact     # prune old runs + Dolt GC (default: --max-runs 50, --max-age 90)
zibby memory reset -f    # wipe the DB
```

Optional team sync:

```bash
zibby memory remote add <url>           # BYO: aws://, gs://, https://, file:///
zibby memory remote use --hosted        # Zibby-managed S3 (signed-in users only)
zibby memory remote info                # show current remote
zibby memory remote remove [name]       # drop the remote (default: origin)

zibby memory pull                       # pull from remote (auto on test start when configured)
zibby memory push                       # push to remote (auto after passing tests)
```

When `memorySync.remote` is set in `.zibby.config.mjs` (`'hosted'` or an `aws://...` URL), `zibby init` auto-wires the remote on first run — teammates clone, run init, and they're plugged in.

## init {#init}

```bash
zibby init [project-name]
zibby init -t browser-test-automation   # also scaffold the test recipe
```

Bare init by default — writes `.zibby.config.mjs`, sets up agent credentials, configures memory. Pass `-t <template>` to also scaffold an agent template into `.zibby/`.

Common options:
- `-t, --template <name>` — agent template to scaffold (see `zibby template list`). Default: none (config + creds only).
- `--agent <claude|cursor|codex|gemini>` — pick the agent up front instead of prompting
- `--memory-backend <mem0|dolt>` — memory backend (default: `mem0` — semantic vector memory, billed through the agent run in cloud, falls back to `dolt` if the embedding proxy is unavailable; pass `dolt` for self-contained structured memory — see [Chat memory](./skills/chat-memory.md))
- `--skip-install` / `--skip-memory` — skip `npm install` / skip memory setup
- `-f, --force` — overwrite existing config
- `--api-key <key>` — non-interactive Zibby API key (for `--cloud-sync`)
- `--cloud-sync` — enable cloud sync and install the Zibby MCP

## template {#template}

```bash
zibby template list             # see what's available
zibby template add <name>       # copy template into .zibby/ (overwrites = doubles as update)
```

Templates are starter agent scaffolds. `add` overwrites existing files in place — use it to upgrade an outdated agent helpers block, or to grab a recipe you didn't pick at `init` time.

`zibby template add zibby-workflow-claude` (or `-cursor`, `-codex`) refreshes the per-agent guidance files emitted by this template — the `<!-- zibby-template-version: N -->` markers make the upgrade idempotent.

Options on `add`:
- `--skip-memory` — strip `SKILLS.MEMORY` from copied `execute-live.mjs` (browser-test template only)

## App commands {#app-commands}

`zibby app` manages [Managed App instances](./apps/) — hosted open-source tools (Grafana, Open WebUI, Docmost, OpenHands, and 18 more in the catalog, plus anything you install via [goal-mode](./apps/goal-mode)) with an autonomous agent-ops sidecar. Each verb is keyed by **instance ID** (`a1b2c3d4`-style); `zibby app list` shows IDs alongside display names.

| Command | What it does |
|---|---|
| [`zibby app templates`](#app-templates) | Browse the catalog (grafana, uptime-kuma, open-webui, openhands, docmost, …) |
| [`zibby app list`](#app-list) | List deployed instances under your account |
| [`zibby app deploy <appType>`](#app-deploy) | Deploy an app from the catalog, or `--goal "..."` for free-form goal-mode |
| [`zibby app status <id>`](#app-status) | One-screen summary: status, resources, URL, last agent-ops run |
| [`zibby app logs <id>`](#app-logs) | Logs from app + agent-ops, with `-t` tail mode; `--service <name>` to scope multi-service |
| [`zibby app upgrade <id>`](#app-upgrade) | Zero-downtime roll to the catalog's current image |
| [`zibby app restart <id>`](#app-restart) | Force ECS service to roll the running tasks |
| [`zibby app set-auth <id>`](#app-set-auth) | Add / rotate / remove the optional Caddy auth proxy |
| [`zibby app update-credential <id>`](#app-update-credential) | Rotate a BYOK credential and restart |
| [`zibby app destroy <id>`](#app-destroy) | Tear down service + volume (data permanently deleted) |

### app templates {#app-templates}

```bash
zibby app templates
```

Print the live catalog — id, display name, tier, hourly rate, one-line description.

### app list {#app-list}

```bash
zibby app list                        # all instances under your account
zibby app list --project <id>         # scope to one project
```

Options:
- `--project <id>` — project to scope the listing to (default: all projects your account owns)
- `--api-key <key>` — API key (or `ZIBBY_API_KEY` env)

### app deploy {#app-deploy}

```bash
zibby app deploy grafana --project <project-id> --name metrics
zibby app deploy --goal "Install n8n on port 5678 with sqlite persistence" --project <id> --name automations
```

Two modes:

- **Catalog**: pass an `appType` (slug from `zibby app templates`).
- **Goal-mode**: pass `--goal "<install description>"` instead of `appType`. Claude writes the install script and agent-ops runs it under supervision inside the container. See [Goal-mode deploys](./apps/goal-mode).

Options:

- `--project <id>` — interactive picker if omitted
- `--name <name>` — display name in the dashboard / `zibby app list` (defaults to `appType`)
- `--provider <name>` — `claude` (default) or `codex` — picks which BYOK credential to inject
- `--arch <name>` — `x86_64` or `arm64` (defaults to catalog's first listed arch)
- `--api-key <key>` — Zibby API key (or `ZIBBY_API_KEY` env)
- `--cpu <units>` — Fargate CPU units (e.g. `1024` for 1 vCPU; default from tier)
- `--memory <mb>` — Fargate memory in MB (e.g. `2048` for 2 GB; default from tier)

Goal-mode + planner options (used by `--goal` deploys and cheatsheet-mode catalog entries):

- `--goal "<text>"` — free-form install description. Mutually exclusive with `[appType]`.
- `--model <name>` — Claude model identifier. E.g. `claude-sonnet-4-6` (default), `claude-opus-4-8`, `claude-haiku-4-5-20251001`. Overrides the agent-ops bootstrap default.
- `--anthropic-token <token>` — per-deploy Claude credential override. An Anthropic API key (`sk-ant-api03-…`, from [console.anthropic.com](https://console.anthropic.com/settings/keys)). SENSITIVE. Also accepts `ZIBBY_ANTHROPIC_TOKEN` env. Falls back to workspace credentials if absent.
- `--max-turns <n>` — Claude subprocess max turns, 1-200 (default 25). Bump for heavy installs.
- `--timeout-min <n>` — bootstrap wall-clock minutes, 1-120 (default 30).

Auth proxy options (opts into a Caddy sidecar on port 8888 — see [Auth proxy](./apps/auth)):

- `--auth-type <kind>` — `basic`, `token`, or `none` (default `none`).
- `--auth-user <name>` — required for `--auth-type basic`. Printable ASCII, no spaces, 1-64 chars.
- `--auth-password <pass>` — required for `--auth-type basic`. SENSITIVE. 8-256 chars. Also accepts `ZIBBY_APP_AUTH_PASSWORD` env.
- `--auth-token <token>` — optional for `--auth-type token`. If omitted, backend auto-generates a 32-char URL-safe token and returns it ONCE on deploy. Also accepts `ZIBBY_APP_AUTH_TOKEN` env.

Returns an `instanceId` and the public URL. If `--auth-type token` was used without `--auth-token`, the generated token is included in the response and shown ONCE — save it then, you can't retrieve it later.

### app status {#app-status}

```bash
zibby app status a1b2c3d4
```

Prints status, resources, hourly rate, public URL, and the latest agent-ops run summary.

### app logs {#app-logs}

```bash
zibby app logs a1b2c3d4                       # last 200 lines
zibby app logs a1b2c3d4 -t                    # tail mode, polls every 3s, SSE auto-reconnect
zibby app logs a1b2c3d4 --lines 1000          # bigger window
zibby app logs a1b2c3d4 --json                # raw JSON lines
zibby app logs a1b2c3d4 --verbose             # full line including JSON body
zibby app logs a1b2c3d4 -t --service db       # scope to one container in a multi-service entry
```

Logs cover **all** containers in the task — the app(s), the agent-ops sidecar, and (if enabled) the Caddy auth proxy — prefixed by source. Default output is the parsed `<time>  <msg>` summary.

Options:

- `-t, --follow` — live tail
- `--lines <n>` — initial window size (default 200)
- `--json` / `--verbose` — output format toggles
- `--service <name>` — scope to one container by name (e.g. `db` on docmost). Useful for multi-service catalog entries.

### app upgrade {#app-upgrade}

```bash
zibby app upgrade a1b2c3d4
zibby app upgrade a1b2c3d4 --version 0.1.16   # pin a specific agent-ops version
zibby app upgrade a1b2c3d4 --yes              # skip confirmation
```

Registers a new task definition revision, updates the ECS service, and lets the ALB drain old tasks before they exit. Zero-downtime for HTTP traffic.

### app restart {#app-restart}

```bash
zibby app restart a1b2c3d4
```

Forces the ECS service to roll the current tasks without changing the task definition. Useful when the app gets wedged on a stuck connection.

### app set-auth {#app-set-auth}

Add, rotate, or remove the [Caddy auth proxy](./apps/auth) on an existing instance.

```bash
# Add basic auth to a previously-unauthenticated instance
zibby app set-auth a1b2c3d4 --auth-type basic --auth-user admin --auth-password 'S0me-long-passphrase!'

# Rotate just the password (basic auth must already be on)
zibby app set-auth a1b2c3d4 --auth-password 'N3w-passphrase-2026!'

# Switch from basic to token auth (caller-supplied)
zibby app set-auth a1b2c3d4 --auth-type token --auth-token "$(cat ~/.secrets/bearer.txt)"

# Switch to token auth with a freshly-generated token (returned ONCE in response)
zibby app set-auth a1b2c3d4 --auth-type token

# Strip auth entirely — Caddy container is removed; ALB routes straight to the app
zibby app set-auth a1b2c3d4 --off
```

PATCH semantics: omitted flags preserve current state. Triggers an ECS rolling task replace (~60-90s); the app container keeps its EFS data, only the proxy config / container set changes.

Options:

- `--auth-type <kind>` — `basic`, `token`, or `none`
- `--auth-user <name>` — required when setting `--auth-type basic`
- `--auth-password <pass>` — set / rotate the basic-auth password. Also accepts `ZIBBY_APP_AUTH_PASSWORD` env.
- `--auth-token <token>` — set / rotate the bearer token. If `--auth-type token` is set without this flag, backend generates a 32-char URL-safe token and returns it once. Also accepts `ZIBBY_APP_AUTH_TOKEN` env.
- `--off` — remove auth entirely. Equivalent to `--auth-type none`.
- `--yes` — skip confirmation prompt.

### app update-credential {#app-update-credential}

```bash
zibby app update-credential a1b2c3d4
```

Picks up whatever's currently in your workspace credentials and rolls the task with the new secret env. EFS data is preserved; the task restarts in ~30s. Used by BYOK apps (e.g. Open WebUI pointing at Anthropic via your own key).

### app destroy {#app-destroy}

```bash
zibby app destroy a1b2c3d4               # interactive confirm
zibby app destroy a1b2c3d4 --yes         # skip the confirmation prompt
```

Drains the ECS service, deletes the task definition revision, removes the ALB listener rule + target group, releases the EFS access point (**destroying the volume data permanently**), and stops the billing meter immediately. No soft delete.

## Environment variables

| Var | Purpose |
|---|---|
| `ZIBBY_API_KEY` | API key for non-interactive auth (CI). Preferred over saved session. |
| `ZIBBY_PROJECT_ID` | Default project for commands that take `--project` |
| `AGENT_TYPE` | Default agent strategy when no per-node override and no project default |
| `ZIBBY_DEPLOY_VERBOSE=1` | Same as `--verbose` on `agent deploy` |
| `ZIBBY_SESSION_LOG=1` | Re-enable the diagnostic `[zibby:session]` log line in run output |
| `ZIBBY_RUN_DIAG=1` | Cloud runtime: dump per-copy `agent-workflow` registry state |
| `ZIBBY_DEBUG=true` | Verbose debug logs from the framework |

## Legacy aliases

These still work and route to the same handlers, but new code should use the `zibby agent <verb>` form. The `zibby workflow <verb>` namespace also remains a full alias for `zibby agent <verb>`:

| Legacy | Canonical |
|---|---|
| `zibby g workflow <name>` | `zibby agent new <name>` |
| `zibby start <name>` | `zibby agent start <name>` |
| `zibby run <name>` | `zibby agent run <name>` |
| `zibby deploy [name]` | `zibby agent deploy [name]` |
| `zibby trigger <uuid>` | `zibby agent trigger <uuid>` |
| `zibby logs <uuid>` | `zibby agent logs <uuid>` |