@zibby/cli 0.1.90 → 0.2.0

package/README.md

@@ -1,926 +1,172 @@
 # @zibby/cli
 
-Command-line interface for Zibby Test Automation with Rails-like generators.
+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)
 
 ## Installation
 
 ```bash
-# Global installation
+# Global
 npm install -g @zibby/cli
+zibby --version
 
-# Or use npx
-npx @zibby/cli init my-project
+# Or via npx (no install)
+npx @zibby/cli workflow new my-pipeline
 ```
 
----
+Requires Node.js ≥ 18.
 
 ## Authentication
 
-Zibby CLI requires **two-layer authentication** for cloud uploads:
-
-### Setup Options
-
-**Option 1: Local Development (Interactive)**
 ```bash
-# Step 1: Login with OAuth
+# Interactive login (local dev) — opens browser, saves to ~/.zibby/config.json
 zibby login
-# Opens browser → Login → Saves to ~/.zibby/config.json
-
-# Step 2: Set project token in .env
-# ZIBBY_API_KEY=zby_xxx
-```
-
-**Option 2: CI/CD (Personal Access Token)**
-```bash
-# Step 1: Generate token at https://zibby.app/settings/tokens
 
-# Step 2: Set environment variables
+# CI/CD — personal access token (no browser)
 export ZIBBY_USER_TOKEN=zby_pat_xxxxx
-export ZIBBY_PROJECT_ID=zby_xxxxx
-
-# Step 3: Run tests
-zibby test tests/**/*.spec.js
-```
-
-### Running Tests with Cloud Sync
-
-```bash
-# Both project token + user token are required
-zibby test test.spec.js --sync
-
-# Or with explicit project override
-zibby test test.spec.js --project zby_xxx --sync
-```
-
-**Backend validates:**
-- ✅ Project token is valid (`zby_xxx`)
-- ✅ User token is valid (JWT from `zibby login` OR PAT from env var)
-- ✅ User is a member of the project
-
-### Authentication Commands
-
-```bash
-# Interactive login (local development)
-zibby login
-
-# Check current status
-zibby status
-
-# Logout (clears session)
-zibby logout
-```
-
-### Personal Access Tokens (CI/CD)
-
-For automated pipelines, use Personal Access Tokens:
-
-1. **Generate token:** https://zibby.app/settings/tokens
-2. **Add to CI secrets:**
-   ```yaml
-   # GitHub Actions
-   env:
-     ZIBBY_USER_TOKEN: ${{ secrets.ZIBBY_USER_TOKEN }}
-     ZIBBY_PROJECT_ID: zby_xxxxx
-   ```
-3. **Run tests:**
-   ```bash
-   npm install -g @zibby/cli
-   zibby test tests/**/*.spec.js
-   ```
-
-**Token features:**
-- 📅 Configurable expiration (30/60/90 days, or never)
-- 🔄 Revoke anytime from dashboard
-- 📊 Track last used timestamp
-- 🔐 Secure: hashed storage, shown once
-
-### Benefits of Two-Layer Auth
-
-| Benefit | Description |
-|---------|-------------|
-| 🔒 **Enhanced Security** | Both project token AND user token required |
-| 📊 **Audit Trail** | Tracks WHO uploaded each test execution |
-| 👥 **Team Access Control** | Revoke users without rotating project token |
-| 🚫 **Project Membership** | Can't upload to projects you're not a member of |
-| 🤖 **CI/CD Ready** | Personal Access Tokens for automation |
-
----
-
-## Commands
-
-### `zibby init` - Project Generator
-
-Initialize a new test automation project (like `rails new`):
-
-```bash
-# Create new project
-zibby init my-tests
-
-# Or initialize in current directory
-zibby init
-
-# Options
-zibby init my-tests --agent=cursor --no-cloud --skip-install
-```
-
-**What it does:**
-- ✅ Creates project structure
-- ✅ Generates `.zibby.config.js`
-- ✅ Generates `.env.example`
-- ✅ Creates example test specs
-- ✅ Installs dependencies
-- ✅ Installs Playwright browsers
-- ✅ Generates README
-
-### `zibby test` - Run Test Specification
-
-Execute a test specification:
-
-```bash
-# Basic usage
-zibby test test-specs/auth/login.txt
-
-# With options
-zibby test test-specs/auth/login.txt --agent=cursor --headless
-
-# Open results in browser after completion
-zibby test test-specs/auth/login.txt --project zby_xxx --collection "My Tests" --open
-
-# For CI/CD
-zibby test test-specs/auth/login.txt --agent=cursor --auto-approve --headless
-```
-
-**Options:**
-- `--agent <type>` - Agent to use (claude, cursor)
-- `--headless` - Run browser in headless mode
-- `--config <path>` - Path to config file (default: `.zibby.config.js`)
-- `--auto-approve` - Auto-approve MCP tools for CI/CD
-- `-o, --open` - Open test results in browser after upload completes
-- `--project <id>` - Project API key for cloud sync (or use ZIBBY_API_KEY env)
-- `--collection <name>` - Collection to upload to
-- `--sync` / `--no-sync` - Force enable/disable cloud sync
-
-### `zibby video` - Organize Test Videos
-
-Move test videos next to their test files:
-
-```bash
-zibby video
-```
-
-**Before:**
-```
-test-results/auth-login-Login-Functionality-chromium/video.webm
+zibby workflow trigger <uuid>
 ```
 
