Back to docs

Getting Started

Set up Local CLI checks first, then layer in Occhio Cloud flows and hosted PR reviews.

Prerequisites

  • Node.js 20+ and npm 10+
  • A GitHub repository with a web app
  • A staging/preview URL for your app
  • Supabase + GitHub auth configured for dashboard login

Step 1: Install Local CLI + Skill

Local checks are free and run fully on your machine.

curl -fsSL https://occhio.build/install/skill | bash
curl -fsSL https://occhio.build/install | bash

occhio init
occhio scan

occhio run is deprecated in the local CLI. Use occhio scan for local static checks.

Step 2: Connect a Repository

In dashboard connect flow, pick a GitHub repo, set the base URL, and run quick setup.

  1. Go to /dashboard/connect and authorize GitHub if prompted.
  2. Select repository and base URL.
  3. Run one-click setup to add .occhio/config.yaml and .github/workflows/occhio.yml.
  4. Add OCCHIO_TOKEN in repository secrets for hosted Analyze API usage.

Step 3: Add Flow Tests (Cloud)

Flow authoring lives in Dashboard → repository → Flows. Use auto-detect, natural-language, or code mode to generate Playwright tests using createOcchio(page) and step capture.

import { test, expect } from '@playwright/test';
import { createOcchio } from '@occhio/playwright';

test('Checkout flow', async ({ page }) => {
  const occhio = createOcchio(page);
  occhio.startFlow('Checkout flow');

  await page.goto('/checkout');
  await occhio.captureStep('Opened checkout');

  const result = await occhio.endFlow();
  expect(result.steps.length).toBeGreaterThan(0);
});

Step 4: Enable Hosted PR Reviews

Hosted review ingestion uses POST /api/v1/analyze with bearer token (OCCHIO_TOKEN). This endpoint is plan-gated: free plan has 0 hosted PR reviews, Pro has 300/month.

See API Reference for the exact request/response schema and error behavior.