@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

Installation

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

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

Requires Node.js ≥ 18. For UI-test memory features (selector cache, team sync), also install Dolt (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 workflow new <name> | Scaffold a new workflow under .zibby/workflows/<name>/ | | | zibby workflow start <name> | Run locally with hot reload (add -w for watch mode) | | | zibby workflow run <name> | One-shot local run (no server) | | | zibby workflow list | Show local + deployed workflows | | | zibby workflow deploy <name> | Build bundle + upload to cloud | | | zibby workflow trigger <uuid> | Trigger a deployed workflow remotely | | | zibby workflow logs <uuid> | Fetch logs once (add -t to tail live) | | | zibby workflow download <uuid> | Pull cloud workflow source locally | | | zibby workflow delete <uuid> | Destroy cloud workflow | | | zibby workflow 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

# 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 workflow trigger <uuid>

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

Workflow lifecycle

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

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

# 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 workflow new my-pipeline
cd .zibby/workflows/my-pipeline

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

# 5. Deploy + trigger remotely
zibby login
zibby workflow deploy my-pipeline
zibby workflow trigger <returned-uuid>
zibby workflow 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.

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.

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

# 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:

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

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:

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

Project + integrations

zibby project list                 # show projects you have access to

Active project selection and integrations (GitHub / GitLab / Slack / Jira / etc.) are managed via Zibby 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.

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

zibby studio                       # open Studio

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

zibby workflow 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 workflow logs) | | -w, --watch | Re-run on file changes (for workflow 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_URLs, etc. Workflow env wins over project secrets on conflict.

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

zibby workflow deploy my-pipeline --env .env

Manage afterward:

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

Full reference: docs.zibby.app/cloud/env-vars.

License

MIT