CLI Reference

AI Kit provides fourteen commands: init, update, reset, audit, tokens, doctor, diff, export, stats, health, patterns, dead-code, drift, and component-registry.

ai-kit init [path]

Scan a project and generate AI configuration files.

npx @mikulgohil/ai-kit init
npx @mikulgohil/ai-kit init ./path/to/project

What it does

1. Scans the project directory for tech stack indicators (including design tokens, static site, and .aiignore)
2. Checks for existing config — if found, shows saved profile and offers: Update (reuse settings), Re-configure, or Cancel
3. Shows detected stack and asks clarification questions if needed (skipped in Update mode)
4. Asks which AI tools to generate configs for — or reuses saved choice
5. Asks strictness and hook profile — or reuses saved choices
6. Generates all configuration files
7. Writes ai-kit.config.json to track what was generated including your tool/strictness/hook choices

Interactive Prompts

Profile Persistence (v1.5.0+)

Your choices are saved in ai-kit.config.json under the tools field:

{
  "tools": { "claude": true, "cursor": true },
  "strictness": "standard",
  "hookProfile": "standard"
}

When a teammate clones the project and runs ai-kit init, they see the saved profile and can accept it with one keypress. This ensures consistent AI configuration across the team.

Generated Files

ai-kit update [path]

Re-scan the project and update all generated files.

npx @mikulgohil/ai-kit update
npx @mikulgohil/ai-kit update ./path/to/project

What it does

