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

# Quickstart

> Install the MergeGuide CLI, authenticate, and run your first policy check.

This quickstart takes you from nothing installed to a first policy check in a few
minutes. By the end you will have the CLI installed, an authenticated session, and
your first findings on real code.

<Note>
  **Prerequisites:** Python 3.11 or newer, and a MergeGuide account. Create one at
  [portal.mergeguide.com](https://portal.mergeguide.com). You will also need an API
  key from the dashboard for headless login (or you can log in interactively).
</Note>

## Option A — one command (recommended)

`mergeguide init` is the first-run orchestrator. After installing the CLI, a single
command authenticates you, installs the MCP server, and wires up your git hooks.

<Steps>
  <Step title="Install the CLI">
    ```bash theme={null}
    pip install mergeguide
    ```

    Verify it installed:

    ```bash theme={null}
    mergeguide --version
    ```
  </Step>

  <Step title="Run the first-run setup">
    ```bash theme={null}
    mergeguide init --api-key mg_xxxxxxxxxxxxxxxx
    ```

    `init` is idempotent — it preflights your environment, writes
    `.mergeguide/config.yaml`, authenticates against the dashboard, installs the
    `@mergeguide/mcp-server` npm package via `npx`, registers it in your project's
    `.mcp.json`, and installs git pre-commit / pre-push hooks. Re-running it on a
    configured install is a fast no-op.

    <Tip>
      Omit `--api-key` to be prompted interactively. In CI, pass the key explicitly —
      `init` fails fast in non-interactive environments rather than hanging on a
      prompt.
    </Tip>
  </Step>

  <Step title="Run your first check">
    ```bash theme={null}
    mergeguide check
    ```

    With no paths, `check` reads your staged changes (or from stdin). Pass paths to
    check specific files or directories:

    ```bash theme={null}
    mergeguide check src/
    ```
  </Step>
</Steps>

## Option B — step by step

If you would rather set up each piece yourself:

<Steps>
  <Step title="Install the CLI">
    ```bash theme={null}
    pip install mergeguide
    ```
  </Step>

  <Step title="Authenticate">
    ```bash theme={null}
    mergeguide login --api-key mg_xxxxxxxxxxxxxxxx
    ```

    Or run `mergeguide login` with no flags to authenticate interactively. Confirm
    who you are signed in as:

    ```bash theme={null}
    mergeguide auth whoami
    ```
  </Step>

  <Step title="Check your setup">
    ```bash theme={null}
    mergeguide doctor
    ```

    `doctor` diagnoses your configuration and connectivity and reports anything
    that needs attention.
  </Step>

  <Step title="Run a check">
    ```bash theme={null}
    mergeguide check src/
    ```
  </Step>
</Steps>

## Reading the result

`check` prints each finding with its file, line, severity, and remediation
guidance, then exits:

* **Exit code 0** — no blocking findings.
* **Exit code 1** — policy violations were found.
* **Exit code 2** — a configuration or environment error.

To get machine-readable output for tooling or CI, choose a format:

```bash theme={null}
mergeguide check src/ --format json
mergeguide check src/ --format sarif --output results.sarif
```

## Next steps

<CardGroup cols={2}>
  <Card title="Install the rest" icon="download" href="/install/cli">
    Add the MCP server, IDE extension, git hooks, and the PR gate.
  </Card>

  <Card title="Configure policies" icon="sliders" href="/configuration/mergeguide-yaml">
    Set up `.mergeguide.yaml` and choose your frameworks.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/reference/cli">
    Every command and flag in detail.
  </Card>

  <Card title="Core concepts" icon="book" href="/get-started/core-concepts">
    The vocabulary the rest of the docs use.
  </Card>
</CardGroup>