CLI Reference¶

All AI-Rulez CLI commands and flags.

Command Overview¶

Core Commands¶

CRUD Commands (Configuration Management)¶

CRUD Commands¶

V3 provides CRUD commands to programmatically modify your .ai-rulez/ configuration. These commands allow you to create domains, add rules/context/skills, manage includes, and organize profiles.

Domain Management¶

ai-rulez domain add <name> [flags]¶

Create a new domain with subdirectories for rules, context, and skills.

Syntax:

ai-rulez domain add <name> [flags]

Arguments: - <name> (required): Domain name. Alphanumeric and underscores, 1-50 characters.

Flags: - --description <text> (optional): Description of the domain - --verbose (optional): Show detailed output

Examples:

Create a backend domain:

ai-rulez domain add backend

Create a domain with description:

ai-rulez domain add frontend --description "React web application"

ai-rulez domain remove <name> [flags]¶

Delete a domain and all its contents.

Syntax:

ai-rulez domain remove <name> [flags]

Arguments: - <name> (required): Domain name to delete

Flags: - --force (optional): Skip confirmation prompt

Examples:

Remove a domain (with confirmation):

ai-rulez domain remove backend

Remove without confirmation:

ai-rulez domain remove backend --force

ai-rulez domain list [flags]¶

List all domains in the .ai-rulez/ directory.

Syntax:

ai-rulez domain list [flags]

Flags: - --json (optional): Output as JSON - --verbose (optional): Show file counts per domain

Examples:

List domains:

ai-rulez domain list

List as JSON:

ai-rulez domain list --json

Content Management¶

Rules, context, and skills can be added to the root (always included) or to specific domains (profile-dependent).

ai-rulez add rule <name> [flags]¶

Create a new rule file with optional YAML frontmatter.

Syntax:

ai-rulez add rule <name> [flags]

Arguments: - <name> (required): Rule filename without .md extension

Flags: - --domain <name> (optional): Domain name. If not specified, creates in root rules directory - --priority <level> (optional): Priority: critical, high, medium, low. Default: medium - --targets <list> (optional): Comma-separated list of target providers (claude, cursor, etc.) - --file <path> (optional): Read content from a file instead of stdin - --verbose (optional): Show detailed output

Examples:

Create a root rule:

ai-rulez add rule code-quality

Create a domain-specific rule:

ai-rulez add rule database-standards --domain backend --priority high

Create with specific targets:

ai-rulez add rule performance --targets claude,cursor --priority high

ai-rulez add context <name> [flags]¶

Create a new context file (documentation/reference material).

Syntax:

ai-rulez add context <name> [flags]

Arguments: - <name> (required): Context filename without .md extension

Flags: - --domain <name> (optional): Domain name. If not specified, creates in root context directory - --priority <level> (optional): Priority: critical, high, medium, low. Default: medium - --targets <list> (optional): Comma-separated list of target providers - --file <path> (optional): Read content from a file - --verbose (optional): Show detailed output

Examples:

Create root context:

ai-rulez add context architecture

Create domain context:

ai-rulez add context database-design --domain backend

ai-rulez add skill <name> [flags]¶

Create a new skill file (AI prompt/expert definition).

Syntax:

ai-rulez add skill <name> [flags]

Arguments: - <name> (required): Skill filename without .md extension

Flags: - --domain <name> (optional): Domain name. If not specified, creates in root skills directory - --priority <level> (optional): Priority: critical, high, medium, low. Default: medium - --targets <list> (optional): Comma-separated list of target providers - --file <path> (optional): Read content from a file - --verbose (optional): Show detailed output

Examples:

Create a root skill:

ai-rulez add skill code-reviewer

Create a domain-specific skill:

ai-rulez add skill performance-optimizer --domain backend --priority high

ai-rulez remove rule <name> [flags]¶

Delete a rule file.

Syntax:

ai-rulez remove rule <name> [flags]

Arguments: - <name> (required): Rule filename without .md extension

Flags: - --domain <name> (optional): Domain name - --force (optional): Skip confirmation

Examples:

Remove a root rule:

ai-rulez remove rule code-quality

Remove a domain rule:

ai-rulez remove rule database-standards --domain backend --force

ai-rulez remove context <name> [flags]¶

Delete a context file.

Syntax:

ai-rulez remove context <name> [flags]

Arguments: - <name> (required): Context filename without .md extension

Flags: - --domain <name> (optional): Domain name - --force (optional): Skip confirmation

Examples:

ai-rulez remove context architecture
ai-rulez remove context backend-design --domain backend --force

ai-rulez remove skill <name> [flags]¶

Delete a skill file.

Syntax:

ai-rulez remove skill <name> [flags]

Arguments: - <name> (required): Skill filename without .md extension

Flags: - --domain <name> (optional): Domain name - --force (optional): Skip confirmation

Examples:

ai-rulez remove skill code-reviewer
ai-rulez remove skill performance-optimizer --domain backend --force

ai-rulez list rules [flags]¶

List all rule files.

Syntax:

ai-rulez list rules [flags]

Flags: - --domain <name> (optional): List rules in specific domain only - --json (optional): Output as JSON - --verbose (optional): Show file details

Examples:

List all rules:

ai-rulez list rules

List domain rules:

ai-rulez list rules --domain backend

ai-rulez list context [flags]¶

List all context files.

Syntax:

ai-rulez list context [flags]

Flags: - --domain <name> (optional): List context in specific domain only - --json (optional): Output as JSON - --verbose (optional): Show file details

Examples:

ai-rulez list context
ai-rulez list context --domain backend

ai-rulez list skills [flags]¶

List all skill files.

Syntax:

ai-rulez list skills [flags]

Flags: - --domain <name> (optional): List skills in specific domain only - --json (optional): Output as JSON - --verbose (optional): Show file details

Examples:

ai-rulez list skills
ai-rulez list skills --domain backend

Installed Skill Management¶

Install named skills from external repositories. See Installed Skills for full details.

ai-rulez skill install <name> --source <url> [flags]¶

Install a named skill from a git repository or local path.

Arguments: - <name> (required): Skill name (unique identifier)

Flags: - --source <url> (required): Git URL or local path - --path <dir> (optional): Path within repo to skill directory (defaults to skills/<name>) - --ref <ref> (optional): Git reference (branch, tag, commit)

Examples:

ai-rulez skill install kreuzberg --source https://github.com/kreuzberg-dev/kreuzberg
ai-rulez skill install my-lib --source https://github.com/org/repo --path custom/path --ref v2.0
ai-rulez skill install local-skill --source ../my-other-repo

ai-rulez skill remove <name> [flags]¶

Remove an installed skill from the configuration.

Arguments: - <name> (required): Skill name to remove

Flags: - --force (optional): Skip confirmation prompt

Examples:

ai-rulez skill remove kreuzberg
ai-rulez skill remove my-lib --force

ai-rulez skill list [flags]¶

List all installed skills.

Flags: - --json (optional): Output as JSON

Examples:

ai-rulez skill list
ai-rulez skill list --json

Include Management¶

Manage external rule sources (git repositories or local packages).

ai-rulez include add <name> <source> [flags]¶

Add a new include source to the configuration.

Syntax:

ai-rulez include add <name> <source> [flags]