-**After:**
-```
-tests/auth/login.spec.webm
-```
+Generate a PAT at https://zibby.app/settings/tokens.
 
-### `zibby ci-setup` - CI/CD Setup
-
-Setup Cursor Agent for CI/CD:
+## Workflow lifecycle
 
 ```bash
-# Patch cursor-agent for auto-approval
-zibby ci-setup
-
-# Get approval keys
-zibby ci-setup --get-keys
-
-# Save approval keys to project
-zibby ci-setup --get-keys --save
-```
-
-## Generated Project Structure
-
-When you run `zibby init`, it creates:
-
-```
-my-project/
-├── .zibby.config.js          # Configuration (50 lines)
-├── .env.example               # API key templates
-├── .gitignore                 # Proper ignores
-├── package.json               # With zibby dependencies
-├── playwright.config.js       # Auto-configured
-├── README.md                  # Full instructions
-├── test-specs/                # Test specifications
-│   └── examples/
-│       └── google-search.txt
-├── tests/                     # Generated tests (created on first run)
-└── test-results/              # Test artifacts
-```
-
-## Configuration
-
-The `.zibby.config.js` file:
-
-```javascript
-export default {
-  agent: {
-    provider: 'claude',  // or 'cursor'
-    
-    claude: {
-      model: 'claude-sonnet-4-20250514',
-      maxTokens: 4096,
-    },
-  },
-
-  paths: {
-    specs: 'test-specs',
-    generated: 'tests',
-  },
-
-  context: {
-    discovery: {
-      global: 'CONTEXT.md',
-      pathBased: 'test-specs/{segment}/CONTEXT.md',
-      env: `env-${process.env.ENV || 'local'}.js`,
-    }
-  },
-
-  // Video recording (affects playwright.config.js generation)
-  video: 'on',  // Options: 'off', 'on', 'retain-on-failure', 'on-first-retry'
-
-  // Browser viewport size for video recording and testing
-  // Default: 1280x720 (works well on most screens)
-  // For larger displays: { width: 1920, height: 1080 }
-  // For mobile testing: { width: 375, height: 667 } (iPhone SE)
-  viewport: { width: 1280, height: 720 },
-
-  // Playwright artifacts (screenshots, traces, videos)
-  // Set to false to disable, or a path like 'test-results/playwright-artifacts' to enable
-  playwrightArtifacts: false,
-
-  // Cloud sync - auto-upload test results & videos
-  cloudSync: false
-};
+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
 ```
 
-## Examples
+`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.
 
-### Generate Project and Run Test
+## Quick start (60 seconds)
 
 ```bash
