greptile

Greptile code review in your terminal. Runs the same review Greptile posts on your team's pull requests, on your local branch before you push.

• Install
• Quick start
• Commands
• Reviewing
• Authentication
• Sensitive files
• Settings
• Diagrams
• Fix in Claude Code
• Updating
• Reference

Install

# macOS, via Homebrew
brew install greptileai/tap/greptile

# Any platform, via npm
npm install -g greptile

# macOS install script
curl -fsSL https://raw.githubusercontent.com/greptileai/cli/main/install.sh | bash

ℹ️ Note: The npm and script installs need Node 22 or newer.

On macOS, run greptile fix install after installing the CLI to set up Greptile's "Fix in Claude Code" links.

Quick start

greptile login        # opens your browser to sign in
greptile onboard      # creates or configures your Greptile organization
cd path/to/your/repo
greptile review       # reviews HEAD against the default branch

Comments appear in the terminal as they come in.

Commands

| Command | What it does | | --------------------------- | -------------------------------------------------------------------- | | greptile review | Review the current branch against its base. | | greptile review show [ID] | Reopen a previous review. Omit the ID to pick from a list. | | greptile review status | Report the most recent review status for a commit (HEAD by default). | | greptile login | Sign in through your browser, or with --api-key. | | greptile onboard | Create or reconfigure a Greptile organization interactively. | | greptile logout | Remove stored credentials. | | greptile whoami | Show who you are signed in as and your organizations. | | greptile settings | Save default settings (list, get, set, unset, path). | | greptile fix | Set up or remove Fix in Claude Code on macOS. | | greptile update | Update the CLI to the latest version. |

Run any command with --help for its full flag list.

Reviewing

Review against a specific base branch:

greptile review -b main

Show findings beside the changed code instead of as a comment list:

greptile review --diff

Continue a review that stopped partway:

greptile review --resume

Reopen an earlier review:

greptile review show          # pick from recent reviews
greptile review show abc123   # open one by ID

List recent reviews non-interactively (for scripts and agents):

greptile review show --json   # recent reviews, grouped by commit
greptile review show --agent  # the same list as plain text

Check whether the current commit has been reviewed (for a pre-push hook):

greptile review status              # checks HEAD
greptile review status --commit abc123
greptile review status --json

review status exits 0 when the commit has a completed review, 3 while one is still running, 4/5 for a failed/cancelled review, and 1 when there is no review (or you're signed out). Example pre-push hook:

greptile review status; case $? in
  0) ;;                                          # reviewed — allow push
  3) echo "Greptile review still running"; exit 1 ;;
  *) echo "Run 'greptile review' before pushing"; exit 1 ;;
esac

Machine-readable output

greptile review --json > review.json   # structured JSON
greptile review --text                 # plain text (default when piped)
greptile review --agent                # alias for --text, for AI agents

Exit codes are stable for scripting; see Reference.

ℹ️ Note: greptile review show with no ID now prints the recent-reviews list when output is piped or --json/--text/--agent is set (previously it required an interactive terminal). In an interactive terminal it still opens the picker.

Working in multiple organizations

There is nothing to configure. Each repository belongs to one Greptile organization, and greptile review infers it from the repo's remote URL. As long as you're a member of that organization, the review runs against it. greptile whoami lists your organizations.

