Skip to content

CLI Reference

All AI-Rulez CLI commands and flags.

Command Overview

Core Commands

Command Description
ai-rulez init Initialize V4 directory-based configuration
ai-rulez generate Generate presets for specific profile
ai-rulez validate Validate configuration
ai-rulez migrate Migrate configuration versions (migrate v4 command)
ai-rulez version Show version
ai-rulez mcp Start MCP server
ai-rulez builtins list List available built-in domains
ai-rulez builtins show <name> Show bundled content for a built-in domain

CRUD Commands (Configuration Management)

Command Description
ai-rulez domain add/remove/list Manage domains
ai-rulez add rule/context/skill Create content files
ai-rulez remove rule/context/skill Delete content files
ai-rulez list rules/context/skills List content files
ai-rulez include add/remove/list Manage external includes
ai-rulez skill install/remove/list Manage installed skills
ai-rulez profile add/remove/list Manage profiles
ai-rulez profile set-default Set default profile

CRUD Commands

AI-Rulez provides CRUD commands to programmatically modify your V4 .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> / -s (optional): Description of the domain

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 / -f (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 / -j (optional): Output as JSON

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> / -d (optional): Domain name. If not specified, creates in root rules directory
  • --priority <level> / -p (optional): Priority: critical, high, medium, low. Default: medium
  • --targets <list> / -t (optional): Comma-separated list of target providers (claude, cursor, etc.)
  • --content <text> / -c (optional): Rule content. Uses a template if omitted.

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> / -d (optional): Domain name. If not specified, creates in root context directory
  • --priority <level> / -p (optional): Priority: critical, high, medium, low. Default: medium
  • --content <text> / -c (optional): Context content. Uses a template if omitted.

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> / -d (optional): Domain name. If not specified, creates in root skills directory
  • --description <text> / -s (optional): Skill description
  • --content <text> / -c (optional): Skill content. Uses a template if omitted.

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> / -d (optional): Domain name
  • --force / -f (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> / -d (optional): Domain name
  • --force / -f (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> / -d (optional): Domain name
  • --force / -f (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> / -d (optional): List rules in specific domain only
  • --json / -j (optional): Output as JSON

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> / -d (optional): List context in specific domain only
  • --json / -j (optional): Output as JSON

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> / -d (optional): List skills in specific domain only
  • --json / -j (optional): Output as JSON

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> / -s (required): Git URL or local path
  • --path <dir> / -p (optional): Path within repo to skill directory (defaults to skills/<name>)
  • --ref <ref> / -r (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 / -f (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 / -j (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> / -p (optional): Path within git repository where .ai-rulez/ content is located
  • --ref <branch> / -r (optional): Git reference (branch, tag, commit). Default: main
  • --include <types> / -i (optional): Comma-separated content types: rules,context,skills,mcp
  • --merge-strategy <strategy> / -m (optional): Merge strategy: default, override, append
  • --install-to <path> / -t (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 / -f (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 / -j (optional): Output as JSON

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 / -s (optional): Set this as the default profile

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 / -f (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 / -j (optional): Output as JSON

Examples:

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

Builtins Command

ai-rulez builtins list [flags]

List all built-in domains embedded in the ai-rulez binary.

Flags:

  • --json / -j (optional): Output as JSON

ai-rulez builtins show <name> [flags]

Show the full rules, context, skills, agents, and commands for a built-in domain.

Arguments:

  • <name> (required): Built-in domain name, such as security, go, or typescript

Flags:

  • --json / -j (optional): Output as 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:

Flag Type Default Description
--format / -f string toml Configuration format: toml, yaml, or json
--domains / -d string (none) Comma-separated list of domain names to create
--skip-content / -s boolean false Skip creating example content files
--from / -F string (none) Import from existing tool files, such as auto or .claude,.cursor
--setup-hooks / -H boolean false Configure Git hooks after initialization
--yes / -y boolean false Automatically answer yes to prompts

General Flags:

Flag Type Description
--verbose boolean Enable verbose output
--debug boolean Enable debug output

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.

Generation Flags:

Flag Type Default Description
--profile / -p string (from config) Profile to generate

General Flags:

Flag Type Default Description
--dry-run / -d boolean false Show what would be generated without writing files
--gitignore / -i boolean (from config) Update .gitignore with generated output patterns
--recursive / -r boolean false Find and process configs recursively
--no-fetch / -f boolean false Skip fetching remote includes and use cached content
--config-dir / -n string .ai-rulez Configuration directory name for non-default layouts
--env / -e string MCP env override in KEY=VALUE form; repeatable
--env-file / -E string .env Dotenv file for MCP env placeholders; repeatable
--no-configure-cli-mcp / -M boolean false Skip configuring CLI-based MCP tools such as Claude and Gemini
--skip-cli-mcp / -S boolean false Alias for --no-configure-cli-mcp
--token / -T string (from env) Git access token for private repositories (or use AI_RULEZ_GIT_TOKEN env var)

--update-gitignore still works as a hidden deprecated alias for --gitignore for backward compatibility.

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 --gitignore

Generate MCP configs with secret env values:

ai-rulez generate --env GRAFANA_SERVICE_ACCOUNT_TOKEN="$GRAFANA_SERVICE_ACCOUNT_TOKEN"

Generate recursively in monorepo:

ai-rulez generate --recursive

Generate from a non-default configuration directory:

ai-rulez generate --config-dir ai-policy

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 profile-based 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:

# .ai-rulez/config.toml
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:

Flag Type Description
--config-dir string Configuration directory name for non-default layouts
--verbose boolean Enable verbose output
--debug boolean Enable debug output

Examples:

Validate current configuration:

ai-rulez validate

Validate specific config file:

ai-rulez validate .ai-rulez/config.toml

With verbose output:

ai-rulez validate --verbose

What Gets Validated

  • version is "3.0" or "4.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

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

Syntax:

ai-rulez migrate v4

Arguments:

  • v4, 4, or 4.0 (required): Target configuration version.

The migrate command has no command-local flags.

Examples:

Migrate current directory:

ai-rulez migrate v4

What It Does:

  1. Finds .ai-rulez/ in the current directory
  2. Returns without changes if .ai-rulez/config.toml already exists
  3. Loads the existing configuration, including legacy MCP files if present
  4. Writes .ai-rulez/config.toml with version = "4.0"
  5. Removes old .ai-rulez/config.yaml, .ai-rulez/config.json, .ai-rulez/mcp.yaml, .ai-rulez/mcp.toml, and .ai-rulez/mcp.json files

After Migration:

  • .ai-rulez/config.toml — new V4 configuration (TOML)
  • 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:

Flag Type Description
--config / -C string Config file path (auto-discovered if not specified)
--token / -T string Git access token for private repositories (or use AI_RULEZ_GIT_TOKEN env var)
--verbose / -V boolean Enable verbose output
--debug / -D boolean Enable debug output
--quiet / -q boolean Suppress progress bars and non-essential output
--help / -h boolean Show help for a command

Most command-local flags also have shorthands. Common mappings are --domain -d, --force -f, --json -j, --priority -p, --targets -t, --content -c, --description -s, --path -p, and --ref -r.

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

Commands that load a project directory use the following config order:

  1. Explicit path: Via --config flag or command argument
  2. Directory config: .ai-rulez/config.toml, .ai-rulez/config.yaml, or .ai-rulez/config.json
  3. Error: No configuration found

Legacy flat V2 config files such as ai-rulez.yaml are migration inputs. Use ai-rulez migrate v4 before running V4 generation workflows.

Example detection flow:

cd /path/to/project

# Detects .ai-rulez/ if it exists
ai-rulez generate

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

# Specify config via flag
ai-rulez generate --config ./ai-policy/config.toml

Exit Codes

The CLI uses standard exit codes:

Code Meaning
0 Success
1 General error (config not found, validation failed, etc.)
2 Command syntax error (invalid flags, arguments)

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

INFO  Configuration is valid path=/path/to/project/.ai-rulez
INFO
Configuration summary:
INFO   - Rules: count=5
INFO   - Context files: count=10
INFO   - Skills: count=8
INFO   - Domains: count=9
INFO     - Domain rules: count=35
INFO     - Domain context: count=2
INFO   - Presets: count=12

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/config.toml

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

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: