# @zibby/cli

Command-line interface for **Zibby — the cloud pipeline for Claude Code, Cursor, Codex, and Gemini.** Compose them into structured workflows with Zod-validated handoff between nodes.

📖 **Full docs:** [docs.zibby.app](https://docs.zibby.app) · **Building an agent? Read [Designing agents](https://docs.zibby.app/concepts/designing-agents)** — the 3 core patterns (one agent / many triggers, zero-LLM code nodes that read & write Stores, event-driven).

## Installation

```bash
# Global
npm install -g @zibby/cli
zibby --version

# Or via npx (no install)
npx @zibby/cli agent new my-pipeline
```

Requires Node.js ≥ 18. For UI-test memory features (selector cache, team sync), also install [Dolt](https://www.dolthub.com/) (`brew install dolt`).

## All commands — cheat sheet

| Group | Command | What it does |
|---|---|---|
| **Setup** | `zibby init` | Bootstrap a project (config + credentials only — pass `-t` for a workflow) |
| | `zibby init -t <template>` | Same, plus scaffold a workflow template into `.zibby/` |
| | `zibby login` | Interactive browser login (saves to `~/.zibby/config.json`) |
| | `zibby uninstall` | Remove zibby from this project + globally + Studio + caches |
| **Templates** | `zibby template list` | Show available workflow templates |
| | `zibby template add <name>` | Copy template into `.zibby/` (overwrites — doubles as update) |
| **Workflows** | `zibby agent new <name>` | Scaffold a new workflow under `.zibby/workflows/<name>/` |
| | `zibby agent start <name>` | Run locally with hot reload (add `-w` for watch mode) |
| | `zibby agent run <name>` | One-shot local run (no server) |
| | `zibby agent list` | Show local + deployed workflows |
| | `zibby agent deploy <name>` | Build bundle + upload to cloud |
| | `zibby agent trigger <uuid>` | Trigger a deployed workflow remotely |
| | `zibby agent logs <uuid>` | Fetch logs once (add `-t` to tail live) |
| | `zibby agent download <uuid>` | Pull cloud workflow source locally |
| | `zibby agent delete <uuid>` | Destroy cloud workflow |
| | `zibby agent update <uuid>` | One-shot edit: `--model` / `--mention` / `--triggers` / `--name` / `--max-runtime` |
| | `zibby agent env list/set/unset/push <uuid>` | Manage per-workflow encrypted env vars |
| **Test** | `zibby test <spec.txt>` | Run an AI-driven browser test (requires `browser-test-automation` template) |
| **Chat** | `zibby chat` | Interactive chat agent with cloud sandbox |
| **Memory (UI agent learning DB)** | `zibby memory init` | Initialize the Dolt-backed memory DB (`.zibby/memory/`) |
| | `zibby memory stats` | Show counts: runs, selectors, pages, insights |
| | `zibby memory cost` | Show real LLM token usage from past runs (input/output/cache) |
| | `zibby memory compact` | Prune old data + run Dolt GC |
| | `zibby memory reset --force` | Wipe the memory DB |
| | `zibby memory remote add <url>` | Configure a shared remote (BYO) — `aws://`, `gs://`, `https://`, `file:///` |
| | `zibby memory remote use --hosted` | Switch to Zibby-managed S3 (signed-in users only) |
| | `zibby memory remote info` | Show configured remote |
| | `zibby memory remote remove [name]` | Drop the remote (memory becomes local-only) |
| | `zibby memory pull` | Pull team's latest learnings (auto-runs on test start) |
| | `zibby memory push` | Push local learnings (auto-runs on test pass) |
| **Project** | `zibby project list` | Show projects you have access to |
| **Studio** | `zibby studio` | Open Zibby Studio desktop app (manages projects + integrations via web UI) |
| **Egress** | `zibby deploy --dedicated-ip enable/status/use/disable` | Manage dedicated egress addon |
| **Credentials** | `zibby creds list/sync/remove` | Manage agent API/OAuth credentials in `~/.zibby/config.json` |

## Authentication

```bash
# Interactive login (local dev) — opens browser, saves to ~/.zibby/config.json
zibby login

# CI/CD — personal access token (no browser)
export ZIBBY_USER_TOKEN=zby_pat_xxxxx
zibby agent trigger <uuid>
```

Generate a PAT at https://zibby.dev/settings/tokens.

## Workflow lifecycle

```bash
zibby agent new <name>          # scaffold .zibby/workflows/<name>/
zibby agent start <name>        # run locally with hot reload
zibby agent start <name> -w     # watch mode (re-run on file changes)
zibby agent list                # show local + cloud workflows
zibby agent deploy <name>       # build bundle + upload to cloud
zibby agent trigger <uuid>      # remote trigger (returns job id)
zibby agent logs <uuid>         # fetch logs once
zibby agent logs <uuid> -t      # tail live (auto-reconnect, follow next exec)
zibby agent download <uuid>     # pull cloud workflow source locally
zibby agent delete <uuid>       # destroy cloud workflow
```

`agent deploy` also ships your `.zibby.config.mjs` to cloud (resolved locally → `zibby.config.json` inside the bundle), so per-node `models` overrides, the `agent` block, and other declarative knobs work the same in cloud as locally.

## Quick start (60 seconds)

```bash
# 1. Bootstrap a project — bare init, no workflow scaffolding
zibby init                                    # config + credentials only
# Or, init AND scaffold a workflow:
zibby init -t browser-test-automation         # for `zibby test`
# (See `zibby template list` for available templates.)

# 2. (For workflows) scaffold a custom one
zibby agent new my-pipeline
cd .zibby/workflows/my-pipeline

# 3. Edit graph.mjs — add nodes, set agents
# 4. Run locally
zibby agent start my-pipeline

# 5. Deploy + trigger remotely
zibby login
zibby agent deploy my-pipeline
zibby agent trigger <returned-uuid>
zibby agent logs <returned-uuid> -t
```

## Templates

`zibby init` is bare by default — it sets up `.zibby.config.mjs`, credentials, and a local memory DB, but doesn't scaffold any workflow. Templates are opt-in.

```bash
zibby template list                            # see available templates
zibby template add browser-test-automation     # add later
zibby init -t browser-test-automation          # or do both at once
```

Currently shipping:
- `browser-test-automation` — full `zibby test` workflow (preflight → live execution → script generation)

`template add` overwrites existing files — re-run after `npm update @zibby/core` to refresh.

## Memory & team sync

UI agent memory: a local-first Dolt DB that learns selectors, page models, and navigation flows from every test run. Used today by `zibby test`; designed to power any agent that drives a UI.

```bash
zibby memory init                          # create .zibby/memory/.dolt
zibby memory stats                         # see what's been learned
zibby memory cost                          # real LLM token spend per spec / per domain
```

### Team sync — three modes

```bash
# Mode A: local-only (default)
# No setup. Memory grows on your machine, never syncs.

# Mode B: BYO remote (your S3/GCS/DoltHub)
zibby memory remote add aws://[my-bucket]team/proj/main
zibby memory remote add gs://my-bucket/zibby
zibby memory remote add https://doltremoteapi.dolthub.com/team/repo
zibby memory remote add file:///shared/zibby-memory          # NFS / iCloud / Dropbox

# Mode C: Zibby-hosted (signed-in users only — we manage the bucket)
zibby login
zibby memory remote use --hosted
```

Once configured, every test run auto-pulls the team's latest learnings before, and auto-pushes after on success. No manual sync needed.

### Declarative team setup via `.zibby.config.mjs`

Commit the remote URL so teammates cloning the repo auto-configure on `zibby init`:

```js
// .zibby.config.mjs
export default {
  // ...
  memorySync: {
    remote: 'hosted',                          // or 'aws://...' or null
  },
};
```

When set, `zibby init` automatically wires up the remote on first run (asks the user to `zibby login` if `'hosted'` is configured but they haven't signed in yet — never blocks init).

## CI/CD trigger

Every deployed workflow exposes an HTTP API:

```bash
curl -X POST https://api.zibby.app/v1/workflows/<uuid>/trigger \
  -H "Authorization: Bearer $ZIBBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"ticket": "BUG-123"}}'
```

GitHub Actions:

```yaml
- name: Trigger Zibby workflow
  env:
    ZIBBY_USER_TOKEN: ${{ secrets.ZIBBY_USER_TOKEN }}
  run: |
    npx @zibby/cli agent trigger ${{ vars.ZIBBY_WORKFLOW_UUID }} \
      --input '{"pr": "${{ github.event.pull_request.number }}"}'
```

## Project + integrations

```bash
zibby project list                 # show projects you have access to
```

Active project selection and integrations (GitHub / GitLab / Slack / Jira / etc.) are managed via [Zibby Studio](https://zibby.dev/studio) — the desktop app handles OAuth flows + per-project active state. Most CLI commands accept `--project <id>` for one-off overrides.

## Dedicated egress (static IP addon)

For customers behind corporate firewalls. See [docs.zibby.app/cloud/dedicated-egress](https://docs.zibby.app/cloud/dedicated-egress).

```bash
zibby deploy --dedicated-ip enable                          # provision (paid, $50/mo)
zibby deploy --dedicated-ip status                          # show your static IP
zibby deploy --dedicated-ip use --project <id>              # opt project in
zibby deploy --dedicated-ip disable                         # cancel at end of billing period
```

## Studio (test recipe only today)

[Zibby Studio](https://zibby.dev/studio) is the desktop UI for the test recipe — visualise live + past test runs, stop a workflow from a button. Broader workflow support is on the roadmap.

```bash
zibby studio                       # open Studio
```

For non-test workflows, replay individual nodes from the CLI:

```bash
zibby agent start <name> --session <id> --node <name>
```

## Common flags

| Flag | What it does |
|---|---|
| `--project <id>` | Override the active project for this command |
| `--input '<json>'` | Pass JSON input to a triggered workflow |
| `-t, --tail` | Follow logs live (for `agent logs`) |
| `-w, --watch` | Re-run on file changes (for `agent start`) |
| `--dedicated-ip` | Modify the dedicated-egress addon (`enable`, `status`, `use`, `disable`) |
| `--debug` | Verbose CLI output for troubleshooting |

## Environment variables

### CLI (your machine)

| Var | Purpose |
|---|---|
| `ZIBBY_USER_TOKEN` | PAT for CI/CD (preferred over `~/.zibby/config.json`) |
| `ZIBBY_API_KEY` | Project-scoped key for triggering workflows |
| `ZIBBY_DEFAULT_PROJECT` | Default `--project` value |
| `ANTHROPIC_API_KEY` / `CURSOR_API_KEY` / `OPENAI_API_KEY` / `GOOGLE_API_KEY` | Per-agent keys for local execution |
| `ZIBBY_DEBUG=1` | Verbose CLI output |

### Per-workflow (cloud)

Each deployed workflow has its own encrypted env-var bag — set per-workflow agent keys (different `ANTHROPIC_API_KEY` per pipeline), workflow-specific `DATABASE_URL`s, etc. Workflow env wins over project secrets on conflict.

The fast path: ship a `.env` at deploy time.

```bash
zibby agent deploy my-pipeline --env .env
```

Manage afterward:

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

Full reference: [docs.zibby.app/cloud/env-vars](https://docs.zibby.app/cloud/env-vars).

## License

Proprietary — Copyright (c) 2026 Zibby Labs. All rights reserved.
Unauthorized copying, distribution, or use is prohibited.