CLI reference

Run commands from the project root. For a project-local installation, replace coderuler with npx coderuler. Use coderuler --help or coderuler <command> --help for installed-release help.

Version

coderuler --version

Print the installed package version. -V is the short form.

Update

coderuler update

Upgrade the active global npm installation to the latest release. npm must be on PATH. The command uses your npm registry configuration.

Local installations and temporary npx copies cannot self-update. For a project-local npm development dependency, run:

npm install --save-dev @alex-dbs/coderuler@latest

For other installation methods, use the package manager that installed CodeRuler. An npm update failure returns npm’s exit code.

Validate

coderuler validate [rule]

Load and structurally validate rules without evaluating them. The optional rule can be a rule name, module path, or directory. There are no command-specific flags.

For all three selectors, a rule name is the exact filename stem of a discovered rule. Discovery searches project .coderuler/ and home ~/.coderuler/, including subfolders. A name filters discovered rules; an explicit path or directory replaces discovery.

Validation does not execute inline tests or type-check TypeScript. Rule modules still execute as trusted Node.js code when loaded.

Test

coderuler test [rule] [options]

The optional rule is a rule name, module path, or directory. Ordinary tests remain offline, including when --ai also selects live cases. For an AI rule, put every case in aiTests and do not add a separate tests export. --ai-scores only displays scores when AI cases run with --ai. See testing for fixtures and timeout behavior.

Check

coderuler check [path] [options]

The default target is .. A file or folder target narrows selection inside the current project root.

An HTTPS or SSH Git URL loads every rule module from the repository’s default branch. Add #revision to select a branch, tag, or full commit ID. An explicit source replaces project and home discovery, but target paths still refer to the current project.

coderuler check . --rules 'https://github.com/acme/company-rules.git#main'

For rule-name and discovery behavior, see the description under Validate. Tags are space-separated, exact, and case-sensitive. Exclusion takes precedence over inclusion. With no tag flags, check uses every rule. If the filters match no rules, check succeeds with zero rules.

coderuler check src --tags go security --exclude-tags experimental

--json and --jsonl are mutually exclusive. --base requires diff mode or --pr. --auto-comment also requires diff mode or --pr.

Concurrency must be a positive safe integer. Threshold must be a decimal between 0 and 1. AI checks execute live during check, without a separate opt-in flag. See CI and GitHub before using PR checks or comments.

Inspect

coderuler inspect <rule> [folder] [options]

<rule> is a module path or exact discovered name. It selects one rule, not a directory. The folder defaults to ., and becomes the inspected project root.

Choose only one of --json, --jsonl, or --raw. Prices must be finite nonnegative decimals. Inspection runs at concurrency 1 and executes the actual check, including live AI calls.

Dependencies

coderuler deps add <packages...> [options]
coderuler deps remove <names...> [options]
coderuler deps sync [options]

All three commands accept --global or --directory <path>. They are mutually exclusive. Without either, commands manage the project’s .coderuler/ directory.

Add accepts public npm names, versions, ranges, and tags. Remove accepts unversioned direct names. Sync acquires the committed graph and refreshes editor links. See rule dependencies.

Coding-agent skill

coderuler skill install [options]
coderuler skill update [options]

These commands install or refresh the bundled coderuler-new-rule skill for coding agents.

Global and project update flags are mutually exclusive. The default target is the shared universal skills directory. Upgrade CodeRuler before updating to obtain newer bundled content. Local skill sources refresh through skills add, not skills update.

Machine-readable output

Check JSON has this envelope:

{
  "durationMs": 12,
  "reports": []
}

The number is illustrative, not a performance claim. A report contains name, ruleFile, status, durationMs, evaluations, and an optional reason. Each evaluation contains subject and result.

By default, both machine formats include violating rules and violation evaluations only. Add --output-all to include every report and evaluation. A successful default check can therefore have an empty reports array.

Check JSON Lines emits one report per line with type: 'rule'. It has no envelope or final summary record. An all-passing check can produce no JSON Lines records unless --output-all is set.

Inspection JSON uses { events, reports, error?, usage? }. Inspection JSON Lines streams type: 'event', type: 'report', and optional type: 'summary' or type: 'error' records. It includes passes and skips without --output-all.

Check JSON and JSON Lines serialize raw reports. They do not apply the inspection renderer’s text redaction. Treat machine-readable check artifacts as potentially sensitive. Inspection formats are redacted, but still review selected source before sharing output.

Exit codes

A test timeout is an expectation failure and uses 1. A skipped rule is not a violation. Runtime failures are not converted into policy passes.

The authoritative command definitions are in program.ts. Check serializers are in reports.ts, and inspection formats are in inspect-json.ts.