> ## Documentation Index
> Fetch the complete documentation index at: https://www.greptile.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Onboarding

> Set up Greptile from your terminal with greptile onboard — or hand this page to your coding agent and have it run the setup for you.

Set up Greptile without leaving your terminal. `greptile onboard` creates your organization, connects GitHub or GitLab, enables repositories, and imports your existing AI rules files — the same setup the dashboard does.

This page is written to be **handed to a coding agent**. Paste the prompt below into Claude Code, Cursor, Codex, or any agent that can read a URL and run shell commands, and it will do the setup for you.

<Note>
  Requires **Greptile CLI v3.2.0 or newer** and **Node 22+**. The `onboard` command does not exist in earlier versions — if you see `Unknown command onboard`, you are on an old build. See [Upgrade](#upgrade).
</Note>

## Onboard with your coding agent

Copy this prompt into your agent:

```text Prompt theme={}
Onboard me to Greptile. Read the agent playbook at
https://www.greptile.com/docs/code-review/cli-onboarding and follow it exactly.

Work in the git repository I currently have open.

Run the machine steps yourself. When you reach a step that needs my browser
or an interactive terminal, stop, print the exact command or URL I need, and
wait for me to confirm before continuing. Do not guess my organization name —
ask me.

Finish by running a review on my current branch and summarizing the findings.
```

Run it from inside the repository you want reviewed.

<Tip>
  Your agent handles installation, checks, sign-in, verification, and your first review. You handle the two things it cannot: approving the browser sign-in, and answering the wizard.
</Tip>

## Onboard yourself

If you would rather do it by hand, it is three commands:

```bash theme={}
npm i -g greptile@latest
cd path/to/your/repo
greptile onboard
```

Then, once setup finishes:

```bash theme={}
greptile review
```

***

## Prerequisites

* **Node 22+** — check with `node --version`
* A **local git repository** with at least one commit, and a remote on GitHub or GitLab
* Permission to **install a GitHub App** on your organization (or, for GitLab, to create an access token and a webhook)

You do **not** need a Greptile account yet. `greptile login` creates one.

## Install

<Tabs>
  <Tab title="npm">
    ```bash theme={}
    npm i -g greptile@latest
    ```
  </Tab>

  <Tab title="Homebrew">
    ```bash theme={}
    brew install greptileai/tap/greptile
    ```
  </Tab>

  <Tab title="Install script">
    ```bash theme={}
    curl -fsSL https://raw.githubusercontent.com/greptileai/cli/main/install.sh | bash
    ```
  </Tab>
</Tabs>

### Upgrade

`onboard` shipped in **v3.2.0**. Confirm your version:

```bash theme={}
greptile --version
```

If it is below `3.2.0`, upgrade with the same method you installed with:

```bash theme={}
npm i -g greptile@latest   # or: brew upgrade greptile
```

<Warning>
  If `GREPTILE_API_KEY` is set, it overrides your browser sign-in and onboarding fails with `API key invalid or revoked` — even when the key is valid. API keys are org-scoped and cannot create an organization, so they cannot onboard.

  Unset it, and check your shell rc files for a lingering export:

  ```bash theme={}
  unset GREPTILE_API_KEY
  ```

  `greptile whoami` marks an environment key with `(via GREPTILE_API_KEY)`.
</Warning>

## Run the wizard

<Steps>
  <Step title="Run it from your repository root">
    ```bash theme={}
    cd path/to/your/repo
    greptile onboard
    ```

    <Warning>
      Run this **inside the repo you want reviewed**. The wizard scans your checkout for AI rules files. Run it from your home directory and that step silently finds nothing.
    </Warning>

    If you are not signed in, the wizard opens your browser. Approve the sign-in and it continues. That sign-in creates your Greptile account.
  </Step>

  <Step title="Create your organization">
    Answer the wizard's prompts. Leave the URL handle blank and Greptile derives one from your organization name.
  </Step>

  <Step title="Connect your code provider">
    Pick **GitHub** or **GitLab**. Greptile opens your browser to finish the connection.

    * **GitHub** — authorize Greptile and complete the App install, choosing which repositories it can access.
    * **GitLab** — paste a service account personal access token (recommended), group access token, or project access token. The account must have the Developer role and the token must have the `api` scope. Set up the webhook, then click <kbd>Done, I've set up the webhook</kbd>.

    Leave the terminal open. Greptile polls and continues on its own once the connection lands.

    <Note>
      No graphical browser (SSH, container, remote dev box)? The CLI prints the URL instead so you can open it on another device, and keeps polling.

      You have **10 minutes** to finish. Every 60 seconds the wizard offers **Keep waiting**, **Pick organization manually**, or **Skip for now**.
    </Note>

    When the connection lands, pick the organization to link. If you only have one and it is unclaimed, Greptile links it automatically.
  </Step>

  <Step title="Enable repositories">
    Select the repositories Greptile should review.

    <Warning>
      **At least one repository is required.** Onboarding cannot finish without one.
    </Warning>

    The list can pause on a spinner while a new organization syncs. Wait it out.

    Indexing starts in the background. You do not have to wait for it.
  </Step>

  <Step title="AI rules are imported automatically">
    Greptile scans your checkout and imports **every** match as org-wide custom context:

    * `CLAUDE.md` and `.claude/rules/**/*.md`
    * `AGENTS.md`
    * `.cursorrules` and `.cursor/rules/**/*.mdc`

    There is no picker — anything it finds, it takes. Add more context later from the dashboard.
  </Step>

  <Step title="Done">
    You will see:

    ```text theme={}
    Greptile is ready to review your first PR!
      1 repo added
      2 AI-rules files imported
    ```

    Your **14-day free trial** starts here. No payment method required.
  </Step>
</Steps>

## Verify

```bash theme={}
greptile whoami   # who you are, and your organizations
greptile onboard  # prints setup status when output is not a terminal
greptile review   # review the current branch
```

Open a pull request and Greptile reviews it automatically.

***

## Agent playbook

<Note>
  **This section is the contract an AI agent should follow.** Human readers can skip to [Troubleshooting](#troubleshooting).
</Note>

### What you can and cannot automate

Two steps are interactive by design and **cannot** be driven by an agent:

1. **Approving the browser sign-in** — a human must click Approve.
2. **The `greptile onboard` wizard itself** — it refuses to run when it detects an agent environment (`CLAUDECODE`, `CLAUDE_CODE`, `CURSOR_AGENT`, `CODEX_*`) or a non-TTY stdout. Run non-interactively, it prints setup status and exits `0` instead.

Do not try to defeat these. Do not spawn a pseudo-TTY, unset agent environment variables, or call internal API endpoints. **Instead, use `greptile onboard`'s non-interactive output as a read-only state probe**, do every other step yourself, and hand off cleanly for the two that need a human.

### Steps

<Steps>
  <Step title="Preflight">
    ```bash theme={}
    node --version
    greptile --version || echo "NOT_INSTALLED"
    ```

    Require Node **22+**. Require greptile **≥ 3.2.0**; if missing or older, run `npm i -g greptile@latest` and re-check. If `greptile onboard --help` reports `Unknown command`, the upgrade did not take effect — stop and report it.
  </Step>

  <Step title="Check for a conflicting API key">
    ```bash theme={}
    [ -n "$GREPTILE_API_KEY" ] && echo "API_KEY_SET"
    ```

    If set, warn the user: it **overrides browser sign-in**, and a stale key produces a misleading `API key invalid or revoked` on every command. Ask them to `unset GREPTILE_API_KEY` and remove it from their shell rc. Do not proceed while a failing key is set.
  </Step>

  <Step title="Locate the repository">
    ```bash theme={}
    git rev-parse --show-toplevel
    ```

    Run everything from there. If this fails, the user is not in a git repository — stop and ask where their repo is. Both the AI-rules import and the review depend on it.
  </Step>

  <Step title="Check sign-in">
    ```bash theme={}
    greptile whoami
    ```

    * `Signed in as <email>` with an org listed → already set up. Skip to **Run the first review**.
    * `Signed in as <email>` with no organizations → signed in, not onboarded. Go to **Hand off the wizard**.
    * `Not signed in` → continue below.

    To sign in, run `greptile login`. It prints a URL and waits. **Surface that URL to the user and stop.** Do not proceed until `greptile whoami` reports a signed-in account.
  </Step>

  <Step title="Probe onboarding state">
    ```bash theme={}
    greptile onboard
    ```

    Because you are an agent, this does not open the wizard. It prints status and exits `0`:

    | Output                              | Meaning             | Do this                          |
    | ----------------------------------- | ------------------- | -------------------------------- |
    | `Greptile onboarding: complete.`    | Fully set up        | Skip to **Run the first review** |
    | `Greptile onboarding: in progress.` | Started, unfinished | **Hand off the wizard**          |
    | `Greptile onboarding: dismissed.`   | Skipped earlier     | **Hand off the wizard**          |
    | `error: not signed in.`             | No credentials      | Go back to **Check sign-in**     |
  </Step>

  <Step title="Hand off the wizard">
    **Stop here and wait for the user.** Print this, verbatim:

    > Run this in your own terminal — I can't drive an interactive wizard:
    >
    > ```
    > cd <repo-root> && greptile onboard
    > ```
    >
    > You'll be asked for: your name, an organization name, a URL handle (blank is fine), company website (optional), and company size. Then pick GitHub or GitLab, finish the connection in the browser that opens, and choose which repositories to enable. Tell me when it says "Greptile is ready to review your first PR!"

    Then poll until it completes:

    ```bash theme={}
    greptile onboard
    ```

    Proceed only when it prints `Greptile onboarding: complete.` If the user reports an error, match it against [Troubleshooting](#troubleshooting) and tell them the fix — do not attempt to work around it yourself.
  </Step>

  <Step title="Run the first review">
    ```bash theme={}
    greptile review --agent
    ```

    Use `--agent` (plain text) or `--json` (structured). Summarize the findings for the user.

    Exit codes: `0` finished · `1` could not finish (or signed out) · `2` invalid invocation (not a git repo) · `130` interrupted.

    If it fails with a billing error, report it and stop — see [Troubleshooting](#troubleshooting).
  </Step>
</Steps>

### Rules

* **Never invent answers to the wizard.** The organization name and handle are the user's to choose.
* **Every command is safe to re-run.** Each step is gated on server state, so a repeated `greptile onboard` skips what is already done. If you are unsure of the state, probe again.
* **Do not create a second organization.** If the user is already onboarded, `greptile onboard` offers "Create a new organization" — that is not a retry, and it is not what they want.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Unknown command onboard">
    Your CLI predates v3.2.0. Run `greptile --version`, then upgrade with `npm i -g greptile@latest` (or `brew upgrade greptile`).

    If you installed via npm but `greptile` resolves through Homebrew's Node, `brew upgrade` will not help — use npm.
  </Accordion>

  <Accordion title="API key invalid or revoked">
    Your key is fine; it is the wrong credential. `GREPTILE_API_KEY` overrides browser sign-in, and API keys cannot create an organization.

    ```bash theme={}
    unset GREPTILE_API_KEY
    greptile whoami
    ```

    Remove the export from `~/.zshrc`, `~/.zprofile`, or `~/.bashrc` too, or it returns in your next shell.
  </Accordion>

  <Accordion title="We didn't detect a completed GitHub connection">
    The browser step did not finish. Re-run `greptile onboard` and complete the GitHub App install — authorizing Greptile is not enough. You must finish the install and grant repository access.
  </Accordion>

  <Accordion title="Every organization is already linked to another workspace">
    Someone at your company already connected that organization to a different Greptile workspace. Ask them to invite you, or install Greptile on an organization you own and refresh the list.
  </Accordion>

  <Accordion title="Greptile needs at least one repository to finish onboarding">
    No repository was enabled. If the list was empty, your organization was probably still syncing — re-run `greptile onboard` and choose **Add repositories**.
  </Accordion>

  <Accordion title="The review fails with a billing or trial error">
    CLI reviews require an active trial or a paid plan; the free plan includes pull request reviews only. New organizations start a 14-day trial automatically. Add a payment method in the [dashboard](https://app.greptile.com/).
  </Accordion>

  <Accordion title="I'm on SSH, a container, or a remote dev box">
    The CLI prints a URL you can open on any device, and a code to paste back if it cannot reach your machine. API keys work for reviews but cannot onboard, so run `greptile onboard` somewhere with a browser first.
  </Accordion>
</AccordionGroup>

## Command reference

| Command             | What it does                                                                 |
| ------------------- | ---------------------------------------------------------------------------- |
| `greptile onboard`  | Interactive setup wizard. Prints setup status when output is not a terminal. |
| `greptile login`    | Sign in through your browser                                                 |
| `greptile whoami`   | Show your account and organizations                                          |
| `greptile review`   | Review the current branch against its base                                   |
| `greptile settings` | Change review settings, members, and team config                             |
| `greptile update`   | Update the CLI                                                               |

<Note>
  Review strictness, PR summary sections, and team invitations are **not** part of onboarding. Configure them after setup with `greptile settings`, or in the dashboard.
</Note>

## What's next?

<CardGroup cols={2}>
  <Card title="Greptile CLI" icon="terminal" href="/code-review/greptile-cli">
    Review flags, output formats, and exit codes.
  </Card>

  <Card title="Custom Standards & Rules" icon="book" href="/code-review/custom-standards">
    Teach Greptile your team's conventions.
  </Card>

  <Card title="MCP" icon="plug" href="/mcp-v2/overview">
    Use Greptile from your editor or coding agent.
  </Card>

  <Card title="Anatomy of a Review" icon="magnifying-glass" href="/code-review/first-pr-review">
    Understand what Greptile posts on a PR.
  </Card>
</CardGroup>