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

# Git Forge (@forge)

> Pull requests, issues and CI through the user's own authenticated gh/glab CLI — read a PR's checks, pull the failing run's logs, comment and open PRs, without leaving the agent. Keyless: ChatCLI never stores forge credentials.

The **`@forge`** tool brings your Git forge into the agent loop. It runs pull-request, issue and CI operations through the CLI **you already authenticated** — [`gh`](https://cli.github.com) for GitHub, [`glab`](https://gitlab.com/gitlab-org/cli) for GitLab — so the agent can close the daily loop **`branch → PR → watch CI → fix`** without you switching windows.

<Info>
  `@forge` is **keyless by design**. ChatCLI never stores a forge token: it shells out to the `gh`/`glab` binary the user logged in with (`gh auth login` / `glab auth login`). Whatever those CLIs can do with your account, `@forge` can do — nothing more, nothing less.
</Info>

<Tip>
  The typical use is debugging a red PR: `@forge pr-checks 42` shows which checks failed, `@forge ci-logs <run-id>` pulls **only the failing steps'** logs, the agent fixes the code, and `@forge pr-comment 42 --body "…"` reports back.
</Tip>

***

## Prerequisites

`@forge` needs the forge's official CLI installed and authenticated on your machine:

<Steps>
  <Step title="Install the CLI">
    GitHub: install [`gh`](https://cli.github.com). GitLab: install [`glab`](https://gitlab.com/gitlab-org/cli). Either is enough — `@forge` picks the right one automatically (see below).
  </Step>

  <Step title="Authenticate once">
    ```bash theme={"system"}
    gh auth login      # GitHub
    glab auth login    # GitLab
    ```

    ChatCLI reuses this session. There is nothing to configure inside ChatCLI and no token to paste.
  </Step>

  <Step title="Run inside a repository">
    `@forge` reads the `origin` remote to decide GitHub vs GitLab, so run the agent from a cloned repo (or pass `host` explicitly).
  </Step>
</Steps>

***

## Usage

```text theme={"system"}
<tool_call name="@forge" args='{"cmd":"pr-checks","args":{"number":42}}' />
<tool_call name="@forge" args='{"cmd":"ci-logs","args":{"run":123456}}' />
<tool_call name="@forge" args='{"cmd":"pr-comment","args":{"number":42,"body":"CI is green now — the flaky test was reseeded."}}' />
```

Both the JSON envelope `{cmd, args}` and a flat argv form are accepted, and the two-token spelling folds into the canonical command — `pr view 42` is the same as `pr-view 42`.

### Subcommands

| Subcommand      | What it does                                                                      | Gating            |
| :-------------- | :-------------------------------------------------------------------------------- | :---------------- |
| `pr-list`       | Open pull requests (`--limit N`)                                                  | read-only         |
| `pr-view`       | One PR: title, body, state, reviews (`{number}`)                                  | read-only         |
| `pr-diff`       | The PR's diff, capped (`{number}`)                                                | read-only         |
| `pr-checks`     | CI check status for the PR (`{number}`)                                           | read-only         |
| `pr-create`     | Open a PR from the current branch (`--title` req., `--body`, `--base`, `--draft`) | **security gate** |
| `pr-comment`    | Comment on a PR (`{number}`, `--body` req.)                                       | **security gate** |
| `issue-list`    | Open issues (`--limit N`)                                                         | read-only         |
| `issue-view`    | One issue with its discussion (`{number}`)                                        | read-only         |
| `issue-comment` | Comment on an issue (`{number}`, `--body` req.)                                   | **security gate** |
| `ci-status`     | Latest workflow runs (`--branch BR`, current branch by default)                   | read-only         |
| `ci-logs`       | The **failing steps'** logs of one run (`{run-id}`)                               | read-only         |
| `detect`        | Which forge CLI would be used, and why                                            | read-only         |

***

## GitHub or GitLab — decided for you

`@forge` picks the backend automatically:

<Steps>
  <Step title="Explicit host wins">
    Pass `{"host":"github"}` or `{"host":"gitlab"}` to force `gh` or `glab` for that call.
  </Step>

  <Step title="Otherwise, the git remote decides">
    An `origin` remote pointing at a **GitLab** URL routes to `glab`; anything else defaults to `gh` (GitHub).
  </Step>
</Steps>

The command surface is identical across both — `@forge` maps the GitLab vocabulary for you: a **PR** becomes a **merge request** (`pr-*` → `mr`), a **comment** becomes a **note**, and `--base` becomes `--target-branch`. You write one set of commands; the right CLI runs underneath.

```text theme={"system"}
<tool_call name="@forge" args='{"cmd":"detect"}' />
→ Forge CLI: glab (origin remote is a GitLab URL)
```

***

## Worked example: fixing a red PR without leaving the agent

```text theme={"system"}
# 1. Which checks failed on PR 42?
<tool_call name="@forge" args='{"cmd":"pr-checks","args":{"number":42}}' />
→ ✓ lint   ✗ test (run 987654)   ✓ build

# 2. Read ONLY the failing run's failing steps
<tool_call name="@forge" args='{"cmd":"ci-logs","args":{"run":987654}}' />
→ FAIL TestPricing/glm-5.3 … expected 0.15 got 0

# 3. …the agent fixes the code with @coder, re-runs tests…

# 4. Report back on the PR
<tool_call name="@forge" args='{"cmd":"pr-comment","args":{"number":42,"body":"Fixed: the pricing table lacked the glm-5.3-flash tier. Pushed 3f0a1c2."}}' />
```

The same flow works on GitLab merge requests unchanged — only the underlying CLI differs.

***

## Security

* **Reads are auto-approved.** `pr-list`, `pr-view`, `pr-diff`, `pr-checks`, `issue-list`, `issue-view`, `ci-status`, `ci-logs` and `detect` only observe forge state, so they run without a confirmation prompt and can be batched.
* **Mutations hit the [security gate](/features/coder-security).** `pr-create`, `pr-comment` and `issue-comment` change what other people see, so they go through the same confirmation policy as any other side-effecting tool call — you (or your policy) approve each one.
* Nothing is ever escalated silently: unparseable arguments fail closed (treated as *not* read-only), and the tool never invents a token — it can only do what your logged-in `gh`/`glab` can.

<Note>
  `@forge` output is capped to keep large PR diffs and CI logs from flooding the context. For a full diff, the agent can fall back to `@coder git-diff` on a checked-out branch.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Agentic Plugins" icon="plug" href="/features/agentic-plugins">
    The full builtin tool catalog and how the agent uses them.
  </Card>

  <Card title="Coder Mode Security" icon="shield-halved" href="/features/coder-security">
    How the security gate arbitrates mutating tool calls.
  </Card>
</CardGroup>