1. Reads existing ai-kit.config.json (fails if not found)
2. Checks for version mismatch — warns if major version differs
3. Re-scans the project for tech stack changes
4. Updates CLAUDE.md and .cursorrules using safe merge — only content between AI-KIT:START/END markers is replaced, preserving your manual edits
5. Updates .cursor/rules/*.mdc files
6. Refreshes slash commands, guides, agents, contexts, and hooks
7. Updates ai-kit.config.json

Safe Merge Behavior

Generated files contain markers:

<!-- AI-KIT:START -->
[generated content]
<!-- AI-KIT:END -->

On update, only content between these markers is replaced. Anything you add above or below the markers is preserved.

If no markers exist (files from before v1.0.0), the entire file is replaced.

Version Mismatch Warning

⚠ Config was generated with ai-kit v1.0.0, but you're running v2.0.0.
  Consider running `ai-kit init` to re-initialize.

This appears when the major version differs. Minor/patch updates proceed silently.

ai-kit reset [path]

Remove all AI Kit generated files from a project.

npx @mikulgohil/ai-kit reset
npx @mikulgohil/ai-kit reset ./path/to/project

What it removes

Safety

• Shows a full list of what will be removed before proceeding
• Requires explicit confirmation (Are you sure? This cannot be undone.)
• Only removes files that AI Kit created — your source code and other configs are untouched
• Does NOT remove docs/ scaffolds (mistakes-log, decisions-log, time-log) since you may have added content to them

ai-kit audit [path]

Run a security and configuration health audit on your AI setup.

npx @mikulgohil/ai-kit audit
npx @mikulgohil/ai-kit audit ./path/to/project

What it checks

Output

AI Kit — Security & Configuration Audit
ℹ Auditing: /Users/you/projects/my-app

  ✓ Config file: ai-kit.config.json found
  ✓ CLAUDE.md: CLAUDE.md has AI-KIT markers
  ✓ Secrets in CLAUDE.md: No secrets detected
  ✓ Hooks: Hooks configured in settings.local.json
  ✓ Agents: 16 agent(s) configured
  ✓ Contexts: 3 context mode(s) available
  ✓ Skills: 48 skill(s) installed
  ✓ .env gitignore: .env files are gitignored
  ⚠ Settings gitignore: settings.local.json not in .gitignore
  ✓ MCP secrets: No hardcoded secrets in settings

Score
  A (95/100)
  10 passed · 1 warnings · 0 failures

Scoring

The audit produces a letter grade based on checks passed:

Warnings count as half a point. Failures count as zero. Fix all failures before proceeding.

ai-kit tokens

Show token usage summary, cost estimates, and analytics.

ai-kit tokens
ai-kit tokens --export
ai-kit tokens --csv
ai-kit tokens --budget 100

Options

What it shows

• Period summaries: Today, this week, this month (sessions, tokens, cost)
• Budget progress: Visual progress bar with percentage used
• Budget alerts: Warnings at 50%, 75%, 90% thresholds
• Per-project breakdown: Cost per project ranked by usage
• Week-over-week trend: Cost comparison with previous week
• Model recommendations: Suggests Sonnet vs Opus usage optimization
• ROI estimate: Estimated time saved and developer cost offset

ai-kit doctor [path]

Diagnose your AI Kit setup and check for issues.

ai-kit doctor
ai-kit doctor ./path/to/project

What it checks

Output

AI Kit — Doctor

✓ ai-kit.config.json found (v1.0.0)
✓ Version matches CLI (v1.0.0)
✓ CLAUDE.md exists and in sync
✓ .cursorrules exists and in sync
✓ 48/48 skills present
✓ 5/5 guides present
⚠ Stack may have changed — detected new styling: scss
⚠ Perplexity MCP not configured

Summary: 6 passed, 2 warnings, 0 issues

ai-kit diff [path]

Preview what would change on ai-kit update without writing any files.

ai-kit diff
ai-kit diff ./path/to/project

What it shows

• Stack changes: New technologies detected, versions changed, or technologies removed
• File changes: Which generated files would be modified, added, or remain unchanged
• Fragment changes: Which template fragments would be added or removed

Output

AI Kit — Diff (dry run)

Stack Changes:
  + scss detected (styling)
  ~ Next.js version: 15.0.0 → 15.1.0

File Changes:
  modified  CLAUDE.md (template fragments changed: +monorepo)
  modified  .cursorrules (template fragments changed: +monorepo)
  unchanged .claude/skills/ (48 skills)
  unchanged ai-kit/guides/ (5 guides)

Summary: 2 files would be modified, 0 added, 0 removed
Run `ai-kit update` to apply these changes.

ai-kit export [path]

Export your AI rules to other AI editor tools.

ai-kit export
ai-kit export --format windsurf
ai-kit export --format all

Options

Supported Formats

The exported files contain the same rules as your CLAUDE.md, reformatted for each tool’s expected format. AI-KIT markers are stripped during export.

ai-kit stats [path]

Show project setup statistics and complexity analysis.

ai-kit stats
ai-kit stats ./path/to/project

What it shows

• Project overview: Name, version, generation date, package manager
• Stack complexity score: Weighted score (1-10) with label (Simple/Moderate/Complex/Enterprise)
• Active rules: Which template fragments are included
• Skills breakdown: Total count grouped by category
• Tools status: Detected vs missing development tools
• MCP servers: Configured vs missing MCP integrations

ai-kit health [path]

One-glance project health dashboard — combines setup integrity, security, stack detection, tools, and documentation checks into a single view.

ai-kit health
ai-kit health ./path/to/project

What it checks

The health command runs five diagnostic sections:

Output

AI Kit — Project Health
  /Users/you/projects/my-app

  Setup Integrity
    ✓ Version: v1.3.0
    ✓ CLAUDE.md: Present with markers
    ✓ .cursorrules: Present
    ✓ Skills: 46 installed
    ✓ Agents: 10 configured
    ✓ Hooks: Configured

  Security
    ✓ Secrets in CLAUDE.md: Clean
    ✓ .env gitignore: Protected
    ✓ MCP config: No hardcoded secrets

  Stack Detection
    ✓ Framework: Next.js 15.1.0 (App Router)
    ✓ CMS: Sitecore XM Cloud (Content SDK v2)
    ✓ TypeScript: Enabled (strict)
    ✓ Styling: tailwind

  Tools & MCP
    ✓ Playwright: Detected
    ✓ ESLint: Detected
    ⚠ Knip: Missing — npm i -D knip
    ⚠ Perplexity MCP: Not configured

  Documentation
    ✓ Mistakes Log: Has entries
    ⚠ Decisions Log: Scaffolded but empty
    ⚠ Time Log: Scaffolded but empty

  Overall: B (82/100)
  ████████████████░░░░ 18 passed · 4 warnings · 0 failures

  Recommendations:
    → Improve: Knip — Missing — npm i -D knip
    → Improve: Perplexity MCP — Not configured
    → Improve: Decisions Log — Scaffolded but empty

Scoring

The health check produces a letter grade based on all checks across all sections:

Passed checks count as 1 point, warnings as 0.5, failures as 0. The top 3 actionable recommendations are shown at the bottom.

When to use

• After ai-kit init — verify everything was set up correctly
• Before a PR — quick health check that your AI setup is intact
• During onboarding — show a new developer the project’s AI health at a glance
• Instead of running doctor + audit + stats separately — health combines the most useful checks from each

ai-kit patterns [path]

Generate a pattern library from recurring code patterns found in your project.

ai-kit patterns
ai-kit patterns ./path/to/project

What it does

Scans your codebase for recurring code patterns and generates ai-kit/patterns.md — a reference document the AI uses to match new code to your established conventions.

Patterns detected

Output

Writes ai-kit/patterns.md with categorized code pattern examples. The AI reads this file to ensure new code follows your project’s established conventions.

ai-kit dead-code [path]

Find unused components and dead code across your project.

ai-kit dead-code
ai-kit dead-code ./path/to/project

What it does

Runs the component scanner and cross-references all exports against import usage to identify code that is no longer referenced.

Output

AI Kit — Dead Code Report
  /Users/you/projects/my-app

  Components scanned: 84

  UNUSED (never imported):
    src/components/OldBanner.tsx
    src/components/legacy/PromoWidget.tsx

  TEST-ONLY (only imported in test files):
    src/components/MockProvider.tsx

  IN USE: 81 components

  Summary: 2 unused · 1 test-only · 81 in use

Reports each component as used, unused, or test-only. Does not delete anything — review output and remove manually.

ai-kit drift [path]

Detect drift between component source code and their .ai.md documentation files.

ai-kit drift
ai-kit drift ./path/to/project

What it does

Compares each component’s current source code against its .ai.md documentation. Flags components where the props, exports, or Sitecore integration no longer match the documented state.

Output

AI Kit — Drift Report
  /Users/you/projects/my-app

  Components checked: 42

  DRIFTED (code changed, docs not updated):
    src/components/ProductCard.tsx — props added: discount, badge
    src/components/Header.tsx — props removed: logoVariant

  OUTDATED (no .ai.md file):
    src/components/NewWidget.tsx

  IN SYNC: 39 components

  Summary: 2 drifted · 1 outdated · 39 in sync
  Run `ai-kit update` to regenerate docs for drifted components.

ai-kit component-registry [path]

Generate a component registry for AI agent discovery.

ai-kit component-registry
ai-kit component-registry ./path/to/project

What it does

Scans all React components in the project and generates two files:

Output

AI Kit — Component Registry
  /Users/you/projects/my-app

  Found 84 components in 12 directories

  Categories:
    28 ui
    18 feature
    14 content
     9 navigation
     8 layout
     7 general

  Health:
    Average score: 62/100
    With tests: 34/84
    With stories: 22/84
    With .ai.md docs: 15/84

✓ Registry written to ai-kit/component-registry.json
✓ Summary written to ai-kit/component-registry.md

When to use

• After creating new components — regenerate to keep the registry current
• Before asking AI to create a component — it checks the registry to avoid duplicates
• During project audits — the health scores highlight under-documented components

Global Options

ai-kit --version          # Show version number
ai-kit --help             # Show help
ai-kit init --help        # Show command-specific help
ai-kit audit --help       # Show audit command help
ai-kit tokens --help      # Show tokens command help
ai-kit doctor --help      # Show doctor command help
ai-kit diff --help        # Show diff command help
ai-kit export --help      # Show export command help
ai-kit stats --help       # Show stats command help
ai-kit health --help      # Show health command help
ai-kit patterns --help    # Show patterns command help
ai-kit dead-code --help   # Show dead-code command help
ai-kit drift --help       # Show drift command help