Install and authenticate 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 Graphite CLI using either Homebrew or npm:

We recommend installing via Homebrew for smoothest sailing, even on Linux!

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

We develop Graphite with Node.js v18, 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 v18 as a first workaround! If that doesn't work, we recommend the brew installation, which ships standalone binaries for both MacOS and Linux.

As of v1.0.0, Graphite requires a minimum git --version of 2.38.0.


Tip

If you are running an Ubuntu version whose apt-get won't update Git to a high enough version for Graphite, you can source the latest version from the git-core PPA repository.

add-apt-repository ppa:git-core/ppa
apt update
apt install git

Read more on the Git website


Currently, the best way to install Graphite on Windows is via npm. If you do not use Node in your day-to-day work, there are a variety of ways to get it set up on your system, listed in the NPM documentation.

Click here for instructions.

Alternatively, you can use either brew or npm on WSL (Windows Subsystem for Linux).

We are always working towards better native Windows support, although occasionally it falls behind *nix systems in priority. If you run into any issues, especially if they are blocking your workflow, please reach out in our community Slack.


Note

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


  1. Sign into https://app.graphite.dev/activate 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.

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 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.