---
sidebar_position: 2
title: Getting Started
---

# Getting Started

Get up and running with Zibby in under 5 minutes.

## Prerequisites

- Node.js 18 or later
- [Cursor](https://cursor.com) IDE installed (for `--agent cursor`), **or** an Anthropic API key (for `--agent claude`), **or** OpenAI API key + Codex CLI (for `--agent codex`)

## Option A: Zero Setup (npx)

No install needed — run directly:

```bash
echo "Go to example.com and verify the page title says Example Domain" > test.txt
npx @zibby/cli run test.txt --agent cursor
```

## Option B: Global Install

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

### 1. Create a test spec

Create a plain-text file with your test instructions:

```text title="test-specs/login.txt"
1. Navigate to https://myapp.com/login
2. Enter email: test@example.com
3. Enter password: TestPass123
4. Click the Sign In button
5. Verify the dashboard page loads
6. Verify the user's name appears in the header
```

### 2. Run it

```bash
zibby test test-specs/login.txt --agent cursor
```

You'll see:
- A browser window open
- The AI agent navigate and interact with your app
- A generated Playwright script saved to `tests/`

### 3. Run the generated test

```bash
npx playwright test tests/login.spec.js
```

## Customizing Your Setup (Optional)

If you want to customize the workflow, config, or nodes:

```bash
zibby init --agent cursor
```

This scaffolds:

```
.zibby.config.js          # Project configuration (ESM)
.zibby/
├── graph.js               # Workflow definition (customizable)
├── nodes/                 # Node implementations
│   ├── execute-live.js
│   ├── generate-script.js
│   └── preflight.js
└── result-handler.js      # Post-execution hooks
```

Without `zibby init`, the CLI uses the built-in default workflow automatically.

## Environment Variables

| Variable | When needed |
|---|---|
| `CURSOR_API_KEY` | CI/CD with `--agent cursor` (locally uses Cursor IDE credentials) |
| `ANTHROPIC_API_KEY` | Using `--agent claude` |
| `OPENAI_API_KEY` | Using `--agent codex` |
| `ZIBBY_API_KEY` | Cloud sync (`--sync` flag) |

For local development, add these to a `.env` file in your project root.

## Cloud Sync (Optional)

To upload results to the [Zibby dashboard](https://zibby.app):

1. Create an account at [zibby.app](https://zibby.app)
2. Get your API key from **Project Settings**
3. Add to `.env`: `ZIBBY_API_KEY=zby_your_key_here`
4. Login: `zibby login`
5. Run with sync: `zibby test test-specs/login.txt --sync`

## Next Steps

- [Installation](/installation) — detailed setup and configuration
- [Running Tests](/running-tests) — all run modes and options
- [CLI Reference](/cli-reference) — every command and flag