Installation

GitHub App (Easiest)

The fastest way to start catching design drift is to install the Buoy GitHub App from the GitHub Marketplace. It scans every PR automatically — no CLI, no config, no CI setup.

  1. Install from the GitHub Marketplace
  2. Select your repositories
  3. Open a PR — Buoy posts a review with drift issues

See GitHub App docs for details.

CLI Installation

For local scanning, auto-fixing, and project setup, install the Buoy CLI. It can be run directly with npx or installed as a dependency.

Using npx (Recommended)

Run Buoy without installing:

npx ahoybuoy dock

This launches the interactive setup wizard that scans your project and guides you through setup.

To run a quick drift scan:

npx ahoybuoy drift

Installing as a Dev Dependency

For ongoing use, install Buoy in your project:

# npm
npm install --save-dev @buoy-design/cli

# pnpm
pnpm add -D @buoy-design/cli

# yarn
yarn add -D @buoy-design/cli

Then run with npx or add to your package.json scripts:

{
  "scripts": {
    "lint:design": "buoy drift",
    "check:design": "buoy drift check --fail-on critical"
  }
}

Global Installation

Install globally to use buoy anywhere:

npm install -g @buoy-design/cli

Requirements

  • Node.js 18 or higher
  • A frontend codebase (React, Vue, Svelte, Angular, Next.js, Tailwind, or plain CSS/HTML)

Verify Installation

$ buoy --version
0.3.23

$ buoy --help
Usage: buoy [command] [options]

Commands:
  show        Show design system status and health
  drift       Detect, check, and fix design drift
  dock        Dock Buoy into your project
  ahoy        Manage account and integrations

Next Steps