Getting Started

Quick start

From the root of any repository that has at least one instruction file (CLAUDE.md, AGENTS.md, .cursorrules, .github/copilot-instructions.md, or GEMINI.md) — no install, no account:

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

You'll see something like this:

Reporails — Diagnostics

  ┌─ Main (1)  4 directive / 3 constraint · 50% prose
  │ CLAUDE.md  4 dir / 3 con · 50% prose
  │   ⚠ L9    Missing directory layout — show the project structure  CORE:C:0035
  │   ⚠ L23   7 of 7 instruction(s) lack effective reinforcement  CORE:C:0053
  │     ... and 19 more
  │     1 misordered · 1 orphan · 1 ambiguous
  │
  └─ 21 findings

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

  Score: 7.9 / 10  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░  (1.3s)
  Agent: Claude

  Scope:
    instructions: 4 directive / 7 prose (50%)
                  3 constraint

  21 findings · 4 warnings · 1 info

Three things to read first:

• Score — closer to 10 is better. See the Score Guide for what each band means.
• Findings list — each row is a rule that fired. Run ails explain CORE:C:0035 (or whichever rule ID) to see what the rule checks for and how to fix it.
• Scope summary — counts of directives, constraints, and prose detected. If a number looks wrong (e.g., zero directives), your instructions are probably written as prose rather than as commands the agent can act on.

Install permanently

npx @reporails/cli install
# or
uvx --from reporails-cli ails install

Either command does two things:

1. Puts the ails binary on your PATH
2. Writes a one-line ~/.reporails/config.yml with sensible defaults

After this, ails check runs from anywhere without the npx / uvx prefix.

Configure (optional)

Reporails auto-detects which agent rules to run based on the base config files present in your repo, so most projects need no setup. You may want to pin a default if your repo has multiple agents (CLAUDE.md + .cursorrules + AGENTS.md) and you want to bias toward one of them:

ails config set --global default_agent claude

Per-repo overrides, severity tweaks, and rule disables live in .ails/config.yml — see Configuration for the full surface.

Authenticate (optional, for full diagnostics)

The anonymous tier works without an account and is enough to see whether your instructions are working. Sign in to raise your request and payload caps and unlock the full diagnostic detail (per-finding fix text and exact cross-file conflict locations):

ails auth login    # browser-based GitHub Device Flow
ails auth status   # show current tier and a redacted key prefix
ails auth token    # print the full API key (for CI export)
ails auth logout   # remove stored credentials

See Tiers and Limits for the side-by-side breakdown, and Configuration → Authentication for the credential-storage and CI specifics.

Common follow-ups

• The score is lower than you expected. Run ails check -v to see all findings (the default output truncates after a per-file budget). Then ails explain CORE:S:0001 (or whichever rule ID) to see the rule body and pass / fail examples. The Score Guide explains what each band means, how per-surface scores roll up, and which rules to fix first for the biggest score improvement.
• You disagree with a rule. Browse reporails.com/rules for the rule's intent before deciding, then either disable it or override its severity in .ails/config.yml — see Configuration → Disabling rules.
• You want this in CI. See the GitHub Actions section in the README and Configuration → Authentication for capturing your API key with ails auth token and wiring it as secrets.REPORAILS_API_KEY.

Useful flags

ails check -v               # verbose — show all findings, not just top per file
ails check -f json          # machine-readable JSON
ails check -f github        # GitHub Actions inline annotations
ails check --strict         # exit code 1 if any finding fires
ails check --agent claude   # only run rules scoped to one agent

The JSON output groups findings under files{path: {findings: [...], count: N}} plus aggregate stats and (when present) cross_file blocks — see Configuration → Output format for the full shape, including which fields are tier-conditional.

Next steps

• Score Guide — what the number means in practice
• Tiers and Limits — anonymous vs signed-in mode, what each includes
• Configuration — tuning rules, agents, exclusions
• FAQ — common questions

← Reporails CLI Documentation · Getting Started · Agent Support →