Documentation

Postil is one Rust binary (postil) and a thin control plane around it. These pages cover everything from the first local review to running the whole stack on your own hardware.

Quickstart

Install the CLI, review your first staged diff, and wire up the GitHub App or Action.

Configuration

The full .postil.yaml reference, including CodeRabbit config translation (reads .coderabbit.yaml).

CLI reference

Every command and flag: review, respond, plan, config, init, doctor, hook, plus environment variables and exit codes.

The gate

postil/gate semantics, fail-on thresholds, and how to require it in branch protection.

postil plan

Dry-run a config change against stored envelopes before deploying it. No model calls.

Envelope schema

The JSON contract between the CLI and everything else: findings, counts, gate, usage.

GitLab

Run Postil on GitLab.com and self-managed: CI job, project tokens, and merge-request review.

Self-hosted

Docker Compose quickstart in under 15 minutes, with OpenRouter, Azure, and Ollama examples.

The short version

# local
curl -fsSL https://postil.dev/install.sh | sh
# or: cargo install --git https://github.com/postil-dev/postil-cli --locked
postil doctor            # verify endpoint, key, and model
postil review --staged

# CI (GitHub Actions) — @v1 resolves after the first tagged release
- uses: postil-dev/postil-action@v1
  with:
    cli-ref: <40-hex postil-cli SHA>

# hosted
Install the GitHub App; reviews start on the next PR.

Exit codes: 0 clean or below the gate threshold, 1 gate-failing findings, 2 operational error. Postil never reports an operational error as a pass.