Reporails CLI

AI instruction diagnostics for coding agents. Validates instruction files for Claude, Codex, Copilot, Gemini, and Cursor against 90+ deterministic rules.

Beta — limited 100 spots, free until GA. Moving fast, feedback welcome.

Quick Start

npx @reporails/cli check
# or
uvx reporails-cli check

No install needed. Or install globally:

npm install -g @reporails/cli    # adds `ails` to PATH
# or
pip install reporails-cli        # same, via Python

Then just:

ails check

You'll get a score, level, and actionable findings:

Reporails — Diagnostics

  ┌─ Main (1)
  │ CLAUDE.md  12 dir / 5 con · 60% prose
  │   ⚠ L1     No NEVER or AVOID statements found  CORE:C:0003
  │   ○ L1     No version or date marker found  CORE:C:0012
  │
  └─ 3 findings

  ── Summary ──────────────────────────────────────────────

  Score: 7.2 / 10  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░  (0.3s)
  Agent: Claude

  Scope:
    capabilities: 1 main
    instructions: 12 directive / 5 prose (28%)
                  5 constraint

  3 findings · 0 errors · 2 warnings · 1 info

  Full diagnostics free for the first 100 registering users during beta
  ails auth login

Fix the issues, run again, watch your score improve.

Install

# Node.js (recommended — no separate Python install needed)
npm install -g @reporails/cli

# Python
pip install reporails-cli

# Zero install (ephemeral, always latest)
npx @reporails/cli check
uvx reporails-cli check

All paths add ails to your PATH. The npm package auto-installs uv if needed — no Python install required.

Authentication

Free offline diagnostics work without an account. For server-enhanced diagnostics (cross-file analysis, reinforcement detection, compliance scoring), sign up for the beta:

ails auth login       # GitHub Device Flow — authorize in browser
ails auth status      # Check your current auth state
ails auth logout      # Remove stored credentials

Credentials are stored in ~/.reporails/credentials.yml.

Commands

ails check                      # Validate your instruction files
ails check -f json              # JSON output
ails check -f github            # GitHub Actions annotations
ails check --strict             # Exit 1 if violations found
ails check --agent claude       # Agent-specific rules only
ails check --exclude-dir vendor # Exclude directory from scanning
ails check -v                   # Verbose: per-file PASS/FAIL with rule titles

ails explain CORE:S:0001        # Explain a specific rule
ails heal                       # Interactive auto-fix for violations
ails install                    # Install MCP server for detected agents
ails version                    # Show version info

Exit codes

Supported Agents

The CLI auto-detects which agents are present in your project.

Configuration

Project config in .ails/config.yml:

default_agent: claude          # Default agent (run: ails config set default_agent claude)
exclude_dirs: [vendor, dist]   # Directories to skip
disabled_rules: [CORE:C:0010]  # Rules to disable

Set values via CLI: ails config set <key> <value>

Global defaults

Global config in ~/.reporails/config.yml applies to all projects. Project config overrides global.

ails config set --global default_agent claude

GitHub Actions

Add ails check as a CI gate with inline PR annotations:

# .github/workflows/reporails.yml
name: Reporails
on:
  pull_request:
    paths: ['CLAUDE.md', '.claude/**', 'AGENTS.md', '.cursorrules']
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install reporails-cli
      - run: ails check . --format github --strict

What It Checks

90+ rules across six categories:

• Structure — File organization, discoverability, size limits
• Content — Clarity, specificity, reinforcement patterns, anti-patterns
• Context Quality — Tech stack, project description, domain terminology
• Efficiency — Token usage, import depth, instruction elaboration
• Maintenance — Versioning, review processes
• Governance — Security policies, credential protection, permissions

Levels [* under re-evaluation *]

Levels describe what your AI instruction setup enables.

Offline vs Server

Performance

First run downloads the embedding model (~90MB) to cache. Subsequent runs start in under 2 seconds for typical projects.

Rules

Rules are bundled with the CLI — no separate install or download needed. See reporails.com/rules for the full rule reference.

License

BUSL 1.1 — converts to Apache 2.0 three years after each release.