CLI reference

Postil is one binary, postil. Seven commands cover the whole workflow: review a diff, reply to a mention, dry-run a config change, inspect the resolved config, scaffold one, verify your setup, and install the pre-push hook.

Remote review supports GitHub, GitLab, Bitbucket, and Azure DevOps via --forge. Bitbucket and Azure DevOps support is early: shipped and covered by tests, but not yet validated against live instances.

`postil review`

Review a diff — a PR/MR on a forge, or local changes — and emit findings, comments, and a gate verdict.

Flag	Description
`--staged`	Review staged changes (git diff --cached).
`--base <ref>`	Review changes since a base ref (git diff base...HEAD).
`--diff-file <path>`	Review a unified diff from a file.
`--forge <forge>`	Code host for remote review: github, gitlab, bitbucket, azure, or local. Inferred as github when --repo is set.
`--repo <repo>`	Repository as owner/name (GitHub) or group/project (GitLab).
`--pr <n>`	Pull/merge request number (also used for GitLab MRs).
`--sha <sha>`	Head SHA to report checks against (defaults to the PR head).
`--since-sha <sha>`	Incremental review: only commits since this SHA.
`--baseline <path>`	Previous review envelope for finding reconciliation.
`--fail-on <severity>`	Exit 1 at/above this severity: info, warn, error, or never. Overrides gate.failOn.
`--config <path>`	Explicit config file (bypasses discovery).
`--model <id>`	Model override (else REVIEW_MODEL, else config, else default).
`--output-json`	Print the envelope JSON on stdout (machine consumers).
`--sarif <path>`	Write SARIF 2.1.0 to this path for code-scanning ingestion.
`--no-post`	Do not post comments or checks to the forge; report locally only.

`postil respond`

Reply to an @postil mention on a pull request or issue (the interactive bot). GitHub and GitLab cover issues and PRs/MRs; Bitbucket and Azure DevOps cover pull requests only. Review-and-answer only: it never opens PRs or pushes commits.

Flag	Description
`--forge <forge>`	Code host: github, gitlab, bitbucket, or azure (default github). GitHub and GitLab accept --pr or --issue; Bitbucket and Azure DevOps accept --pr only.
`--repo <repo>`	Repository as owner/name.
`--pr <n>`	Pull request number the mention is on.
`--issue <n>`	Issue number the mention is on.
`--comment <text>`	The maintainer's message text. Falls back to the POSTIL_COMMENT environment variable; prefer that in automation.
`--config <path>`	Explicit config file (bypasses discovery).
`--model <id>`	Model override for this reply.
`--no-post`	Print the reply instead of posting it.

`postil plan`

Replay stored envelopes under a candidate config: what would change? No model calls, no API spend.

Flag	Description
`--envelopes <dir>`	Directory of envelope JSON files from previous reviews. Required.
`--config <path>`	Candidate config file to evaluate (defaults to discovery).

`postil config`

Print the resolved configuration and where each value came from (flag, environment, file, or default).

`postil init`

Write a starter .postil.yaml.

Flag	Description
`--force`	Overwrite an existing .postil.yaml.

`postil doctor`

Validate endpoint, key, model, and repo setup with actionable errors. Run it before your first review.

Flag	Description
`--config <path>`	Explicit config file to validate.

`postil hook`

Manage git hooks. postil hook install adds a pre-push hook that reviews outgoing commits.

Flag	Description
`install --force`	Overwrite an existing pre-push hook on install.

Environment variables

Variable	Purpose
`POSTIL_API_KEY`	LLM API key for any OpenAI-compatible endpoint; falls back to OPENROUTER_API_KEY.
`OPENROUTER_API_KEY`	Inference key for the default OpenRouter provider.
`POSTIL_API_BASE`	OpenAI-compatible base URL (default https://openrouter.ai/api/v1).
`REVIEW_MODEL`	Model id override.
`REVIEW_MODEL_CASCADE`	Comma-separated fallback models.
`GITHUB_TOKEN`	Token for GitHub remote review and comment posting.
`GITHUB_API_URL`	Base URL for GitHub Enterprise Server.
`GITLAB_TOKEN`	Project or group access token for GitLab remote review.
`GITLAB_API_URL`	Base URL for self-managed GitLab (e.g. https://gitlab.example.com/api/v4).
`BITBUCKET_TOKEN`	Token for Bitbucket; set BITBUCKET_USER too to use an app password.
`BITBUCKET_API_URL`	Base URL for Bitbucket Data Center.
`AZURE_DEVOPS_TOKEN`	Azure DevOps personal access token.
`AZURE_DEVOPS_API_URL`	Base URL for Azure DevOps Server.

Postil talks to any OpenAI-compatible endpoint through POSTIL_API_BASE; there are no provider-specific key variables beyond POSTIL_API_KEY / OPENROUTER_API_KEY.

Exit codes

Code	Meaning
`0`	Clean, or all findings below the gate threshold.
`1`	Gate-failing findings at or above the threshold.
`2`	Operational error. Never reported as a pass.

Examples

# review staged changes locally
postil review --staged

# review a branch against main, fail only on errors
postil review --base main --fail-on error

# review a GitHub PR and print the envelope
postil review --repo owner/name --pr 4127 --output-json

# review a GitLab MR on a self-managed instance
export GITLAB_TOKEN=glpat-...
export GITLAB_API_URL=https://gitlab.example.com/api/v4
postil review --forge gitlab --repo group/project --pr 88

# write SARIF for code-scanning ingestion
postil review --repo owner/name --pr 4127 --sarif postil.sarif

# incremental re-review: only commits since the last reviewed head
postil review --repo owner/name --pr 4127 \
  --since-sha <last-reviewed-head> --baseline previous-envelope.json

# reply to an @postil mention without posting (dry run)
postil respond --repo owner/name --pr 123 \
  --comment "@postil is this safe?" --no-post

# dry-run a candidate config against stored envelopes
postil plan --envelopes .cache/envelopes --config .postil.candidate.yaml

# verify setup before the first review
postil doctor

See the quickstart for first-run setup and configuration for the full .postil.yaml reference.