Command reference

CLI reference

17 commands. Start with an example; expand the options when you need them.

Run from your repository root. Installation and rule activation · JSON contracts

`repo-standards baseline`

Print baseline JSON from exact Git evidence without writing files.

repo-standards baseline .

Arguments and options (6)

root

Path · optional

Default: "."

--manifest

str · optional

Default: ".repo-standards/repository.toml"

--as-of

str · optional

Deterministic YYYY-MM-DD

--staged

bool · optional

Read the staged Git index instead of the committed HEAD tree.

Default: false

--enable-rule

list · optional

--ratchet-warnings

bool · optional

Include active warnings in the reviewed baseline.

Default: false

`repo-standards capabilities`

Describe the stable machine capabilities without inspecting a repository.

repo-standards capabilities

`repo-standards catalog`

Export the deterministic public product, rule, command, and schema catalog.

repo-standards catalog

`repo-standards check`

Analyze one repository manifest.

repo-standards check . --staged

Usage notes

Without a nonempty rule selection, reject undeclared JavaScript and bespoke verifier scripts. Use .mts for ESM tooling and .cts for CommonJS. The untyped-javascript rule reviews .js, .jsx, .mjs and .cjs case-insensitively; typed variants and source maps remain outside this rule. A nonempty enabled_rules list or --enable-rule selects the requested rules instead. Migrations must update loaders, callers, type checks and runtime tests. Typed tool presets such as eslint.strict.ts need no JavaScript artifact declaration. Prefer a tool's supported TypeScript preset over declaring its generated JavaScript output solely to satisfy this policy.

Required JavaScript uses exact [[javascript.artifacts]] records in the manifest: path, kind and a nonblank reason. Allowed kinds are tool-config, generated, vendor, fixture and runtime. Only generated requires and accepts source: a distinct tracked non-JavaScript file, including Python or schemas. Paths are literal Git paths; wildcard characters never expand patterns. Paths must be canonical repository-relative regular files in the selected Git tree or index. Globs, duplicates, stale paths and over 1,000 records fail. Names and folders grant no exemptions. Declarations record intent; they prove neither generation nor runtime necessity. No application code runs. Independent verifier and operational-test rules still apply.

Warnings remain advisory in strict/report mode. To block new warnings, first resolve violations and review required artifact declarations. Print native JSON with `repo-standards baseline . --ratchet-warnings`, review it, then commit it at .repo-standards/baseline.json. Run this command with --mode ratchet --ratchet-warnings; use --staged on both for exact index input. Baseline creation explicitly accepts eligible current findings. Its optional include_warnings setting defaults to false for existing schema-2 baselines. Comparison settings must match; stale scope, policy and entries fail closed. Warning opt-in covers all enabled rules without changing their severity. Uncappable rules remain uncappable. Use `repo-standards schema baseline` for the wire format. Python callers create baselines with baseline_from_report(report, include_warnings=True), serialize with baseline_dict, and analyze with RepositoryAnalysisRequest using both selection=RatchetAnalysis(baseline_path, include_warnings=True).

Arguments and options (10)

root

Path · optional

Default: "."

--manifest

str · optional

Default: ".repo-standards/repository.toml"

--baseline

str · optional

Default: ".repo-standards/baseline.json"

--mode

Mode · optional · report | ratchet | strict

Default: "strict"

--format

OutputFormat · optional · json | pretty-json | text

Default: "text"

--as-of

str · optional

Deterministic YYYY-MM-DD

--base

str · optional

Base for Makefiles and new SQL migrations; staged uses HEAD.

--staged

bool · optional

Analyze the exact staged Git index; ignore unstaged and untracked bytes.

Default: false

--enable-rule

list · optional

Activate a current rule ID for this run.

--ratchet-warnings

bool · optional

Include active warnings in --mode ratchet comparisons.

Default: false

`repo-standards commit-message`

Enforce `[(i/n) ][TICKET] type(scope)!: description` and safely normalize spacing/case.

repo-standards commit-message .git/COMMIT_EDITMSG --fix-safe

Arguments and options (4)

message_file

Path · required

Git commit-message file to validate.

--fix-safe/--no-fix-safe

bool · optional

Apply only verified mechanical header normalization.

Default: false

--format

OutputFormat · optional · json | pretty-json | text

Default: "text"

--advise

bool · optional

Advise on descriptive subject length without blocking.

Default: false

`repo-standards explain`

Explain one immutable rule.

repo-standards explain repository/artifacts/bespoke-iac-verifiers

Arguments and options (1)

rule_id: repo_standards.core.models.RuleId · required

`repo-standards inspect`

Inventory tracked inert repository metadata without requiring a manifest.

repo-standards inspect . --kind workflow

Arguments and options (5)

root

Path · optional

Default: "."

--kind

str · optional

Filter: all, project, workflow, cloudbuild, dockerfile, terraform, openapi.

Default: "all"

--path-prefix

str · optional

Filter by repository path prefix.

--limit

str · optional

Page size from 1 through 500.

Default: "100"

--cursor

str · optional

Opaque cursor returned by the prior page.

`repo-standards pull-request commits`

Require concise PR history or one complete explicitly numbered series.

repo-standards pull-request commits . --advisory

Arguments and options (12)

root

Path · optional

Default: "."

--base

str · optional

Exact pull-request base revision.

