---
sidebar_position: 3
title: Installation
---

# Installation

## Install the CLI

```bash
npm install -g @zibby/cli
```

Verify:

```bash
zibby --version
```

Or use without installing:

```bash
npx @zibby/cli run test.txt --agent cursor
```

## Project Setup (Optional)

`zibby test` works without any project setup — it uses a built-in workflow. To customize:

```bash
cd your-project
zibby init --agent cursor
```

**Options:**

| Flag | Description |
|---|---|
| `--agent <type>` | `cursor` or `claude` |
| `--cloud-sync` | Enable cloud sync and configure API |
| `--headless` | Run browser in headless mode |
| `--headed` | Run browser in headed mode (visible) |
| `--skip-install` | Skip `npm install` |
| `-f, --force` | Overwrite existing config |

This creates:

```
.zibby.config.js           # Project configuration
.zibby/
├── graph.js                # Workflow graph (entry point → nodes → END)
├── nodes/
│   ├── preflight.js        # Extract title + assertions from spec
│   ├── execute-live.js     # AI drives browser
│   └── generate-script.js  # Generate Playwright script
└── result-handler.js       # Save artifacts after execution
```

## Configuration

`.zibby.config.js` in your project root (ESM format):

```javascript
export default {
  agent: {
    cursor: {
      model: 'auto',
    },
    // OR:
    // claude: {
    //   model: 'auto',
    //   maxTokens: 4096,
    // },
  },

  paths: {
    specs: 'test-specs',
    generated: 'tests',
    output: '.zibby/output',
  },

  video: 'on',
  viewport: { width: 1280, height: 720 },
  playwrightArtifacts: true,
  cloudSync: false,
};
```

## Environment Setup

Copy the generated `.env.example` to `.env` and add your keys:

```bash
cp .env.example .env
```

Then edit `.env` with your values:

```bash
# For Cursor agent in CI/CD
CURSOR_API_KEY=your-cursor-api-key

# For Claude agent
ANTHROPIC_API_KEY=sk-ant-...

# For cloud sync (optional)
ZIBBY_API_KEY=zby_your_api_key_here
```

## Playwright Setup

Zibby uses Playwright for browser automation. If you don't have it:

```bash
zibby setup-playwright
```

This configures the Playwright MCP server for Zibby.

## Verify Setup

```bash
echo "Go to example.com and verify the page title" > test.txt
zibby test test.txt --agent cursor
```

You should see a browser open, the AI navigate to example.com, and a Playwright script generated in `tests/`.