AGENT_RULES Docs

Installation

# Run with npx
npx @agentrules/cli <command>

# Or install globally
npm install -g @agentrules/cli
agentrules <command>

Installing Rules

add

Install a rule from the registry.

agentrules add <name> [options]

Arguments:

Argument	Description
`name`	Rule name, optionally with version (e.g., `my-rule`, `my-rule@1.0`)

Options:

Option	Description
`-p, --platform <platform>`	Target platform: `opencode`, `claude`, `cursor`, `codex`
`--version <version>`	Install a specific version (or use `slug@version`)
`-g, --global`	Install to global config directory
`--dir <path>`	Install to a custom directory
`-r, --registry <alias>`	Use a specific registry
`-f, --force`	Overwrite existing files (backs up originals to `.bak`)
`-y, --yes`	Alias for `--force`
`--no-backup`	Don't backup files when using `--force`
`--dry-run`	Preview changes without writing
`--skip-conflicts`	Skip files that already exist

Examples:

# Basic install
agentrules add agentic-dev-starter --platform opencode

# Install globally
agentrules add agentic-dev-starter -p opencode --global

# Install specific version
agentrules add agentic-dev-starter -p opencode --version 1.0

# Using @ syntax for version
agentrules add agentic-dev-starter@1.0 -p opencode

# Preview without writing
agentrules add agentic-dev-starter -p opencode --dry-run

# Force overwrite (backs up existing files)
agentrules add agentic-dev-starter -p opencode --force

# Force overwrite without backups
agentrules add agentic-dev-starter -p opencode --force --no-backup

Creating Rules

init

Initialize a rule config in a directory.

agentrules init [directory] [options]

Arguments:

Argument	Description
`directory`	Directory to initialize (default: current directory)

Options:

Option	Description
`-n, --name <name>`	Rule name
`-t, --title <title>`	Display title
`--description <text>`	Rule description
`-p, --platform <platform>`	Target platform(s). Repeatable, accepts comma-separated. Supports `<platform>=<path>` for custom paths
`-l, --license <license>`	License (e.g., `MIT`)
`-f, --force`	Overwrite existing config
`-y, --yes`	Accept defaults, skip prompts

Examples:

# Initialize in current directory (interactive)
agentrules init

# Initialize a new directory (interactive)
agentrules init my-rule

# Non-interactive (requires --platform unless directory name is a platform dir)
agentrules init my-rule --platform opencode --yes

# Multiple platforms (comma-separated or repeated)
agentrules init my-rule --platform opencode,claude --yes
agentrules init my-rule -p opencode -p claude --yes

# With custom source paths per platform
agentrules init my-rule --platform opencode=src/opencode,claude=.claude-files --yes
# Alternatively:
agentrules init my-rule -p opencode=src/opencode -p claude=.claude-files --yes

Result:

my-rule/
├── agentrules.json       # Rule config (created by init)
├── README.md             # Metadata (optional, not bundled)
├── LICENSE.md            # Metadata (optional, not bundled)
├── INSTALL.txt           # Metadata (optional, not bundled)
└── command/
    └── review.md

validate

Validate a rule configuration.

agentrules validate [path]

Arguments:

Argument	Description
`path`	Path to `agentrules.json` or directory containing it (default: current directory)

Examples:

# Validate current directory
agentrules validate

# Validate specific path
agentrules validate ./my-rule

Publishing Rules

Authenticate with the registry. Opens a browser for OAuth.

agentrules login [options]

Options:

Option	Description
`--url <url>`	Registry URL
`--no-browser`	Skip opening browser (for headless environments)

logout

Log out and clear stored credentials.

agentrules logout

whoami

Show the currently authenticated user.

agentrules whoami

publish

Publish a rule to the registry. Requires authentication.

agentrules publish [path] [options]

Arguments:

Argument	Description
`path`	Path to `agentrules.json`, a directory containing it, or a single file to publish (default: current directory)

Options:

