# How to Integrate Tuicr with GitHub: A Complete Setup Guide

> Learn how to integrate Tuicr with GitHub using the GitHub CLI. This guide covers setting up direct terminal access for pull requests, diffs, and reviews.

- Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr)
- Tags: how-to-guide
- Published: 2026-08-01

---

**Tuicr integrates with GitHub through the official GitHub CLI (`gh`), implementing the `ForgeBackend` trait in [`src/forge/github/gh.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/github/gh.rs) to fetch pull requests, render diffs, and submit reviews directly from your terminal.**

Tuicr is a terminal-based code review tool that streamlines GitHub workflows without leaving the command line. To integrate Tuicr with GitHub, you must install and authenticate the GitHub CLI, which serves as the underlying backend for all repository operations. This integration lives in the `src/forge/github` package and enables you to browse PRs, view diffs, and submit reviews using Tuicr's TUI interface.

## Prerequisites: Install the GitHub CLI

Tuicr requires the `gh` binary to be present in your system PATH. According to the source code in [`src/forge/github/gh.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/github/gh.rs), Tuicr checks for the CLI's presence during initialization and aborts with a clear error message—`GitHub integration requires `gh``—if the binary is missing.

Install the GitHub CLI using your package manager:

```bash

# macOS

brew install gh

# Linux (Debian/Ubuntu)

sudo apt install gh

# Linux (Fedora)

sudo dnf install gh

```

## Authenticate with GitHub

Before using Tuicr, authenticate the GitHub CLI to store your OAuth token. Tuicr reuses this authentication context rather than managing tokens independently.

Run the following command and follow the interactive prompts:

```bash
gh auth login

```

For GitHub Enterprise Server, specify your hostname:

```bash
gh auth login --hostname github.company.com

```

The authentication state is shared between `gh` and Tuicr, so you only need to complete this step once per environment.

## Open and Review Pull Requests

### Fetching PR Metadata

To open a PR in Tuicr, use the command `tuicr pr open <pr-url>`. Internally, Tuicr parses the URL to create a `PrSessionKey`, then calls `GitHubGhBackend::get_pull_request()` to fetch metadata.

In [`src/forge/github/pr_info.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/github/pr_info.rs), Tuicr executes `gh pr view --json` to retrieve extended PR details including the title, description, author, and review status:

```bash
tuicr pr open https://github.com/agavra/tuicr/pull/42

```

### Loading the Diff

Tuicr retrieves the diff text using `GitHubGhBackend::get_pull_request_diff()` in [`src/forge/github/gh.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/github/gh.rs). This method executes `gh pr diff` without the `--patch` flag (a behavior verified by the regression test `should_not_pass_patch_flag_to_gh_pr_diff`), ensuring the raw diff text serves as the source of truth for rendering and comment anchoring.

### Adding Inline Comments

While reviewing in the TUI:

1. Navigate to a specific line using arrow keys
2. Press **`a`** (or your configured keybinding) to add a line comment
3. Type your comment in the popup dialog
4. Press `Ctrl-S` to save the comment locally

Tuicr stores comments in [`src/model/comment.rs`](https://github.com/agavra/tuicr/blob/main/src/model/comment.rs) and maps each to a GitHub-style anchor using path, line number, and side (left/right) before submission.

## Submit Reviews to GitHub

When ready to submit, press **`:`** to enter command mode, type `submit`, and press Enter. For draft reviews, use `:submit draft`.

The submission logic resides in [`src/forge/github/submit.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/github/submit.rs). Tuicr builds a `CreateReviewRequest` payload and passes it to `GitHubGhBackend::create_review()`. To avoid CLI-argument length limits, the backend pipes the JSON payload via stdin using `gh api ... --input -`:

```bash

# Inside Tuicr TUI

:submit

```

This POSTs the review to the GitHub API endpoint `/repos/{owner}/{repo}/pulls/{number}/reviews` with all your inline comments attached.

## Error Handling and Troubleshooting

Errors from the GitHub CLI are translated in the `map_gh_error` function within [`src/forge/github/gh.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/github/gh.rs). Common failure modes include:

- **Missing CLI**: Tuicr displays "GitHub integration requires `gh`" and exits
- **Authentication failures**: Prompts direct users to run `gh auth login` again
- **API errors**: HTTP 422 responses are parsed and displayed in the status bar with friendly messaging

## Summary

- **Install `gh`**: Tuicr requires the GitHub CLI binary available in your PATH, verified at runtime in [`src/forge/github/gh.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/github/gh.rs)
- **Authenticate once**: Run `gh auth login` to store credentials that Tuicr inherits automatically
- **Open PRs**: Use `tuicr pr open <url>` to parse the PR and launch the TUI, fetching metadata via [`src/forge/github/pr_info.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/github/pr_info.rs)
- **Review locally**: Navigate diffs and press `a` to add anchored comments stored in [`src/model/comment.rs`](https://github.com/agavra/tuicr/blob/main/src/model/comment.rs)
- **Submit remotely**: Execute `:submit` to POST reviews via [`src/forge/github/submit.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/github/submit.rs) using `gh api` with stdin piping

## Frequently Asked Questions

### Do I need to generate a personal access token for Tuicr?

No. Tuicr does not require manual token generation. It relies entirely on the GitHub CLI's authentication state. As long as you have run `gh auth login`, Tuicr can access the API using those stored credentials without additional configuration.

### Can I use Tuicr with GitHub Enterprise Server?

Yes. Tuicr supports GitHub Enterprise through the `gh` CLI's multi-account authentication. Run `gh auth login --hostname <your-enterprise-host>` before launching Tuicr. The `ForgeBackend` trait implementation in [`src/forge/github/gh.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/github/gh.rs) respects the authentication context for the specified hostname.

### Why does Tuicr use the GitHub CLI instead of calling the REST API directly?

Tuicr delegates to `gh` to avoid managing OAuth tokens, refresh logic, and enterprise configuration manually. By wrapping the CLI in [`src/forge/github/gh.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/github/gh.rs), Tuicr inherits `gh`'s robust authentication handling while focusing on the TUI experience. This approach also ensures that security updates to the CLI automatically benefit Tuicr users.

### How do I view existing review comments in Tuicr?

Tuicr retrieves existing review threads via `gh api graphql` as implemented in [`src/forge/github/review_threads.rs`](https://github.com/agavra/tuicr/blob/main/src/forge/github/review_threads.rs). When you open a PR, the TUI fetches and displays existing comments alongside the diff, allowing you to see previous feedback before adding new comments or submitting your review.