Arguments: - <name> (required): Unique identifier for this include - <source> (required): Git URL (e.g., https://github.com/org/repo) or local path (e.g., ./packages/shared)

Flags: - --path <dir> (optional): Path within git repository where .ai-rulez/ content is located - --ref <branch> (optional): Git reference (branch, tag, commit). Default: main - --include <types> (optional): Comma-separated content types: rules,context,skills,mcp - --merge-strategy <strategy> (optional): Merge strategy: default, override, append - --install-to <path> (optional): Installation target path in .ai-rulez/

Examples:

Add a git-based include:

ai-rulez include add corporate-rules https://github.com/myorg/shared-rules

Add with custom path and ref:

ai-rulez include add shared-patterns https://github.com/myorg/repo --path .ai-rulez --ref develop

Add local include:

ai-rulez include add backend-package ./packages/backend

ai-rulez include remove <name> [flags]¶

Remove an include source.

Syntax:

ai-rulez include remove <name> [flags]

Arguments: - <name> (required): Include name to remove

Flags: - --force (optional): Skip confirmation

Examples:

ai-rulez include remove corporate-rules
ai-rulez include remove shared-patterns --force

ai-rulez include list [flags]¶

List all include sources.

Syntax:

ai-rulez include list [flags]

Flags: - --json (optional): Output as JSON - --verbose (optional): Show detailed configuration

Examples:

ai-rulez include list
ai-rulez include list --json

Profile Management¶

Organize domains into named profiles for targeted generation.

ai-rulez profile add <name> <domains...> [flags]¶

Create a new profile.

Syntax:

ai-rulez profile add <name> <domains...> [flags]

Arguments: - <name> (required): Profile name - <domains...> (required): Space-separated list of domain names to include

Flags: - --set-default (optional): Set this as the default profile - --verbose (optional): Show detailed output

Examples:

Create a backend profile:

ai-rulez profile add backend backend qa

Create and set as default:

ai-rulez profile add full backend frontend qa --set-default

ai-rulez profile remove <name> [flags]¶

Delete a profile.

Syntax:

ai-rulez profile remove <name> [flags]

Arguments: - <name> (required): Profile name to remove

Flags: - --force (optional): Skip confirmation

Examples:

ai-rulez profile remove staging
ai-rulez profile remove development --force

ai-rulez profile set-default <name> [flags]¶

Set a profile as the default for generation.

Syntax:

ai-rulez profile set-default <name> [flags]

Arguments: - <name> (required): Profile name to set as default

Examples:

ai-rulez profile set-default full

ai-rulez profile list [flags]¶

List all profiles.

Syntax:

ai-rulez profile list [flags]

Flags: - --json (optional): Output as JSON - --verbose (optional): Show domain contents

Examples:

ai-rulez profile list
ai-rulez profile list --json

Initialization Command¶

ai-rulez init [project-name]¶

Initialize a new V4 directory-based configuration.

Syntax:

ai-rulez init [project-name] [flags]

Arguments: - [project-name] (optional): The project name. If not provided, prompted interactively.

V4-specific Flags:

General Flags:

Examples:

Basic V4 initialization (TOML format):

ai-rulez init "my-project"

V4 with YAML format:

ai-rulez init "my-project" --format yaml

V4 with multiple domains:

ai-rulez init "my-project" --domains "backend,frontend,qa"

V4 with example content skipped:

ai-rulez init "my-project" --skip-content

Generate Command¶

ai-rulez generate [config-path]¶

Generate AI assistant rule files from configuration.

Syntax:

ai-rulez generate [config-path] [flags]

Arguments: - [config-path] (optional): Path to configuration file or directory. If not provided, auto-detected.

V3-specific Flags:

General Flags:

Examples:

Generate with default profile:

ai-rulez generate

Generate specific profile:

ai-rulez generate --profile backend

Dry-run to preview generation:

ai-rulez generate --dry-run --profile backend

Generate and update .gitignore:

ai-rulez generate --profile full --update-gitignore

Generate recursively in monorepo:

ai-rulez generate --recursive

Generate with private repository authentication:

# Using environment variable (recommended)
export AI_RULEZ_GIT_TOKEN="ghp_your_github_token_here"
ai-rulez generate

# Using CLI flag
ai-rulez generate --token "ghp_your_github_token_here"

Profile Selection¶

When using V3 configuration:

1. No --profile flag: Uses default profile from config
2. --profile backend: Generates content for the backend profile
3. Invalid profile: Shows error and lists available profiles

Example with profile hierarchy:

# config.yaml
default: "full"
profiles:
  full:
    - backend
    - frontend
    - qa
  backend:
    - backend
  frontend:
    - frontend

# Uses "full" profile (default)
ai-rulez generate

# Uses "backend" profile only
ai-rulez generate --profile backend

# Uses "frontend" profile only
ai-rulez generate --profile frontend

Validation Command¶

ai-rulez validate [config-path]¶

Validate configuration without generating files.

Syntax:

ai-rulez validate [config-path] [flags]

Arguments: - [config-path] (optional): Path to configuration file. If not provided, auto-detected.

Flags:

Examples:

Validate current configuration:

ai-rulez validate

Validate specific config file:

ai-rulez validate .ai-rulez/config.yaml

With verbose output:

ai-rulez validate --verbose

What Gets Validated¶

• version is exactly "3.0"
• name is present and non-empty
• All preset names are valid
• Referenced domains exist in filesystem
• Profile definitions reference valid domains
• File paths are accessible

Migrate Command¶

ai-rulez migrate v4 [config-path]¶

Migrate configuration from V3 (YAML) to V4 (TOML format).

Syntax:

ai-rulez migrate v4 [config-path] [flags]

Arguments: - [config-path] (optional): Path to V3 config.yaml file. If not provided, auto-detected.

Flags:

Examples:

Migrate current directory:

ai-rulez migrate v4

Migrate with dry-run (preview changes):

ai-rulez migrate v4 --dry-run

Migrate specific config without backup:

ai-rulez migrate v4 .ai-rulez/config.yaml --backup false

What It Does:

1. Reads V3 config.yaml (YAML format)
2. Converts all configuration to TOML format
3. Moves MCP servers from separate mcp.yaml into config.toml inline
4. Updates version field to "4.0"
5. Creates new config.toml alongside original
6. Optionally creates backup of original config.yaml

After Migration:

• .ai-rulez/config.toml — new V4 configuration (TOML)
• .ai-rulez/config.yaml.bak — backup of original (if --backup enabled)
• All other files remain unchanged

Then regenerate outputs:

ai-rulez generate

Version Command¶

ai-rulez version¶

Show the current version and build information.

ai-rulez version

MCP Server¶

ai-rulez mcp¶

Starts the Model Context Protocol (MCP) server to allow AI assistants to programmatically interact with your configuration.

ai-rulez mcp

See the MCP Server Documentation for more details.

Global Flags¶

These flags work with all commands:

Examples:

Generate with debug output:

ai-rulez generate --debug

Quiet mode (minimal output):

ai-rulez generate --quiet

Show help for init:

ai-rulez init --help

Configuration Detection¶

The CLI auto-detects configuration in the following order:

1. Explicit path: Via --config flag or command argument
2. V3 format: .ai-rulez/ directory in current directory
3. V2 format: ai-rulez.yaml or ai-rulez.yml in current directory
4. Error: No configuration found

Example detection flow:

cd /path/to/project

# Detects .ai-rulez/ if it exists (V3)
ai-rulez generate

# Use explicit path
ai-rulez generate .ai-rulez/config.yaml

# Specify config via flag
ai-rulez generate --config ./custom-config.yaml

Exit Codes¶

The CLI uses standard exit codes:

Output Examples¶

Initialize Output¶

✅ Created .ai-rulez/ directory structure

Directory structure:
  .ai-rulez/
  ├── config.toml
  ├── rules/         # Base rules (always included)
  ├── context/       # Base context (always included)
  ├── skills/        # Base skills (always included)
  ├── agents/        # Base agents (always included)
  └── domains/       # Domain-specific content

Example content created:
  - rules/code-quality.md
  - context/architecture.md
  - skills/code-reviewer/SKILL.md
  - skills/ai-rulez/SKILL.md

Domain directories created:
  - domains/backend/
  - domains/frontend/
  - domains/qa/

Next steps:
  1. Edit .ai-rulez/config.toml to customize presets and profiles
  2. Add your rules, context, and skills to the appropriate directories
  3. Run 'ai-rulez generate' to create tool-specific outputs

Generate Output¶

✅ Generated 3 file(s) successfully
  - CLAUDE.md
  - .cursorrules
  - docs/AI_GUIDE.md

Validation Output¶

✅ Configuration is valid
  Project: my-project
  Version: 3.0
  Presets: 3
  Domains: 3
  Profiles: 2

Validation Error¶

❌ Configuration validation failed

errors:
  - Profile "backend" references undefined domain "backend"
  - Preset "claude" not found

Run 'ai-rulez validate --verbose' for details

Common CRUD Workflows¶

Creating a Domain with Rules¶

# Create a domain
ai-rulez domain add backend --description "Backend services"

# Add rules to the domain
ai-rulez add rule database-standards --domain backend --priority high
ai-rulez add rule api-design --domain backend --priority high

# Add context
ai-rulez add context architecture --domain backend

# Validate and generate
ai-rulez validate
ai-rulez generate

Setting Up Team-Based Profiles¶

# Create domains for each team
ai-rulez domain add backend
ai-rulez domain add frontend
ai-rulez domain add qa

# Create team-specific profiles
ai-rulez profile add full backend frontend qa --set-default
ai-rulez profile add backend backend qa
ai-rulez profile add frontend frontend qa

# Generate for a specific profile
ai-rulez generate --profile backend

Adding External Rules from Git¶

# Add corporate rules include
ai-rulez include add corporate-rules https://github.com/myorg/shared-rules --ref main

# Verify include was added
ai-rulez include list

# Validate with included content
ai-rulez validate

# Regenerate with included content
ai-rulez generate

Managing Content Across Domains¶

# Add shared rule to root (always included)
ai-rulez add rule code-style --priority high

# Add domain-specific rule
ai-rulez add rule database-standards --domain backend --priority high
ai-rulez add rule accessibility --domain frontend --priority high

# List all rules
ai-rulez list rules

# List domain-specific rules
ai-rulez list rules --domain backend
ai-rulez list rules --domain frontend

# Remove a rule
ai-rulez remove rule old-guideline --force

Common Workflows¶

Set Up a New Project¶

# Initialize with domains
ai-rulez init "my-project" --domains "backend,frontend,qa"

# Review generated structure
ls -la .ai-rulez/

# Create/edit content files
# (edit .ai-rulez/rules/, .ai-rulez/context/, etc.)

# Validate configuration
ai-rulez validate

# Generate outputs
ai-rulez generate

Generate Multiple Profiles¶

# Generate full profile
ai-rulez generate --profile full

# Generate backend-only profile
ai-rulez generate --profile backend

# Generate frontend-only profile
ai-rulez generate --profile frontend

Update AI Configuration After Changes¶

# Edit your content
vim .ai-rulez/rules/my-rule.md

# Validate it's still correct
ai-rulez validate

# Regenerate outputs
ai-rulez generate

# Commit changes
git add .ai-rulez/ CLAUDE.md .cursor/ GEMINI.md
git commit -m "docs: update AI assistant guidelines"

CI/CD Integration¶

#!/bin/bash
# Simple CI/CD script

# Validate configuration
ai-rulez validate || exit 1

# Generate all outputs
ai-rulez generate || exit 1

# Check for uncommitted changes
if ! git diff --quiet CLAUDE.md .cursor/ GEMINI.md; then
  echo "Generated files are out of sync"
  echo "Run: ai-rulez generate"
  exit 1
fi

Troubleshooting¶

Command not found¶

# Make sure AI-Rulez is installed
which ai-rulez

# Or check version
ai-rulez version

Configuration not found¶

# Check current directory
ls -la .ai-rulez/
ls -la ai-rulez.yaml

# Or specify explicitly
ai-rulez generate --config /path/to/config.yaml

Invalid profile name¶

# List available profiles
ai-rulez validate --verbose

# Use a valid profile name
ai-rulez generate --profile backend

Generated files not updated¶

# Check if files were actually generated
ai-rulez generate --dry-run

# Force regeneration
rm CLAUDE.md .cursor/rules/*
ai-rulez generate

Help and Documentation¶

Get help for any command:

ai-rulez --help
ai-rulez init --help
ai-rulez generate --help
ai-rulez validate --help

For more detailed documentation: - Configuration Reference: Config options - Quick Start: Getting started - Domains & Profiles: Team organization