Table of contents

• What is gh?
• Why use gh?
• Basic usage of gh
• Introducing the Graphite CLI
• Summary
• Frequently asked questions

When working with GitHub repositories, you often want quick, command-line-driven ways to create pull requests, manage issues, review changes, and more. The GitHub CLI—commonly referred to as gh—is an official command-line tool that simplifies interaction with GitHub from your terminal.

In addition to the GitHub CLI, you might also be interested in the Graphite CLI (gt), a separate command-line tool that helps you create and manage stacked pull requests. This guide covers both tools, including when and why you might want to use them, how to install each one, and how to authenticate them with GitHub.

What is gh?

gh is the official GitHub CLI, maintained by GitHub. It provides a convenient way to perform various GitHub-related tasks:

• Creating pull requests (gh pr create, gh pr checkout, gh pr merge)
• Managing issues (gh issue create, gh issue status, gh issue view)
• Working with gists (gh gist create, gh gist list)
• Viewing and editing GitHub Actions workflows and runs
• Managing GitHub repositories (viewing, forking, starring)

Essentially, gh helps reduce context switching between your terminal and the browser. You can remain in your local development environment while still leveraging the full power of GitHub.

Why use gh?

• Streamlined workflow: Create pull requests without leaving your terminal.
• Automation: Automate repetitive tasks (e.g., labeling issues, merging PRs).
• Scripting: Incorporate GitHub operations into larger scripts and CI/CD pipelines.

Basic usage of gh

After installation, you can run gh commands from your terminal. Here are a few common examples:

Authenticate with GitHub

gh auth login

Follow the prompts to connect your GitHub account.

Create a pull request

# from a branch with new changes
gh pr create --fill

• --fill uses your current commits and branch name to fill in the pull request details automatically.

List pull requests

gh pr list

View issues

gh issue list
gh issue view <issue_number>

Introducing the Graphite CLI

While gh is ideal for general GitHub tasks, the Graphite CLI is purpose-built for breaking up large engineering tasks into a series of small, incremental code changes (i.e., stacked pull requests).

Why use the Graphite CLI?

• Stacked pull requests: Easily manage multiple small PRs that build on each other.
• Improved code reviews: Smaller PRs lead to more targeted, faster reviews.
• Remain unblocked: Quickly update or reorder branches without complex git gymnastics.
• Full Git compatibility: The Graphite CLI integrates seamlessly with existing Git workflows.

Installing the Graphite CLI

You can install the Graphite CLI (gt) via Homebrew or npm. It’s fully compatible with existing repositories—just install and start using it.

5.1 Homebrew Installation (Recommended)

brew install withgraphite/tap/graphite
gt --version

• MacOS: The recommended method is via Homebrew.
• Linux: Homebrew on Linux is also supported.

5.2 npm Installation

npm install -g @withgraphite/graphite-cli@stable
gt --version

Authenticating the Graphite CLI

To create or update pull requests on GitHub via the Graphite CLI (gt submit), you’ll need to authenticate. This involves generating a one-time token and passing it to the CLI.

1. Sign into the Graphite web app Visit https://app.graphite.dev/activate and log in with your GitHub account.

2. Copy your auth command You’ll see a command of the form:

   Terminal

   gt auth --token <YOUR_AUTH_TOKEN>
   
   

   This token will be unique to your user account.

3. Paste & run Back in your terminal, paste the gt auth command. You should see:

   Terminal

   🔐 Saved auth token to "/Users/<username>/.graphite_user_config"
   
   

   This indicates the CLI is now authenticated.

Once authenticated, you can use:

gt submit

to create or update GitHub pull requests for every branch in your stack.

Using the Graphite CLI

Below are some common gt commands you’ll use when managing stacked pull requests:

1. Creating a new stack branch

   Terminal

   gt branch create <branch_name>
   
   

   This command sets up a new branch in your stack.

2. Submitting a pull request

   Terminal

   gt submit
   
   

   This will create or update pull requests for each branch that isn’t already merged.

3. Syncing & updating

   Terminal

   gt up
   
   

   Merges the latest changes from parent branches so your stack remains in sync.

4. Viewing Your Stack

   Terminal

   gt stack
   
   

   Displays a graphical tree of your stacked branches.

   

Summary

• gh (GitHub CLI) is a powerful, official tool from GitHub for day-to-day repository management, including PRs, issues, and repository configuration.
• The Graphite CLI is an additional layer focusing on stacked pull requests and enabling smaller, more manageable code review workflows.
• Both can coexist in your toolbox, each serving a distinct purpose. Installing both allows you to handle general GitHub tasks via gh while leveraging Graphite’s powerful stacked PR features when splitting up large feature branches.

By combining these two tools, you can streamline code reviews, simplify your workflow, and keep your branches organized—leading to quicker, higher-quality code merges.

Frequently asked questions

Do I need to authenticate both tools separately?

Yes, each tool requires its own authentication:

• gh: Use gh auth login to authenticate with your GitHub account
• gt: Visit app.graphite.dev/activate to get your auth token and run gt auth --token <YOUR_AUTH_TOKEN>

What's the difference between gh pr create and gt submit?

• gh pr create: Creates a single pull request from your current branch
• gt submit: Creates or updates pull requests for all branches in your stack (multiple related PRs)

Can I use Graphite CLI without the web app?

The Graphite CLI requires authentication through the web app to create and update pull requests on GitHub. However, you can use local Git operations (like gt branch create, gt up, gt stack) without authentication.

Is the Graphite CLI compatible with existing Git workflows?

Yes! The Graphite CLI is built on top of standard Git commands and integrates seamlessly with your existing Git workflow. You can continue using your preferred Git commands alongside Graphite's stacked PR features.

What happens if I have conflicts in my stack?

Use gt up to sync your stack with the latest changes from parent branches. If conflicts arise, resolve them using standard Git conflict resolution methods, then continue with your Graphite workflow.