📋 Overview

AI Rules CLI is a command-line tool for managing and composing rule sets defined in ai-rules. It provides an interactive wizard, schema validation, dependency resolution, and conflict detection — all fully typed with TypeScript.

✨ Features

• Interactive Wizard: Step-by-step rule selection with visual feedback
• Dependency Resolution: Automatically resolves rule dependencies
• Conflict Detection: Identifies and helps resolve rule conflicts
• Schema Validation: Validates rules against the MDC schema
• Multiple Commands: List, validate, check, and generate rules
• TypeScript: Fully typed with strict mode

📦 Installation

• Global Installation

npm install -g ai-rules-cli

• Using npx (Recommended)

npx ai-rules-cli init

• Local Development

git clone https://github.com/rerades/ai-rules-cli.git
cd ai-rules-cli
npm install
npm run build
npm link

⚙️ Configuration

• QUICK RULES SETUP

Note: This CLI does not include any predefined rules. To use your own rules, you must specify where the CLI can find them. By default, the CLI will look for rules in your user directory at ~/ai-rules (you can change this path using environment variables).

Any new rule that you define must follow the predefined schema created in this repository.

For a quick rules setup, I also maintain a repository with example rules that you can fork to create your own rule sets.

You can copy the rules to the default repository path ~/ai-rules to get started quickly.

The CLI uses the following default configuration:

• Repository Path: ~/ai-rules - This is where your rules are saved
• Rules Directory: rules
• Schema File: mdc.schema.json
• Output Directory: .cursor/rules

You can override these settings using environment variables:

| Variable | Default | Description | | ---------------------- | --------------- | --------------------------------- | | AI_RULES_REPO_PATH | ~/ai-rules | Repository where rules are stored | | AI_RULES_OUTPUT_PATH | .cursor/rules | Output folder | | AI_RULES_VERBOSE | false | Enable verbose logging |

export AI_RULES_REPO_PATH="/path/to/your/rules/repo"
export AI_RULES_OUTPUT_PATH="/path/to/output"
export AI_RULES_VERBOSE=true

🚀 Usage

• Initialize a new project

ai-rules init

This will launch the interactive wizard to:

1. Select rule categories
2. Choose specific rules
3. Configure output directory
4. Resolve dependencies and conflicts
5. Generate rule files

• List available rules

ai-rules list

Options:

• -c, --category <category> - Filter by category
• -s, --search <query> - Search rules by title or summary
• -v, --verbose - Show detailed information

• Validate rules

ai-rules validate

Options:

• -v, --verbose - Show detailed validation results

• Check dependencies and conflicts

ai-rules check <rule-ids...>

Options:

• -v, --verbose - Show detailed information

• Generate rules directly

ai-rules generate <rule-ids...> -o <output-path>

Options:

• -o, --output <path> - Output directory path
• --dry-run - Simulate without creating files
• -m, --minify-frontmatter - Emit minimal frontmatter (required fields only)
• --keep <fields> - Comma-separated optional fields to retain with minify (e.g., description,scope,enforcement)
• -v, --verbose - Enable verbose output

Frontmatter modes

• Minimal (with -m):

---
id: foundation.response-deliverables.structure
version: 1.0.0
title: "Response Deliverables — Structure"
category: foundation
---

• Extended (default or allowlisted via --keep):

---
id: foundation.response-deliverables.structure
version: 1.0.0
title: "Response Deliverables — Structure"
category: foundation
description: "Rules for structuring responses with status, edits, and impact summary."
scope: ["global"]
language: "none"
enforcement: { lint: "warn", ci: "allow", scaffold: "none" }
---

📋 Rule Schema

Rules must follow the MDC (Markdown with frontmatter) schema defined in mdc.schema.json. Each rule file should have:

• Frontmatter: YAML metadata with rule information
• Content: Markdown content with the actual rule

Example rule structure:

---
id: "foundation.code-guidelines"
version: "1.0.0"
title: "Code Guidelines"
summary: "Basic coding standards and best practices"
category: "foundation"
scope: ["global"]
language: "ts"
lifecycle: "recommended"
maturity: "stable"
order: 10
---
# 📝 Code Guidelines

This rule defines basic coding standards...

📁 Output Structure

The CLI generates the following structure:

.cursor/
└── rules/
    ├── index.md
    ├── foundation.code-guidelines.mdc
    ├── typescript.conventions.mdc
    └── ...

Additionally, the CLI generates a claude.md file in the output directory root (alongside .cursor/rules/) for Claude AI integration.

• Index File

The index.md file contains:

• Overview of all rules
• Categorization
• Rule metadata
• Usage instructions

• Claude.md File

The claude.md file is automatically generated to help Claude AI integrate with your rules:

• Provides structured guidelines for Claude AI to reference the .cursor/rules directory
• Explains how Claude can benefit from your rules and maintain consistency with Cursor IDE
• Includes usage examples and best practices for working with rules in Claude
• Documents available rules and categories for easy reference
• Generated automatically when running init or generate commands

• Rule Files

Each rule file (.mdc) contains:

• YAML frontmatter with metadata
• Markdown content with the actual rule

🛠️ Development

• Prerequisites

• Node.js 18+
• TypeScript 5+
• npm or yarn

• Setup

git clone <repository-url>
cd ai-rules-cli
npm install

• Build

npm run build

• Development

npm run dev

• Testing

npm test

• Linting

npm run lint
npm run lint:fix

🏗️ Architecture

The CLI is built with a modular architecture:

src/
├── core/           # Core business logic
│   ├── config.ts   # Configuration management
│   ├── rule-loader.ts      # Rule loading and parsing
│   ├── rule-validator.ts   # Schema validation
│   └── dependency-resolver.ts # Dependency resolution
├── ui/             # User interface
│   ├── wizard.ts   # Interactive wizard
│   ├── prompts.ts  # Inquirer prompts
│   ├── formatters.ts # Visual formatting
│   └── spinner.ts  # Loading indicators
├── generators/     # File generation
│   ├── output-generator.ts # Rule file generation
│   └── index-generator.ts  # Index file generation
├── utils/          # Utilities
│   ├── logger.ts   # Logging
│   └── file-utils.ts # File operations
├── types/          # TypeScript types
│   ├── rule.types.ts
│   ├── config.types.ts
│   └── wizard.types.ts
└── index.ts        # CLI entry point

⚠️ Error Handling

The CLI provides comprehensive error handling:

• Validation Errors: Clear messages for schema violations
• Dependency Errors: Missing dependencies are reported
• Conflict Errors: Rule conflicts are identified and resolved
• File Errors: File system operations are handled gracefully
• User Errors: Invalid inputs are caught and reported

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

💬 Support

For issues and questions:

• Create an issue on GitHub
• Check the documentation
• Review the examples

🪪 License

MIT © Rodrigo Erades