Option	Description
`--version <major>`	Major version to publish (overrides config)
`--dry-run`	Preview without publishing
`-p, --platform <platform>`	Publish one or more platform variants (config mode). Repeatable and accepts comma-separated. In file mode, must resolve to exactly one platform (required in non-interactive file mode)
`--type <type>`	Override rule type (config mode), or set type when publishing a file (required in non-interactive file mode)
`--name <name>`	Override published name (config mode), or set name when publishing a file (required in non-interactive file mode)
`--tags <tags>`	Override published tags (comma-separated). In file mode, defaults to the type if omitted
`-t, --title <title>`	Override published title
`--description <text>`	Override published description
`-l, --license <license>`	Override published license

Examples:

# Publish current directory
agentrules publish

# Publish a specific rule directory
agentrules publish ./my-rule

# Publish to major version 2
agentrules publish --version 2

# Preview what would be published
agentrules publish --dry-run

# Publish only one platform variant (config mode)
agentrules publish --platform claude

# Publish a subset of platform variants (config mode)
agentrules publish --platform claude,opencode
agentrules publish --platform claude --platform opencode

# Quick publish a file or directory (interactive)
agentrules publish .claude/commands/deploy.md
agentrules publish ./my-rule

# Quick publish non-interactively (requires all options)
agentrules publish .claude/commands/deploy.md --platform claude --type command --name deploy

unpublish

Remove a specific version of a rule from the registry. Requires authentication.

agentrules unpublish <rule> [options]

Arguments:

Argument	Description
`rule`	Rule identifier (e.g., `my-rule@1.0`)

Options:

Option	Description
`--version <version>`	Version to unpublish (or use `rule@version`)

Examples:

# Using @ syntax (recommended)
agentrules unpublish my-rule@1.0

# Using --version flag
agentrules unpublish my-rule --version 1.0

Unpublished versions cannot be republished with the same version number.

Registry Management

registry list

List configured registries.

agentrules registry list

registry add

Add a custom registry.

agentrules registry add <alias> <url> [options]

Arguments:

Argument	Description
`alias`	Short name for the registry
`url`	Registry URL

Options:

Option	Description
`-f, --force`	Overwrite existing entry
`-d, --default`	Set as the default registry

Examples:

# Add a registry
agentrules registry add company https://registry.company.com

# Add and set as default
agentrules registry add company https://registry.company.com --default

registry remove

Remove a registry.

agentrules registry remove <alias> [options]

Options:

Option	Description
`-f, --force`	Allow removing the default registry

registry use

Set the default registry.

agentrules registry use <alias>

registry build

Build registry artifacts from rule directories. For self-hosted registries.

agentrules registry build [options]

Options:

Option	Description
`-i, --input <path>`	Directory containing rule folders (required)
`-o, --out <path>`	Output directory for registry artifacts
`-b, --bundle-base <url>`	URL prefix for bundle locations
`-c, --compact`	Emit minified JSON
`--validate-only`	Validate without writing files

Configuration

CLI configuration is stored at ~/.agentrules/config.json.

You can override the config directory with the AGENT_RULES_HOME environment variable.

Default config:

~/.agentrules/config.json

{
  "defaultRegistry": "main",
  "registries": {
    "main": {
      "url": "https://agentrules.directory/"
    }
  }
}

Supported Platforms

Platform	ID	Project Directory	Global Directory
OpenCode	`opencode`	`.opencode/`	`~/.config/opencode`
Claude Code	`claude`	`.claude/`	`~/.claude`
Cursor	`cursor`	`.cursor/`	`~/.cursor`
Codex	`codex`	`.codex/`	`~/.codex`

CLI Reference

Installation

Installing Rules

add

Creating Rules

init

validate

Publishing Rules

logout

whoami

publish

unpublish

Registry Management

registry list

registry add

registry remove

registry use

registry build

Configuration

Supported Platforms

FAQ

On this page

CLI Reference

Can I install the same rule for multiple platforms?

How do I update a rule I've installed?

What happens if files conflict?

On this page