Skip to content

Installing the CLI

gpilot ships as a single self-contained binary for macOS, Linux, and Windows. Once it is installed, log in and follow the quickstart. Pick the method that matches your platform. All of them install the same binary, so you can switch later without uninstalling first.

Homebrew (recommended):

Terminal window
brew install graphpilot/tap/gpilot

Shell script:

Terminal window
curl --proto '=https' --tlsv1.2 -fsSL https://get.graphpilot.io | sh

The script installs to ~/.local/bin. Set GPILOT_INSTALL_DIR to choose a different location.

Both scripts download the release archive from GitHub over HTTPS and install it only if its SHA-256 matches the release’s SHA256SUMS.txt. When cosign v2.5.0 or later is on your PATH, they first check the signature of SHA256SUMS.txt and refuse to install if it does not match (see Verify a download). Keep the https:// in the command: without it, curl and PowerShell fetch the script itself over plain HTTP before any redirect.

Neither script changes your PATH. When the install directory is not on it, the script says so at the end; add the directory to your PATH to run gpilot by name.

Install a specific version

Section titled “Install a specific version”

The scripts install the latest release. To install another one, set GPILOT_VERSION to its version number (with or without the leading v):

Terminal window
curl --proto '=https' --tlsv1.2 -fsSL https://get.graphpilot.io | GPILOT_VERSION=1.0.1 sh
Terminal window
$env:GPILOT_VERSION = "1.0.1"; irm https://get.graphpilot.io/install.ps1 | iex

Check the installation

Section titled “Check the installation”
Terminal window
gpilot --version

Manual download

Section titled “Manual download”

Every release publishes prebuilt archives for all platforms on the releases page. Download the archive for your target, extract the gpilot binary, and place it anywhere on your PATH. The archives are named gpilot-cli-<version>-<target>:

PlatformTargetArchive
macOS, Apple siliconaarch64-apple-darwin.tar.gz
macOS, Intelx86_64-apple-darwin.tar.gz
Linux, x86-64x86_64-unknown-linux-musl.tar.gz
Linux, ARM64aarch64-unknown-linux-musl.tar.gz
Windows, x86-64x86_64-pc-windows-msvc.zip

Each release carries a SHA256SUMS.txt and, from v1.0.1 on, its signature SHA256SUMS.txt.sigstore.json, so you can verify the download.

Verify a download

Section titled “Verify a download”

Each release from v1.0.1 on is signed. SHA256SUMS.txt.sigstore.json is a keyless Sigstore signature of SHA256SUMS.txt, made by GraphPilot’s CLI release workflow at the release’s tag and recorded in Sigstore’s public transparency log. A valid signature shows that the checksums come from that workflow, not from whoever can upload files to the release, and the checksums in turn cover every archive.

Download the archive, SHA256SUMS.txt and SHA256SUMS.txt.sigstore.json from the same release, then check the signature with cosign v2.5.0 or later (older versions cannot read the signature format) and the archive against the checksums:

Terminal window
VERSION=1.0.2   # the release you downloaded, without the leading v
cosign verify-blob --bundle SHA256SUMS.txt.sigstore.json \
  --certificate-identity "https://github.com/GraphPilot/graphpilot-proxy/.github/workflows/release-cli.yml@refs/tags/gpilot-cli-v${VERSION}" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  SHA256SUMS.txt
sha256sum --check --ignore-missing SHA256SUMS.txt   # macOS: shasum -a 256 --check --ignore-missing SHA256SUMS.txt

cosign prints Verified OK for a valid signature. The identity names the release’s own tag, so checksums signed for a different version do not pass.

The install scripts run the same check:

  • cosign v2.5.0 or later on the PATH: the signature is checked before the checksum, and the script stops without installing anything if it does not match.
  • No cosign, or an older one: the script prints a warning with the command above and installs on the checksum alone. The scripts never download cosign themselves.
  • A signed release without its signature file: the script refuses to install, with or without cosign.
  • Releases before v1.0.1 (installed with GPILOT_VERSION) carry no signature. The script warns and relies on the checksum.

To make the signature mandatory, so that a machine without a suitable cosign fails instead of falling back to the checksum, pass --require-signature or set GPILOT_REQUIRE_SIGNATURE=1:

Terminal window
curl --proto '=https' --tlsv1.2 -fsSL https://get.graphpilot.io | sh -s -- --require-signature
Terminal window
$env:GPILOT_REQUIRE_SIGNATURE = "1"; irm https://get.graphpilot.io/install.ps1 | iex

With the signature required, an unsigned release is refused too.

Shell completions

Section titled “Shell completions”

gpilot can generate completions for your shell:

Terminal window
gpilot completion bash    # or zsh, fish, powershell, elvish

The Homebrew formula installs bash, zsh, and fish completions automatically.

Updating

Section titled “Updating”
Terminal window
brew upgrade gpilot

Staying up to date

Section titled “Staying up to date”

Before any command that talks to the GraphPilot API, the CLI checks the minimum version GraphPilot supports. A new release may be published as the new minimum, and then an older gpilot stops working for API commands soon after a new version ships. Plan on upgrading whenever one comes out:

  • Behind the latest release, but supported: the command runs and prints a notice on stderr that an update is available.
  • Below the minimum: the command refuses to run and exits with code 6. The error names the upgrade command for how you installed the CLI (brew upgrade gpilot, scoop update gpilot, or the install script).

Commands that never leave your machine, such as gpilot profile and gpilot config convert, are not checked.

The check reads a small version manifest from GitHub (raw.githubusercontent.com) and remembers the answer for five minutes. When the manifest cannot be fetched, the last answer it remembers applies, however old. A machine that has never reached it runs without the check.

Section titled “Related”