CLI Reference
Public reference for the shipped PatchPatrol CLI surface.
CLI Reference
Use this page when you need the exact public command-line contract for the shipped PatchPatrol workflow.
Source of truth: this page is derived from shipped PatchPatrol contracts in patchpatrol/cli.py and live ai-review help output for the supported commands.
Use the configuration reference for environment variables and the policy controls page when you are deciding how strict delivery or gating should be.
Command Group
Top-level help exposes these public commands and command groups:
| Command | Public purpose |
|---|---|
ai-review run | Runs the PatchPatrol review pipeline against a selected diff context and writes artifacts. |
ai-review test | Runs bounded provider readiness checks and optional CI preflight checks without doing a full review. |
ai-review license inspect | Validates the configured Self-Hosted License and emits non-sensitive machine-readable status without running review work. |
ai-review run
Use ai-review run when you want PatchPatrol to resolve review context, build a bounded chunk plan, call the configured provider, and write artifacts.
ai-review run [options]| Flag | Public meaning | Default source or posture |
|---|---|---|
--output-dir | Overrides where PatchPatrol writes review artifacts. | AI_REVIEW_OUTPUT_DIR or .ai-review |
--model | Overrides the model used for review. | AI_REVIEW_MODEL |
--provider | Overrides the provider path. | AI_REVIEW_PROVIDER |
--ollama-host | Overrides the Ollama endpoint for this run. | OLLAMA_HOST |
--openai-base-url | Overrides the OpenAI-compatible base URL for this run. | OPENAI_BASE_URL |
--feedback-mode | Chooses artifact-only, mr, or mr-manual delivery for the run. | AI_REVIEW_FEEDBACK_MODE |
--remediation-mode | Chooses optional advisory remediation output: off, briefs, or suggestions. | AI_REVIEW_REMEDIATION_MODE |
--gitlab-inline-discussions / --no-gitlab-inline-discussions | Turns owned inline GitLab discussions on or off while leaving summary-note delivery intact. | AI_REVIEW_GITLAB_INLINE_DISCUSSIONS |
--allow-draft-mr-feedback / --no-allow-draft-mr-feedback | Allows or suppresses MR delivery on draft or WIP merge requests for this run. | AI_REVIEW_ALLOW_DRAFT_MR_FEEDBACK |
--manual-feedback-authorized / --no-manual-feedback-authorized | Explicitly authorizes or denies manual MR delivery when --feedback-mode mr-manual is used. | AI_REVIEW_MANUAL_FEEDBACK_AUTHORIZED |
--incremental-mode | Chooses GitLab MR incremental review behavior: auto, always, or never. | AI_REVIEW_INCREMENTAL_MODE |
--fail-on | Applies the configured severity gate: none, blocker, high, or medium. | AI_REVIEW_FAIL_ON |
--max-diff-bytes | Caps total diff bytes selected for review. | AI_REVIEW_MAX_DIFF_BYTES |
--max-files | Caps how many changed files PatchPatrol reviews. | AI_REVIEW_MAX_FILES |
--max-chunks | Caps how many reviewable chunks PatchPatrol keeps after filtering. | AI_REVIEW_MAX_CHUNKS |
--max-file-diff-bytes | Caps diff size per file chunk and omits oversized files. | AI_REVIEW_MAX_FILE_DIFF_BYTES |
--enable-final-summary | Enables the optional summary-only refinement pass. | Disabled unless AI_REVIEW_ENABLE_FINAL_SUMMARY=true |
--enable-review-lenses / --no-enable-review-lenses | Enables or suppresses optional high-stakes review lens passes for this run. | AI_REVIEW_ENABLE_LENSES |
--review-lenses | Comma-separated lens allowlist for enabled lens passes. | AI_REVIEW_LENSES |
--html-report / --no-html-report | Enables or suppresses additive ai-review.html generation for the current run. | AI_REVIEW_HTML_REPORT |
--mode | Chooses diff context: auto, mr, github-pr, branch, staged, or working-tree. | auto |
--base-ref | Overrides the base ref for branch, mr, or github-pr mode. | unset |
--head-ref | Overrides the head ref for branch, mr, or github-pr mode. | unset |
--dry-run | Prints the resolved diff context and chunk plan, then exits before provider review. | off |
ai-review test
Use ai-review test when you want a bounded preflight for provider connectivity, model availability, or CI readiness before a full review run.
ai-review test [options]| Flag | Public meaning | Default source or posture |
|---|---|---|
--model | Overrides the model used for readiness checks. | AI_REVIEW_MODEL |
--provider | Overrides the provider path for readiness checks. | AI_REVIEW_PROVIDER |
--ollama-host | Overrides the Ollama endpoint for this preflight. | OLLAMA_HOST |
--openai-base-url | Overrides the OpenAI-compatible base URL for this preflight. | OPENAI_BASE_URL |
--timeout-seconds | Sets an HTTP timeout for the test call. | AI_REVIEW_TIMEOUT_SECONDS or OLLAMA_TIMEOUT_SECONDS |
--chat | Adds a lightweight chat-completion check using the configured model. | off |
--prompt | Supplies the prompt used with --chat. | Reply with OK. |
--dry-run | Prints which checks would run without contacting external systems. | off |
--gitlab-readiness | Validates GitLab merge-request note context readiness from environment variables. | off |
--semantic-readiness | Runs bounded semantic-runtime readiness checks for the current repository. | off |
--readiness-json | Emits one parseable readiness.metadata JSON line after the human-readable readiness output. | off |
Readiness output stays human-readable by default. Each check.* line includes a
stable reason code and, for not-ready provider checks, a category such as
configuration, license, trust_gate_blocked, network_connectivity,
model_unavailable, authentication, structured_output_unsupported, or
transport_retry_exhausted. Use --readiness-json when CI automation needs the
same result as structured metadata.
ai-review license inspect
Use ai-review license inspect to validate the Self-Hosted License supplied by
PATCHPATROL_LICENSE or PATCHPATROL_LICENSE_FILE without extracting review
context or calling a provider.
ai-review license inspect --jsonThe --json flag is required. The command emits non-sensitive License Status,
reason codes, and trusted entitlement claims; it never emits the raw Signed
License, signature, or private key. It exits 0 when the license is valid and
uses exit 12 for every other status, including missing, invalid, expired,
not-yet-valid, or unsupported licenses.
Use the configuration reference for source and ambiguity behavior, and Troubleshooting for the complete status and reason-code recovery table.
Practical Guidance
- Start with
ai-review test --chat --readiness-jsonfor artifact-only provider readiness, and providePATCHPATROL_LICENSEorPATCHPATROL_LICENSE_FILEwhen the probe calls a real provider. - Add
ai-review test --gitlab-readiness --readiness-jsonbefore enabling MR feedback delivery. - Run
ai-review license inspect --jsonafter wiring a Self-Hosted License and before the first real-provider review. - Use
ai-review run --dry-runwhen you want to inspect diff selection without calling a provider. - Keep environment-variable detail in the configuration reference instead of repeating it in command invocations.
Return to Reference.