-# Generate project
-zibby init my-tests
-cd my-tests
-
-# Add API key
-cp .env.example .env
-# Edit .env: ANTHROPIC_API_KEY=sk-ant-...
-
-# Run example test
-zibby test test-specs/examples/google-search.txt
-
-# Run with cloud sync and open results
-zibby test test-specs/examples/google-search.txt \
-  --project zby_xxx \
-  --collection "My Tests" \
-  --open
+# 1. Scaffold
+npx @zibby/cli workflow new my-pipeline
+cd .zibby/workflows/my-pipeline
 
-# Organize videos
-zibby video
+# 2. Edit graph.mjs — add nodes, set agents
+# 3. Run locally
+npx @zibby/cli workflow start my-pipeline
 
-# Run generated test
-npx playwright test tests/examples/google-search.spec.js
+# 4. Deploy + trigger remotely
+npx @zibby/cli login
+npx @zibby/cli workflow deploy my-pipeline
+npx @zibby/cli workflow trigger <returned-uuid>
+npx @zibby/cli workflow logs <returned-uuid> -t
 ```
 
-### CI/CD Usage
+## CI/CD trigger
 
-#### With Claude Agent (Simple)
+Every deployed workflow exposes an HTTP API:
 
 ```bash
-# Just set API key in CI environment
-export ANTHROPIC_API_KEY=sk-ant-...
-
-# Run tests
-zibby test test-specs/auth/login.txt --agent=claude --headless
+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"}}'
 ```
 
-#### With Cursor Agent (Requires Setup)
-
-```bash
-# 1. Install cursor-agent (in CI container/runner)
-curl https://cursor.com/install -fsS | bash
-
-# 2. Set Cursor API key
-export CURSOR_API_KEY=your-cursor-token-here
-
-# 3. Patch cursor-agent for auto-approval (one-time setup)
-zibby ci-setup
-
-# 4. Get and save approval keys (optional, for faster subsequent runs)
-zibby ci-setup --get-keys --save
-
-# 5. Run tests
-zibby test test-specs/auth/login.txt \
-  --agent=cursor \
-  --auto-approve \
-  --headless
-
-# 6. Upload results to cloud (optional)
-zibby test test-specs/auth/login.txt \
-  --agent=cursor \
-  --auto-approve \
-  --headless \
-  --sync \
-  --collection="CI Tests"
-```
-
-**GitHub Actions Example:**
+GitHub Actions:
 
 ```yaml
-name: Test with Cursor Agent
-
-on: [push]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: '18'
-      
-      - name: Install dependencies
-        run: npm install
-      
-      - name: Install cursor-agent
-        run: curl https://cursor.com/install -fsS | bash
-      
-      - name: Setup Cursor Agent for CI
-        run: npx zibby ci-setup
-        env:
-          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
-      
-      - name: Run tests
-        run: |
-          npx zibby test test-specs/auth/login.txt \
-            --agent=cursor \
-            --auto-approve \
-            --headless \
-            --sync
-        env:
-          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
-          ZIBBY_API_KEY: ${{ secrets.ZIBBY_API_KEY }}
-```
-
-## Using the Cursor Agent
-
-The Cursor Agent integrates with the cursor-agent CLI to leverage Cursor's AI capabilities for test generation. This is ideal for teams already using Cursor IDE.
-
-### Setup for Cursor Agent
-
-#### Local Development (with Cursor IDE)
-
-If you have Cursor IDE installed, no additional setup is needed! The CLI will use your stored Cursor credentials automatically.
-
-```bash
-# 1. Initialize project with cursor agent
-zibby init my-tests --agent=cursor
-
-# 2. Run tests
-cd my-tests
-zibby test test-specs/examples/google-search.txt --agent=cursor
-```
-
-#### CI/CD Setup
-
-For CI/CD environments, you need to:
-
-1. **Install cursor-agent CLI:**
-```bash
-curl https://cursor.com/install -fsS | bash
-# or
-npm install -g cursor-agent
-```
-
-2. **Get your Cursor API token:**
-   - Visit https://cursor.com/settings
-   - Copy your API token
-
-3. **Set environment variable:**
-```bash
-export CURSOR_API_KEY=your-cursor-token-here
-```
-
-4. **Patch cursor-agent for auto-approval:**
-```bash
-zibby ci-setup
-```
-
-This patches the cursor-agent binary to automatically approve MCP tool calls, which is required for automated pipelines.
-
-### Cursor Agent Examples
-
-#### Basic Test Generation
-
-```bash
-# Generate test using Cursor Agent
-zibby test test-specs/auth/login.txt --agent=cursor
-
-# With options and auto-open results
-zibby test test-specs/auth/login.txt \
-  --agent=cursor \
-  --headless \
-  --collection="Auth Tests" \
-  --open
-
-# Upload to specific project
-zibby test test-specs/auth/login.txt \
-  --agent=cursor \
-  --project zby_your_project_id \
-  --collection="My Tests" \
-  -o
-```
-
-#### Running in CI/CD
-
-```bash
-# Complete CI/CD workflow
-zibby test test-specs/auth/login.txt \
-  --agent=cursor \
-  --auto-approve \
-  --headless \
-  --sync
-```
-
-#### Running Specific Workflow Nodes
-
-```bash
-# Run only live execution (useful for debugging)
-zibby test test-specs/auth/login.txt \
-  --agent=cursor \
-  --node=execute_live
-
-# Resume from last session and run script generation
-zibby test test-specs/auth/login.txt \
-  --agent=cursor \
-  --node=generate_script \
-  --session=last
-```
-
-#### Using Custom Workflows
-
-```bash
-# Download workflow from cloud
-zibby workflow download --type=run_test --include-default
-
-# Modify .zibby/workflow-run_test.json as needed
-
-# Run with custom workflow
-zibby test test-specs/auth/login.txt \
-  --agent=cursor \
-  --workflow=CustomWorkflow
-```
-
-### Cursor Agent vs Claude Agent
-
-| Feature | Cursor Agent | Claude Agent |
-|---------|--------------|--------------|
-| Setup | Requires cursor-agent CLI | Just API key |
-| Local Dev | Uses IDE credentials | Requires API key |
-| CI/CD | Requires patching + token | Just API key |
-| Speed | Depends on IDE connection | Direct API (faster) |
-| Cost | Uses Cursor subscription | Pay per token |
-| Best For | Teams using Cursor IDE | Pure CLI workflows |
-
-### Approval Keys
-
-Cursor Agent uses MCP tool approval keys to determine which tools can be auto-approved. You can manage these keys:
-
-```bash
-# Get current approval keys
-zibby ci-setup --get-keys
-
-# Save to project
-zibby ci-setup --get-keys --save
-
-# Keys are saved to:
-# - .mcp/approval-keys.json (project-specific)
-# - ~/.cursor-agent/approval-keys.json (global fallback)
-```
-
-### Troubleshooting Cursor Agent
-
-#### "cursor-agent not found"
-
-```bash
-# Install cursor-agent
-curl https://cursor.com/install -fsS | bash
-
-# Verify installation
-cursor-agent --version
-```
-
-#### "CURSOR_API_KEY not set" (CI/CD only)
-
-```bash
-# Get token from https://cursor.com/settings
-export CURSOR_API_KEY=your-token-here
-```
-
-#### "Tool approval required" (CI/CD)
-
-```bash
-# Patch cursor-agent for auto-approval
-zibby ci-setup
-
-# Verify patch
-zibby ci-setup --get-keys
-```
-
-#### Tests hang or timeout
-
-```bash
-# Run in headed mode to see what's happening
-zibby test test-specs/auth/login.txt --agent=cursor
-
-# Check session logs
-ls -la test-results/sessions/
-```
-
-#### MCP connection errors
-
-```bash
-# Ensure Playwright MCP is set up
-zibby setup-playwright --headed
-
-# Check MCP config
-cat .mcp/config.json
-```
-
-## Features
-
-✅ **Interactive Prompts** - Choose agent, MCP, cloud sync
-✅ **Zero Configuration** - Works out of the box
-✅ **Beautiful CLI** - Colorful output with progress indicators
-✅ **CI/CD Ready** - Auto-approval for automated pipelines
-✅ **Video Organization** - Keep videos next to tests
-✅ **Multi-Agent Support** - Claude (API) or Cursor (CLI)
-
-## Environment Variables
-
-### Agent Configuration
-
-```bash
-# ============================================
-# Claude Agent (Anthropic API)
-# ============================================
-ANTHROPIC_API_KEY=sk-ant-...
-# Required: Always
-# Get from: https://console.anthropic.com/
-
-# ============================================
-# Cursor Agent (cursor-agent CLI)
-# ============================================
-CURSOR_API_KEY=your-cursor-token-here
-# Required: Only in CI/CD (not needed locally with Cursor IDE)
-# Get from: https://cursor.com/settings
-# Install cursor-agent: curl https://cursor.com/install -fsS | bash
-
-# ============================================
-# Optional: Cloud Sync
-# ============================================
-ZIBBY_API_KEY=zby_live_...
-# Optional: For uploading test results and videos to Zibby Cloud
-# Get from: https://app.zibby.com/projects (copy project API key)
-
-ZIBBY_PROJECT_ID=proj_...
-# Optional: Specific project ID (auto-detected from API key if not set)
-
-ZIBBY_TENANT_ID=org_...
-# Optional: Organization/tenant ID
+- 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 }}"}'
 ```
 
-### Complete .env.example
+## Project + integrations
 
 ```bash