Default: ""

--head

str · optional

Exact pull-request head revision.

Default: "HEAD"

--base-ref

str · optional

Pull-request base ref name.

--head-ref

str · optional

Pull-request head ref name.

--repository-id

repo_standards.core.models.RepositoryId · optional

Exact PR head owner/name identity used by transition exemptions.

--max-commits

int · optional

Maximum unnumbered non-merge commits.

Default: 5

--transition-exemption

list · optional

Trusted JSON transition exemption; repeat for multiple transitions.

--github-event

Path · optional

GitHub Actions event payload containing exact pull-request evidence.

--advisory

bool · optional

Report policy findings without a nonzero policy exit.

Default: false

--quiet

bool · optional

Suppress output only when analysis completes successfully.

Default: false

--format

OutputFormat · optional · json | pretty-json | text

Default: "text"

`repo-standards pull-request documentation`

Reject new README/docs content and enforce the trusted Markdown page budget.

repo-standards pull-request documentation . --base origin/main

Arguments and options (4)

root

Path · optional

Default: "."

--base

str · optional

Trusted base revision used for policy.

Default: ""

--head

str · optional

Head revision to compare with the base.

Default: "HEAD"

--format

OutputFormat · optional · json | pretty-json | text

Default: "text"

`repo-standards pull-request review-policy`

Require short prose, well-formed examples, isolated migrations and human consensus.

Use the Review Policy Action to collect trusted provider evidence. --base and --head require full commit SHAs.

Usage notes

Defaults: 2,000 total characters and 500 prose characters. Use closed, language-tagged code fences when examples help explain the change.

The total includes Markdown and comments. Migration-only PRs and declared domain roots need current human approval. Coupling other files requires a tracked migration_exception with reason, alternatives, and every coupled path, plus two human approvals on this head. Trusted promotion exemptions preserve their existing scope behavior.

Arguments and options (6)

root

Path · optional

Default: "."

--base

str · optional

Exact trusted base commit SHA.

Default: ""

--head

str · optional

Exact evaluated pull-request head commit SHA.

Default: ""

--evidence

Path · optional

Strict, complete provider evidence JSON.

--manifest

Path · optional

Explicit trusted manifest; defaults to the manifest in --base.

--generated-attribute

str · optional

Git attribute that marks repository-specific excluded artifacts.

Default: "pr-size-excluded"

`repo-standards pull-request size`

Count authored production and test churn; exclude declared generated artifacts.

repo-standards pull-request size . --base origin/main

Usage notes

Test categories describe paths, not a review-cost exemption. Review each case: each case should protect a distinct contract, regression, boundary, interaction, or lifecycle. Consolidate equivalent cases into readable named tables and reuse owned fixtures; preserve independent oracles, case isolation, and safety checks. Coverage percentages and test counts alone do not justify another case.

Counted review lines include production and test categories, including support and configuration. Churn measures additions plus deletions, not net LOC.

Source-semantic test-quality checks belong to Code Standards. Do not infer quality from a test filename, file length, or the excluded-line count.

Arguments and options (6)

root

Path · optional

Default: "."

--base

str · optional

Trusted base revision used for diff and policy.

Default: ""

--head

str · optional

Head revision to compare with the base.

Default: "HEAD"

--generated-attribute

str · optional

Git attribute that marks repository-specific excluded artifacts.

Default: "pr-size-excluded"

--report-path

Path · optional

Write the complete canonical JSON report to this path.

--format

OutputFormat · optional · json | pretty-json | text

Default: "text"

`repo-standards pull-request text`

Preview default description budgets without Git or provider evidence; warnings exit zero.

repo-standards pull-request text PR_BODY.txt --title "docs: clarify setup"

Arguments and options (3)

body_file: Path · required
UTF-8 file containing the proposed PR body.
--format: OutputFormat · optional · json | pretty-json | text
Default: "text"
--title: str · optional
Proposed single-line PR title.

`repo-standards report`

Analyze one manifest without blocking on completed policy findings.

repo-standards report . --format json

Arguments and options (6)

root: Path · optional
Default: "."
--manifest: str · optional
Default: ".repo-standards/repository.toml"
--format: OutputFormat · optional · json | pretty-json | text
Default: "text"
--as-of: str · optional
Deterministic YYYY-MM-DD
--base: str · optional
Compare Makefiles and new SQL migrations to this commit.
--enable-rule: list · optional
Activate a current rule ID for this run.

`repo-standards rest discover`

Discover committed OpenAPI entry candidates without importing application code.

repo-standards rest discover .

Arguments and options (1)

root: Path · optional
Default: "."

`repo-standards rest doctor`

Return the installed capability handshake and inert repository detection.

repo-standards rest doctor .

Arguments and options (1)

root: Path · optional
Default: "."

`repo-standards rules`

List installed policy rules as bounded deterministic JSON.

repo-standards rules --severity error

Arguments and options (4)

--rule-prefix

str · optional

Filter rule IDs by prefix.

--severity

str · optional

Filter by warning or error.

--limit

str · optional

Page size from 1 through 500.

Default: "100"

--cursor

str · optional

Opaque cursor returned by the prior page.

`repo-standards schema`

Print repository report, baseline or catalog JSON Schema.

repo-standards schema report

Arguments and options (1)

document: str · optional
Default: "report"