{"id":42581497,"url":"https://github.com/reporails/cli","last_synced_at":"2026-04-15T17:01:51.947Z","repository":{"id":334750540,"uuid":"1140003613","full_name":"reporails/cli","owner":"reporails","description":"Check if your AI coding instructions are clear, complete, and likely to work. Based on reporails/rules. Supports CLAUDE.md, AGENTS.md, and more.","archived":false,"fork":false,"pushed_at":"2026-04-15T12:22:12.000Z","size":1791,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-15T12:27:53.474Z","etag":null,"topics":["ai-coding","claude-code","cli","code-quality","developer-tools","llm","mcp","validation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/reporails.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"reporails"}},"created_at":"2026-01-22T17:44:25.000Z","updated_at":"2026-04-14T22:42:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/reporails/cli","commit_stats":null,"previous_names":["reporails/cli"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/reporails/cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reporails%2Fcli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reporails%2Fcli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reporails%2Fcli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reporails%2Fcli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reporails","download_url":"https://codeload.github.com/reporails/cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reporails%2Fcli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31851057,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"ssl_error","status_checked_at":"2026-04-15T15:24:39.138Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-coding","claude-code","cli","code-quality","developer-tools","llm","mcp","validation"],"created_at":"2026-01-28T22:09:44.666Z","updated_at":"2026-04-15T17:01:51.942Z","avatar_url":"https://github.com/reporails.png","language":"Python","readme":"# Reporails CLI\n\nAI instruction diagnostics for coding agents. Validates instruction files for Claude, Codex, Copilot, Gemini, and Cursor against 90+ deterministic rules.\n\n### Beta — limited 100 spots, free until GA. Moving fast, feedback welcome.\n\n## Quick Start\n\n```bash\nnpx @reporails/cli check\n# or\nuvx reporails-cli check\n```\n\nNo install needed. Or install globally:\n\n```bash\nnpm install -g @reporails/cli    # adds `ails` to PATH\n# or\npip install reporails-cli        # same, via Python\n```\n\nThen just:\n\n```bash\nails check\n```\n\nYou'll get a score, level, and actionable findings:\n\n```\nReporails — Diagnostics\n\n  ┌─ Main (1)\n  │ CLAUDE.md  12 dir / 5 con · 60% prose\n  │   ⚠ L1     No NEVER or AVOID statements found  CORE:C:0003\n  │   ○ L1     No version or date marker found  CORE:C:0012\n  │\n  └─ 3 findings\n\n  ── Summary ──────────────────────────────────────────────\n\n  Score: 7.2 / 10  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░  (0.3s)\n  Agent: Claude\n\n  Scope:\n    capabilities: 1 main\n    instructions: 12 directive / 5 prose (28%)\n                  5 constraint\n\n  3 findings · 0 errors · 2 warnings · 1 info\n\n  Full diagnostics free for the first 100 registering users during beta\n  ails auth login\n```\n\nFix the issues, run again, watch your score improve.\n\n## Install\n\n```bash\n# Node.js (recommended — no separate Python install needed)\nnpm install -g @reporails/cli\n\n# Python\npip install reporails-cli\n\n# Zero install (ephemeral, always latest)\nnpx @reporails/cli check\nuvx reporails-cli check\n```\n\nAll paths add `ails` to your PATH. The npm package auto-installs `uv` if needed — no Python install required.\n\n## Authentication\n\nFree offline diagnostics work without an account. For server-enhanced diagnostics (cross-file analysis, reinforcement detection, compliance scoring), sign up for the beta:\n\n```bash\nails auth login       # GitHub Device Flow — authorize in browser\nails auth status      # Check your current auth state\nails auth logout      # Remove stored credentials\n```\n\nCredentials are stored in `~/.reporails/credentials.yml`.\n\n## Commands\n\n```bash\nails check                      # Validate your instruction files\nails check -f json              # JSON output\nails check -f github            # GitHub Actions annotations\nails check --strict             # Exit 1 if violations found\nails check --agent claude       # Agent-specific rules only\nails check --exclude-dir vendor # Exclude directory from scanning\nails check -v                   # Verbose: per-file PASS/FAIL with rule titles\n\nails explain CORE:S:0001        # Explain a specific rule\nails heal                       # Interactive auto-fix for violations\nails install                    # Install MCP server for detected agents\nails version                    # Show version info\n```\n\n### Exit codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success |\n| 1 | Violations found (strict mode) |\n| 2 | Invalid input (bad path, unknown agent/format/rule) |\n\n## Supported Agents\n\n| Agent | Instruction files |\n|-------|-------------------|\n| Claude | `CLAUDE.md`, `.claude/rules/*.md`, `.claude/skills/*/SKILL.md` |\n| Codex | `AGENTS.md`, `CODEX.md`, `agents/*.md` |\n| Copilot | `copilot-instructions.md`, `.github/copilot-instructions.md` |\n| Gemini | `GEMINI.md`, `.gemini/rules/*.md` |\n| Cursor | `.cursorrules`, `.cursor/rules/*.md` |\n\nThe CLI auto-detects which agents are present in your project.\n\n## Configuration\n\nProject config in `.ails/config.yml`:\n\n```yaml\ndefault_agent: claude          # Default agent (run: ails config set default_agent claude)\nexclude_dirs: [vendor, dist]   # Directories to skip\ndisabled_rules: [CORE:C:0010]  # Rules to disable\n```\n\nSet values via CLI: `ails config set \u003ckey\u003e \u003cvalue\u003e`\n\n### Global defaults\n\nGlobal config in `~/.reporails/config.yml` applies to all projects. Project config overrides global.\n\n```bash\nails config set --global default_agent claude\n```\n\n## GitHub Actions\n\nAdd `ails check` as a CI gate with inline PR annotations:\n\n```yaml\n# .github/workflows/reporails.yml\nname: Reporails\non:\n  pull_request:\n    paths: ['CLAUDE.md', '.claude/**', 'AGENTS.md', '.cursorrules']\njobs:\n  check:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - run: pip install reporails-cli\n      - run: ails check . --format github --strict\n```\n\n## What It Checks\n\n90+ rules across six categories:\n\n- **Structure** — File organization, discoverability, size limits\n- **Content** — Clarity, specificity, reinforcement patterns, anti-patterns\n- **Context Quality** — Tech stack, project description, domain terminology\n- **Efficiency** — Token usage, import depth, instruction elaboration\n- **Maintenance** — Versioning, review processes\n- **Governance** — Security policies, credential protection, permissions\n\n## Levels [* under re-evaluation *]\n\nLevels describe what your AI instruction setup enables.\n\n| Level | Name | What It Enables |\n|-------|------|-----------------|\n| L0 | Absent | No instruction file |\n| L1 | Present | A non-trivial, tracked instruction file exists |\n| L2 | Structured | Project-specific constraints, focused content |\n| L3 | Substantive | Modular guidance with external references |\n| L4 | Actionable | Instructions adapt based on code location |\n| L5 | Refined | Structurally sound, governed, navigable |\n| L6 | Adaptive | Agent dynamically discovers context and extends capabilities |\n\n## Offline vs Server\n\n| Feature | Unauthenticated | Authenticated                         |\n|---------|-----------------|---------------------------------------|\n| Mechanical rules | 70+ rules       | 70+ rules                             |\n| Deterministic rules | 20+ rules       | 20+ rules                             |\n| Cross-file analysis | -               | Conflicts, repetition                 |\n| Reinforcement detection | -               | Orphan instructions, topic clustering |\n| Compliance scoring | -               | Per-instruction strength              |\n| Rate limit | -               | 10/hour (beta)                        |\n\n## Performance\n\nFirst run downloads the embedding model (~90MB) to cache. Subsequent runs start in under 2 seconds for typical projects.\n\n## Rules\n\nRules are bundled with the CLI — no separate install or download needed. See [reporails.com/rules](https://reporails.com/rules) for the full rule reference.\n\n## License\n\n[BUSL 1.1](LICENSE) — converts to Apache 2.0 three years after each release.\n","funding_links":["https://github.com/sponsors/reporails"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freporails%2Fcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freporails%2Fcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freporails%2Fcli/lists"}