If you work in a sandboxed environment that routes git through a proxy (for example, remotes shaped like https://<proxy-host>/proxy/github.com/<owner>/<repo>), the CLI unwraps the proxy prefix automatically so the review resolves against the real host.

Authentication

greptile login signs you in through your browser (OAuth) and stores a refreshable token at ~/.greptile/auth.json. Tokens refresh automatically. If the browser can't reach the CLI on the same machine (SSH sessions, containers, remote/cloud dev environments) the browser shows a login code instead; paste it at the Paste code here if prompted: prompt to finish signing in.

For CI or headless environments, use an API key instead. Create one in the Greptile dashboard, then either export it or store it on the machine:

# Per-shell or CI
export GREPTILE_API_KEY=...
greptile review

# Or persist it: prompts for the key, or reads it from stdin
greptile login --api-key
echo "$GREPTILE_API_KEY" | greptile login --api-key

⚠️ Warning: Don't pass the API key as a command-line argument. Arguments are visible in shell history and process lists; use the prompt, stdin, or the environment variable instead.

When GREPTILE_API_KEY is set, it takes precedence over a stored sign-in.

ℹ️ Note: API keys are scoped to an organization, not a person, so reviews run under the organization's identity. Use OAuth sign-in if you want per-developer attribution.

Sensitive files

Before sending anything, greptile review holds back changed files that look like they contain secrets, so a mistakenly committed .env file or private key stays on your machine. When files are held back, the review prints a one-line note naming them. A file is held back when:

• Its name suggests secrets: dotenv files (.env, .env.local, ...), key material and credential stores (*.pem, *.key, *.p12, id_rsa, .npmrc, credentials, ...). Placeholder files like .env.example are fine and still sent.
• Its diff contains a recognizable credential: private keys, or API keys for AWS, GitHub, Slack, Google, Stripe, Anthropic, or OpenAI.
• It matches a .gitignore rule but was committed anyway (force-added, or added before the rule existed). These are held back quietly.

The rest of the review is unaffected. If every changed file is held back, the review stops and tells you.

Including a held-back file

If a file was held back and you do want it reviewed, list it with --include:

greptile review --include .env config/db.pem
greptile review --include .env --include config/db.pem

⚠️ Warning: Files passed to --include skip the sensitive-file check entirely and are sent as-is. Double-check they don't contain real credentials first.

💡 Tip: Two cases that can be surprising:

• A commit that removes a hard-coded secret is also held back, because the removed value still appears in the diff. Use --include to review that cleanup commit.
• A rename away from a sensitive name (say .env to config.txt) is held back too, based on the original path.

Settings

Save defaults instead of repeating flags:

greptile settings set review.layout diff   # always show findings beside the code
greptile settings set review.context 30    # more code around each finding
greptile settings list                     # every setting and where it comes from
greptile settings unset review.layout      # back to the default

| Setting | Values | Matching flag | | ---------------- | --------------------------------------- | ------------------------------------------------------ | | color | true (default), false | --color / --no-color | | review.output | auto (default), text, json | --text / --json | | review.layout | comments (default), diff | --layout (--diff is shorthand for --layout diff) | | review.context | 0 to 60 (default 15) | --context | | review.width | 40 to 240 (default: terminal width) | --width |

A flag passed on the command line always wins over a saved setting for that run.

Settings live in ~/.config/greptile/settings.json (or $XDG_CONFIG_HOME/greptile/settings.json); greptile settings path prints the exact location. The file includes a $schema reference to a published JSON Schema, so editors can validate and autocomplete it if you edit it by hand.

Diagrams

When a review summary includes a Mermaid diagram, greptile renders it inline in kitty and Ghostty, and links an SVG file in other terminals. The first time a diagram renders, greptile downloads a small renderer (mmdr) into ~/.cache/greptile/. Set GREPTILE_NO_AUTO_INSTALL=1 to skip the download.

Fix in Claude Code

On macOS, the CLI can set up the local app used by Greptile's "Fix in Claude Code" links. It maps a repository slug such as owner/repo to its local checkout and submits the full review prompt in your active terminal. Setup is explicit and does not run as part of installing or updating the CLI.

greptile fix install                    # install or repair
greptile fix status                     # human-readable health
greptile fix status --json              # stable fields for scripts
greptile fix uninstall                    # remove app and service; keep mappings
greptile fix uninstall --remove-mappings  # also remove repository folder choices

The first link for a repository opens a Finder folder picker. The selection is saved in ~/.greptile/repos.json. Uninstall preserves these mappings unless you pass --remove-mappings.

The generated URL handler is ~/Applications/Greptile Fix.app. It supports Terminal, Ghostty, iTerm, Warp, kitty, WezTerm, and Alacritty. If Fix in Claude Code is not set up, Greptile falls back to Claude Code's native URL handler. The native handler prefills a shorter prompt and may require you to submit it.

Updating

greptile update

This checks for a newer release and upgrades in place. Homebrew installs are the exception: run brew upgrade greptile instead (the command will tell you). The CLI also checks for updates once a day and prints a notice when one is available; set GREPTILE_NO_UPDATE_CHECK=1 to turn that off.

Reference

Command synopsis

greptile login [--api-key] | logout | whoami
greptile review [-b BRANCH] [--layout comments|diff | --diff] [--resume] [--include PATH...]
                [--json | --text | --agent] [--context LINES] [--width COLUMNS] [--no-color]
greptile review show [ID]   # same output flags as review
greptile review status [--commit REF] [--json | --text | --agent]
greptile settings list | get KEY | set KEY VALUE | unset KEY | path
greptile fix install | status [--json] | uninstall [--remove-mappings]
greptile update

Environment variables

| Variable | What it does | | -------------------------- | --------------------------------------------------------------------- | | GREPTILE_API_KEY | Authenticate with an API key; takes precedence over a stored sign-in. | | GREPTILE_INLINE_IMAGES | Force inline diagrams on (1, true, kitty) or off (0, off). | | GREPTILE_NO_AUTO_INSTALL | Skip the one-time diagram renderer download. | | GREPTILE_NO_UPDATE_CHECK | Skip the daily check for a newer CLI release. | | NO_COLOR | Turn off ANSI color. | | FORCE_COLOR | Turn on ANSI color even when output is piped. | | COLUMNS | Override the output width. |

Exit codes

| Code | Meaning | | ----- | -------------------------------------------------------------------------------- | | 0 | Review finished, or (review status) the commit has a completed review. | | 1 | Couldn't finish, or (review status) no review exists / signed out / no origin. | | 2 | Invalid invocation (not inside a git repo, unknown flag, unresolvable commit). | | 3 | review status only: a review for the commit is still running. | | 4 | review status only: the most recent review failed. | | 5 | review status only: the most recent review was cancelled. | | 130 | Interrupted with Ctrl-C. |

Files

| Path | Contents | | ---------------------------------- | ------------------------------------------ | | ~/.greptile/auth.json | Credentials (refreshed automatically). | | ~/.config/greptile/settings.json | Saved settings (greptile settings path). | | ~/.cache/greptile/ | Downloaded diagram renderer. |