@usesidekick/cli

Command-line tool for integrating and managing Sidekick in Next.js applications. Analyzes your app, generates AI-powered override modules, and scaffolds the full integration in one command.

Quick Start

npx @usesidekick/cli init

This single command will:

1. Install @usesidekick/react and build plugins
2. Configure .babelrc with the Sidekick JSX runtime
3. Add webpack aliases to next.config.js
4. Create a catch-all API route (api/sidekick/[...action]/) with JSON file storage
5. Add SidekickBootstrap to your app layout
6. Analyze your components and generate schema.json

After init, add your API key and start developing:

# .env.local
ANTHROPIC_API_KEY=your_api_key

npm run dev

Overrides are stored locally in .sidekick/overrides.json — no database setup required.

Using Postgres Instead

For production deployments (e.g. Vercel) where the filesystem is read-only, use the --postgres flag to set up Drizzle + Neon:

npx @usesidekick/cli init --postgres

This will additionally:

• Install drizzle-orm, @neondatabase/serverless, and drizzle-kit
• Create a database schema and connection (lib/db/)
• Create drizzle.config.ts
• Generate an API route using createDrizzleStorage

After init with --postgres:

# .env.local
DATABASE_URL=your_neon_database_url
ANTHROPIC_API_KEY=your_api_key

npx drizzle-kit push
npm run dev

Commands

sidekick init

Initialize Sidekick in an existing Next.js project.

sidekick init [options]

| Option | Default | Description | |--------|---------|-------------| | -d, --dir <path> | . | Target project directory | | --postgres | false | Use Drizzle + Neon Postgres instead of JSON file storage |

Detects automatically: package manager (npm/yarn/pnpm), Next.js version, TypeScript, src/app vs app directory structure. Skips already-installed dependencies and already-configured files. Creates backups before modifying existing configs.

sidekick analyze

Analyze your app's components, extension points, data models, and design system to generate a schema.json that powers AI override generation.

sidekick analyze [options]

| Option | Default | Description | |--------|---------|-------------| | -d, --dir <path> | . | Target directory to analyze | | -o, --output <path> | ./sidekick/schema.json | Output path for schema |

sidekick generate

Generate an override module from a natural language description using Claude.

sidekick generate <request> [options]

| Option | Default | Description | |--------|---------|-------------| | -s, --schema <path> | ./sidekick/schema.json | Path to schema.json | | -o, --output <path> | ./sidekick/overrides | Output directory for generated overrides | | -k, --api-key <key> | ANTHROPIC_API_KEY env var | Anthropic API key |

Example:

sidekick generate "Add a purple banner above the task board that says 'Beta'"

The generated override is validated against the SDK's safety rules (no DOM access, no eval, only @usesidekick/react and react imports allowed).

sidekick validate

Validate an override module file for correctness and safety.

sidekick validate <file>

Checks for:

• Valid JavaScript/TypeScript syntax
• Forbidden APIs (document, window, eval, fetch, etc.)
• Import restrictions (only @usesidekick/react and react)
• Required createOverride export

What init Creates

Default (JSON file storage)

your-app/
  .babelrc                              # JSX runtime config
  next.config.js                        # Webpack aliases (modified)
  src/
    components/
      SidekickBootstrap.tsx             # Provider + Panel wrapper
    app/
      layout.tsx                        # Modified to include SidekickBootstrap
      api/sidekick/[...action]/
        route.ts                        # Handler with JSON file storage
    .sidekick/
      schema.json                       # App analysis output
      overrides.json                    # Override data (auto-created on first request)

With --postgres

your-app/
  .babelrc                              # JSX runtime config
  next.config.js                        # Webpack aliases (modified)
  drizzle.config.ts                     # Drizzle Kit config
  src/
    lib/db/
      schema.ts                         # Overrides table definition
      index.ts                          # Neon DB connection
    components/
      SidekickBootstrap.tsx             # Provider + Panel wrapper
    app/
      layout.tsx                        # Modified to include SidekickBootstrap
      api/sidekick/[...action]/
        route.ts                        # Handler with Drizzle storage
    .sidekick/
      schema.json                       # App analysis output

Requirements

• Next.js 14+ with App Router
• Node.js 18+
• Anthropic API key for AI generation
• Neon (or any PostgreSQL) only when using --postgres

License

MIT