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 one public command group:
| 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 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 |
--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 |
--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 |
--mode | Chooses diff context: auto, mr, branch, staged, or working-tree. | auto |
--base-ref | Overrides the base ref for branch or mr mode. | unset |
--head-ref | Overrides the head ref for branch or mr 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 |
Practical Guidance
- Start with
ai-review test --gitlab-readiness --semantic-readinessbefore enabling stricter delivery or policy gates. - 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.