Install the CLI

The Graphite CLI is a tool to help you break up large engineering tasks into a series of small, incremental code changes directly from the command line. The Graphite CLI makes it easy to stay unblocked as an author, develop faster, and provide more helpful comments as a reviewer.

The Graphite CLI is fully compatible with git—just install it on an existing repository and begin using our suite of gt commands.

Install the CLI

Install the Graphite CLI using either npm or homebrew:

# Install Graphite from npm.
npm install -g @withgraphite/graphite-cli
gt --version
# Install Graphite from Homebrew.
brew install withgraphite/tap/graphite
gt --version

We develop Graphite with and set the Homebrew dependency to Node.js v16, but Graphite should run with no major issues on any current version of Node. If you run into any issues that seem Node-related, try using v16 as a first workaround!

As of v1.0.0, Graphite requires a minimum git --version of 2.38.0. There is a specific plumbing command that we would like to rely on under the hood that was introduced in 2.40.0 — we are expecting to begin using it as soon as Apple-git reaches that version.

If you'd like to use Graphite on Windows, we recommend working within Windows Subsystem for Linux. Follow the instructions to set it up. After setting up WSL, you can set up nvm/node/npm and then install Graphite as normal. We are slowly working towards better native Windows support—if you'd like to stay up to date, the discussions are often found in our community Slack.

Authenticate the CLI


To use Graphite to create or update pull requests in GitHub for the branches in your stack using gt stack submit, you must authenticate the CLI with your GitHub account. See Privacy and Security to understand which GitHub permissions Graphite requires.

  1. Sign into with your GitHub account.

  2. Copy the gt auth --token <your_cli_auth_token> command shown (your CLI auth token will be pre-filled for you).

  3. Paste and run it in your terminal.

> gt auth --token <YOUR_AUTH_TOKEN>
🔐 Saved auth token to "/Users/pranathiperi/.graphite_user_config"

Once you've authenticated the CLI, you can run gt stack submit to create or update pull requests in GitHub for every branch in your stack.

Your privacy and security are our top priorities. Graphite is architected to ask for the minimum set of permissions necessary within the constraints of GitHub's API. Learn more about our GitHub integration.