@ai-guide/cli

Command-line tool for scanning React applications and automatically adding data-ai attributes to components. Makes your UI discoverable for AI-powered guidance.

Installation

npm install -g @ai-guide/cli
# or
pnpm add -g @ai-guide/cli
# or
yarn global add @ai-guide/cli

Or use directly with npx:

npx @ai-guide/cli scan ./src

Features

• 🔍 Scans all React/JSX files (pages, components, lib, etc.)
• 🏷️ Automatically adds data-ai attributes
• 🎯 Smart naming based on content and context
• 📊 Detailed scanning reports
• 🔄 Supports TypeScript and JavaScript
• ⚡ Fast parallel processing
• 📁 Comprehensive coverage: components, pages, and all UI code
• 🛤️ Supports both App Router (app/) and Pages Router (pages/)
• 🧩 Detects reusable components in components/, lib/, and custom directories

Usage

Initialize AI Guide

Set up AI Guide in your Next.js project:

npx @ai-guide/cli init

This will:

1. Install @ai-guide/react and @ai-guide/cli packages
2. Inject the <AiGuide /> component into your root layout
3. Scan your project and upload UI context
4. Show all scanned files for transparency
5. Optionally export scan results to scan-results.json

Scan Your Project

Scan and index your UI components:

ai-guide scan

Or with a specific project ID:

ai-guide scan --project-id your-project-id

What gets scanned:

• All React/TypeScript files in your project
• Component names, buttons, links, forms, headings
• Interactive element metadata (no source code!)
• File paths and route information

Transparency Features:

• 📂 Lists all scanned files
• 📋 Option to export scan-results.json to review collected data
• 🔒 No source code is uploaded, only UI metadata

Examples

Dry run (see changes without applying):

ai-guide scan ./src --dry-run

Scan with exclusions:

ai-guide scan ./src --exclude "**/test/**,**/node_modules/**"

Generate report:

ai-guide scan ./src --output report.json

What It Does

The CLI scans your React files and adds data-ai attributes to interactive elements:

Before:

function ContactForm() {
  return (
    <form>
      <input type="email" placeholder="Email" />
      <input type="text" placeholder="Name" />
      <button type="submit">Send Message</button>
    </form>
  );
}

After:

function ContactForm() {
  return (
    <form>
      <input data-ai="email-input" type="email" placeholder="Email" />
      <input data-ai="name-input" type="text" placeholder="Name" />
      <button data-ai="send-message" type="submit">Send Message</button>
    </form>
  );
}

How Naming Works

The CLI generates data-ai values based on:

1. Element text content (buttons, links)
2. Input types and names
3. Placeholder text
4. ARIA labels and roles
5. Component context

Supported Elements

• Buttons (<button>)
• Links (<a>)
• Inputs (<input>, <textarea>, <select>)
• Interactive divs/spans with click handlers
• Form elements
• Navigation elements

Configuration

Create a .aiguidrc.json file in your project root:

{
  "exclude": ["**/node_modules/**", "**/test/**"],
  "include": ["src/**/*.tsx", "src/**/*.jsx"],
  "namingStrategy": "semantic",
  "overwrite": false
}

Best Practices

1. Run before commit: Add as a pre-commit hook to ensure all new components are tagged
2. Review changes: Use --dry-run first to review what will change
3. Commit tagged code: Commit the tagged files to your repository
4. Combine with manual tagging: Add specific data-ai attributes manually for important elements

API Integration

The CLI can optionally connect to your AI Guide backend to:

• Validate that tagged elements are discoverable
• Generate semantic suggestions for tags
• Test guidance flows

ai-guide scan ./src --api-url https://your-backend.com/api

Related Packages

• @ai-guide/react - React component for AI Guide
• @ai-guide/react-plugin - Build-time plugin alternative
• @ai-guide/types - Shared types

License

MIT