-# Copy this to .env and fill in your keys
+zibby project list                 # show projects you have access to
+zibby project use <id>             # set active project for subsequent commands
 
-# ===========================================
-# AI AGENT (choose one)
-# ===========================================
-
-# Option 1: Claude Agent (recommended for CI/CD)
-ANTHROPIC_API_KEY=sk-ant-your-key-here
-
-# Option 2: Cursor Agent (for teams using Cursor IDE)
-# Local: Not needed (uses IDE credentials)
-# CI/CD: Required
-# CURSOR_API_KEY=your-cursor-token-here
-
-# ===========================================
-# CLOUD SYNC (optional)
-# ===========================================
-
-# Upload test results to Zibby Cloud
-# ZIBBY_API_KEY=zby_live_your-project-key
-# ZIBBY_PROJECT_ID=proj_your-project-id
-
-# ===========================================
-# ENVIRONMENT (optional)
-# ===========================================
-
-# For environment-specific configs
-# NODE_ENV=development|production|staging
+zibby integrations list            # show connected integrations
+zibby integrations connect github  # OAuth flow for GitHub
+zibby integrations connect gitlab  # token flow for self-hosted GitLab
 ```
 
-## Advanced Cursor Agent Usage
+## Dedicated egress (static IP addon)
 
-### Running Multiple Tests
+For customers behind corporate firewalls. See [docs.zibby.app/cloud/dedicated-egress](https://docs.zibby.app/cloud/dedicated-egress).
 
 ```bash
-# Run all tests in a folder
-for spec in test-specs/auth/*.txt; do
-zibby test "$spec" --agent=cursor --headless --sync
-done
-
-# Or use a workflow system
-zibby workflow download --type=run_test
-# Edit workflow to run multiple specs
-zibby test test-specs/auth/login.txt --workflow=BatchRunner
+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
 ```
 
-### Custom Approval Keys
-
-By default, cursor-agent requires approval for each MCP tool call. For CI/CD, you can configure which tools are auto-approved:
-
-```bash
-# 1. Get current keys
-zibby ci-setup --get-keys
-
-# 2. Edit approval-keys.json
-cat > .mcp/approval-keys.json << 'EOF'
-{
-  "playwright": {
-    "browser_navigate": true,
-    "browser_click": true,
-    "browser_type": true,
-    "browser_screenshot": true,
-    "browser_close": true
-  }
-}
-EOF
-
-# 3. Use in CI
-zibby test test-specs/auth/login.txt --agent=cursor --auto-approve
-```
-
-### Session Management
-
-Cursor Agent creates session folders for each run. You can reuse sessions for debugging:
-
-```bash
-# 1. Run test (creates session folder)
-zibby test test-specs/auth/login.txt --agent=cursor
-
-# Session saved to: test-results/sessions/1709567890/
-
-# 2. View session files
-ls test-results/sessions/1709567890/execute_live/
-# events.json - All MCP tool calls and responses
-# videos/ - Recorded video(s)
-# title.txt - Generated test name
-
-# 3. Resume from specific session
-zibby test test-specs/auth/login.txt \
-  --agent=cursor \
-  --node=generate_script \
-  --session=1709567890
-
-# 4. Or use "last" to resume from most recent
-zibby test test-specs/auth/login.txt \
-  --agent=cursor \
-  --node=generate_script \
-  --session=last
-```
+## Studio (test recipe only today)
 
-### Debugging Cursor Agent
+[Zibby Studio](https://zibby.app/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
-# 1. Run in headed mode (see browser)
-zibby test test-specs/auth/login.txt --agent=cursor
-
-# 2. Check cursor-agent logs
-tail -f ~/.cursor-agent/logs/agent.log
-
-# 3. Inspect MCP tool calls
-cat test-results/sessions/*/execute_live/events.json | jq '.[] | select(.type == "tool_call")'
-
-# 4. Verify MCP setup
-cat .mcp/config.json
-
-# 5. Test MCP connection
-cursor-agent --test-mcp
+zibby studio                       # open Studio
 ```
 
-### Performance Optimization
+For non-test workflows, replay individual nodes from the CLI:
 
 ```bash
