@diffdeckai/cli

The DiffDeck upload CLI — push Storybook builds and Playwright recordings to DiffDeck from any CI.

It's a small, dependency-light Node/TypeScript CLI. It speaks only HTTP to the DiffDeck ingest API; there's no other runtime dependency (it uses Node's built-in fetch, fs, and zlib).

Install

Requires Node 18+.

# one-off, no install
npx @diffdeckai/cli upload-storybook --help

# or add to your project
npm install --save-dev @diffdeckai/cli

The binary is diffdeck.

Authentication & host

Every command needs a project token, sent as the X-UI-Review-Token header. Provide it with --token or the DIFFDECK_TOKEN environment variable.

The DiffDeck host defaults to https://diffdeck.ai and can be overridden with --host or the DIFFDECK_HOST environment variable (useful for self-hosted/enterprise instances).

export DIFFDECK_TOKEN=ddp_xxxxxxxxxxxxxxxx
export DIFFDECK_HOST=https://diffdeck.ai   # optional

Commands

upload-storybook

Packs a built Storybook directory into a gzip tarball and uploads it for visual review (POST <host>/api/products/ui-review/builds).

diffdeck upload-storybook --dir storybook-static \
  --commit "$GITHUB_SHA" \
  --branch main \
  --message "Fix button padding"

Flag	Description
--dir <path>	Directory of the built Storybook (e.g. storybook-static). Required.
--commit <sha>	Git commit SHA. Required.
--branch <name>	Git branch name. Defaults to the repo's default branch server-side.
--message <text>	Git commit message. Optional.
--default-branch <b>	Repository default branch (from CI). Persisted server-side so PR baselines resolve against it. Optional.
--pr-number <n>	Pull request number (from CI). Persisted server-side so the build deep-links straight to the exact PR. Optional.
--token <token>	Project token. Defaults to $DIFFDECK_TOKEN.
--host <url>	DiffDeck host. Defaults to $DIFFDECK_HOST or https://diffdeck.ai.

Build your Storybook first (npx storybook build produces storybook-static/).

upload-storybook uploads the build only; screenshots are then rendered server-side. Prefer screenshot-storybook below, which renders in CI (no server browser needed) and fails the build if a story can't render.

screenshot-storybook

Renders every story in a built Storybook to PNGs in CI (six variants each: light/dark × phone/tablet/desktop), then uploads the screenshots together with the build (POST <host>/api/products/ui-review/builds). The server does no rendering — it hosts the build for browsing and diffs the screenshots against the baseline.

A render-check runs alongside: if any story fails to render (a thrown error, a non-benign console.error, or Storybook's #sb-errordisplay overlay) the command prints a report, exits non-zero, and uploads nothing — so a broken story fails the CI build.

npm i -D playwright && npx playwright install chromium   # once, in your project
diffdeck screenshot-storybook --dir storybook-static \
  --commit "$GITHUB_SHA" \
  --branch main \
  --message "Fix button padding"

Flag	Description
--dir <path>	Directory of the built Storybook (e.g. storybook-static). Required.
--commit <sha>	Git commit SHA. Required.
--branch <name>	Git branch name. Defaults to the repo's default branch server-side.
--message <text>	Git commit message. Optional.
--default-branch <b>	Repository default branch (from CI). Persisted server-side so PR baselines resolve against it. Optional.
--pr-number <n>	Pull request number (from CI). Persisted server-side so the build deep-links straight to the exact PR. Optional.
--token <token>	Project token. Defaults to $DIFFDECK_TOKEN.
--host <url>	DiffDeck host. Defaults to $DIFFDECK_HOST or https://diffdeck.ai.

Playwright (with browsers) must be installed in the project — it's resolved from your project, not bundled with the CLI, which keeps the CLI dependency-light.

upload-recording

Uploads a single Playwright test recording (video + test metadata) (POST <host>/api/products/ui-review/recordings). Your CI runs Playwright itself; this command just uploads the resulting video.

diffdeck upload-recording --video test-results/home.webm \
  --test "Home page renders" \
  --file "tests/home.spec.ts" \
  --status passed \
  --duration 1840 \
  --retries 0 \
  --commit "$GITHUB_SHA" \
  --branch main

Flag	Description
--video <path>	Recorded video file (.webm/.mp4/…). Required.
--test <title>	Test title.
--file <path>	Test file path.
--test-id <id>	Stable test identifier.
--status <status>	Test status (passed, failed, skipped, …).
--duration <ms>	Test duration in milliseconds.
--retries <n>	Number of retries.
--metadata <json>	Extra metadata as a JSON string.
--branch <name>	Git branch name.
--commit <sha>	Git commit SHA.
--token <token>	Project token. Defaults to $DIFFDECK_TOKEN.
--host <url>	DiffDeck host. Defaults to $DIFFDECK_HOST or https://diffdeck.ai.

Recordings are a separately-priced add-on. If they're not enabled for your repository, the upload is rejected with HTTP 402 and the CLI prints a clear message.

Run diffdeck <command> --help for the full per-command help, and diffdeck --version for the version.

CI examples

GitHub Actions

name: DiffDeck
on: [push]
jobs:
  storybook:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx storybook build -o storybook-static
      - run: npx @diffdeckai/cli upload-storybook
              --dir storybook-static
              --commit "$GITHUB_SHA"
              --branch "${GITHUB_REF_NAME}"
              --message "$(git log -1 --pretty=%s)"
        env:
          DIFFDECK_TOKEN: ${{ secrets.DIFFDECK_TOKEN }}

GitLab CI

diffdeck-storybook:
  image: node:20
  script:
    - npm ci
    - npx storybook build -o storybook-static
    - npx @diffdeckai/cli upload-storybook
        --dir storybook-static
        --commit "$CI_COMMIT_SHA"
        --branch "$CI_COMMIT_REF_NAME"
        --message "$CI_COMMIT_TITLE"
  variables:
    DIFFDECK_TOKEN: $DIFFDECK_TOKEN

CircleCI

version: 2.1
jobs:
  diffdeck:
    docker:
      - image: cimg/node:20.11
    steps:
      - checkout
      - run: npm ci
      - run: npx storybook build -o storybook-static
      - run: >
          npx @diffdeckai/cli upload-storybook
          --dir storybook-static
          --commit "$CIRCLE_SHA1"
          --branch "$CIRCLE_BRANCH"
workflows:
  build:
    jobs:
      - diffdeck:
          context: diffdeck   # provides DIFFDECK_TOKEN

Uploading a recording from CI

# after Playwright runs and produced a video at test-results/home.webm
npx @diffdeckai/cli upload-recording \
  --video test-results/home.webm \
  --test "Home page renders" \
  --file "tests/home.spec.ts" \
  --status passed \
  --commit "$GITHUB_SHA" \
  --branch "$GITHUB_REF_NAME"

Development

npm install
npm run build       # tsc → dist/
npm test            # build + node --test
node dist/cli.js --help

License

MIT