-# Use headless mode (faster)
-zibby test test-specs/auth/login.txt --agent=cursor --headless
-
-# Skip video recording
-# Edit .zibby.config.js:
-# video: 'off'
-
-# Run specific nodes only
-zibby test test-specs/auth/login.txt \
-  --agent=cursor \
-  --node=execute_live  # Skip script generation & verification
-
-# Reuse existing session
-zibby test test-specs/auth/login.txt \
-  --agent=cursor \
-  --node=generate_script \
-  --session=last  # No need to execute live again
+zibby workflow start <name> --session <id> --node <name>
 ```
 
-### Best Practices for Cursor Agent
+## Common flags
 
-1. **Local Development**: Use Cursor IDE credentials (no CURSOR_API_KEY needed)
-2. **CI/CD**: Always set CURSOR_API_KEY and patch cursor-agent
-3. **Auto-Approval**: Use `--auto-approve` flag in CI/CD only
-4. **Headless Mode**: Always use `--headless` in CI/CD for performance
-5. **Session Reuse**: Use `--session=last` to debug without re-running
-6. **Cloud Sync**: Use `--sync` to automatically upload results
-7. **Collections**: Use `--collection` to organize tests by feature/module
+| 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 |
 
-### Comparing Agents
+## Environment variables
 
-When to use **Cursor Agent**:
-- ✅ Your team uses Cursor IDE
-- ✅ You want to leverage Cursor's AI capabilities
-- ✅ You're okay with CLI-based execution
-- ✅ You have a Cursor subscription
+### CLI (your machine)
 
-When to use **Claude Agent**:
-- ✅ You want the simplest setup
-- ✅ You prefer direct API access
-- ✅ You need faster execution
-- ✅ You're running in pure CI/CD (no IDE)
+| 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 |
 
-**Recommendation**: Start with Claude Agent for simplicity. Switch to Cursor Agent if your team already uses Cursor IDE and wants to leverage its AI capabilities.
+### Per-workflow (cloud)
 
-## Opening Test Results
+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 `--open` (or `-o`) flag automatically opens test results in your browser after upload completes:
+The fast path: ship a `.env` at deploy time.
 
 ```bash
-# Opens browser to test results page
-zibby test test-specs/auth/login.txt \
-  --project zby_xxx \
-  --collection "My Tests" \
-  --open
-
-# Short form
-zibby test test-specs/auth/login.txt --project zby_xxx -o
+zibby workflow deploy my-pipeline --env .env
 ```
 
-**Environment-aware URLs:**
-- Local: `http://localhost:3000/projects/{projectId}/runs/{executionId}`
-- Staging: `https://app-staging.zibby.app/projects/{projectId}/runs/{executionId}`
-- Production: `https://app.zibby.app/projects/{projectId}/runs/{executionId}`
-
-**Environment configuration:**
-```bash
-# Default: local
-ZIBBY_ENV=local
-
-# Staging
-ZIBBY_ENV=staging
-ZIBBY_STAGING_FRONTEND_URL=https://app-staging.zibby.app
-
-# Production
-ZIBBY_ENV=prod
-ZIBBY_PROD_FRONTEND_URL=https://app.zibby.app
-```
-
-**Note:** The `--open` flag only works when uploading to cloud (requires `--project` or `--sync` flag). It will not open anything for local-only runs.
-
-## Quick Reference - Cursor Agent Commands
+Manage afterward:
 
 ```bash
-# ============================================
-# SETUP
-# ============================================
-
-# Install cursor-agent (CI/CD only)
-curl https://cursor.com/install -fsS | bash
-
-# Patch for CI/CD
-zibby ci-setup
-
-# Get approval keys
-zibby ci-setup --get-keys --save
-
-# Setup Playwright MCP
-zibby setup-playwright --headed
-
-
-# ============================================
-# RUN TESTS
-# ============================================
-
-# Basic run (local)
-zibby test test-specs/auth/login.txt --agent=cursor
-
-# With options and open results
-zibby test test-specs/auth/login.txt \
-  --agent=cursor \
-  --headless \
-  --collection="Auth Tests" \
-  --open
-
-# Quick open with short flag
-zibby test test-specs/auth/login.txt \
-  --project zby_xxx \
-  -o
-
-# CI/CD run
-zibby test test-specs/auth/login.txt \
-  --agent=cursor \
-  --auto-approve \
-  --headless \
-  --sync
-
-
-# ============================================
-# DEBUGGING
-# ============================================
-
-# Run in headed mode (see browser)
-zibby test test-specs/auth/login.txt --agent=cursor
-
-# Run specific node
-zibby test test-specs/auth/login.txt \
-  --agent=cursor \
-  --node=execute_live
-
-# Resume from last session
-zibby test test-specs/auth/login.txt \
-  --agent=cursor \
-  --node=generate_script \
-  --session=last
-
-# Check logs
-tail -f ~/.cursor-agent/logs/agent.log
-cat test-results/sessions/*/execute_live/events.json
-
-
-# ============================================
-# WORKFLOWS
-# ============================================
-
-# Download workflow
-zibby workflow download --type=run_test
-
-# Run with custom workflow
-zibby test test-specs/auth/login.txt \
-  --agent=cursor \
-  --workflow=CustomWorkflow
-
-# List workflows
-zibby workflow list
-
-
-# ============================================
-# ENVIRONMENT SETUP
-# ============================================
-
-# Local development (.env)
-ANTHROPIC_API_KEY=sk-ant-...  # For Claude
-# No CURSOR_API_KEY needed if Cursor IDE installed
-
-# CI/CD (.env or secrets)
-CURSOR_API_KEY=your-token      # Required in CI/CD
-ZIBBY_API_KEY=zby_live_...     # For cloud sync
-ZIBBY_PROJECT_ID=proj_...      # Optional
+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
 ```
 
-## Troubleshooting Reference
-
-| Error | Solution |
-|-------|----------|
-| `cursor-agent not found` | Install: `curl https://cursor.com/install -fsS \| bash` |
-| `CURSOR_API_KEY not set` | Set env var from https://cursor.com/settings |
-| `Tool approval required` | Run `zibby ci-setup` |
-| Tests hang | Run in headed mode to see browser |
-| MCP connection errors | Run `zibby setup-playwright --headed` |
-| Session files missing | Check `test-results/sessions/` folder |
-| Video not uploaded | Ensure `--sync` flag and ZIBBY_API_KEY set |
-| Browser doesn't open with `--open` | Check ZIBBY_ENV and frontend URL settings |
-| `--open` does nothing | Ensure upload succeeded (requires `--project` or `--sync`) |
-| `Not a member of this project` | Run `zibby login` to authenticate as project member |
-| `Invalid user token` | User JWT expired, run `zibby login` again |
+Full reference: [docs.zibby.app/cloud/env-vars](https://docs.zibby.app/cloud/env-vars).
 
 ## License
 
 MIT
-