Setup

The CLI is distributed as a binary archive from https://pkg.devgrid.io/latest/.

Download

Choose your platform and architecture:

macOS (Intel)

curl -Lo devgrid-latest-darwin-x64.tar.gz https://pkg.devgrid.io/latest/devgrid-latest-darwin-x64.tar.gz

macOS (Apple Silicon / ARM)

curl -Lo devgrid-latest-darwin-arm64.tar.gz https://pkg.devgrid.io/latest/devgrid-latest-darwin-arm64.tar.gz

Linux (x64)

curl -Lo devgrid-latest-linux-x64.tar.gz https://pkg.devgrid.io/latest/devgrid-latest-linux-x64.tar.gz

Linux (ARM64)

curl -Lo devgrid-latest-linux-arm64.tar.gz https://pkg.devgrid.io/latest/devgrid-latest-linux-arm64.tar.gz

Windows (x64)

curl -Lo devgrid-latest-windows-x64.tar.gz https://pkg.devgrid.io/latest/devgrid-latest-windows-x64.tar.gz

Windows (ARM64)

curl -Lo devgrid-latest-windows-arm64.tar.gz https://pkg.devgrid.io/latest/devgrid-latest-windows-arm64.tar.gz

macOS / Linux install

1. Move the downloaded archive to a directory where you want the CLI to live (for example ~/bin or ~/Programs/devgrid).

2. Extract the archive:

mkdir -p ~/bin
tar -xzf devgrid-latest-darwin-x64.tar.gz -C ~/bin
# Use the matching archive name for your platform (darwin-arm64, linux-x64, etc.)

3. Make the binary executable:

chmod +x ~/bin/devgrid-cli

4. Run the CLI using the full path, or add the directory to your PATH:

export PATH="$HOME/bin:$PATH"
devgrid-cli help

macOS Gatekeeper

If macOS blocks the binary with "cannot be opened because the developer cannot be verified", remove the quarantine attribute:

xattr -d com.apple.quarantine ./devgrid-cli

Windows install

1. Move the downloaded archive to a folder such as C:\Programs\devgrid.

2. Extract the archive (right-click → Extract All...).

3. Run from PowerShell or Command Prompt using the full path:

C:\Programs\devgrid\devgrid-cli.exe help

Add the folder to your system PATH if you want to run devgrid-cli from any directory.

Authenticate

After installing, authenticate before running sync, dry_run, or event.

Local development (recommended)

Log in once; the CLI caches your OAuth token locally:

devgrid-cli login --username [email protected]

You will be prompted for your password if you do not pass --password. Then verify:

devgrid-cli auth status
devgrid-cli sync

Cached credentials are stored at:

• $XDG_CONFIG_HOME/devgrid/<env>/credentials.json, or
• ~/.config/devgrid/<env>/credentials.json on most systems

The <env> value matches your ENV setting (prod, dev, or local). Legacy ENV=next is treated as dev.

CI / automation

For pipelines, pass credentials via environment variables instead of using login:

export DEVGRID_CLIENT_ID=your-client-id
export DEVGRID_CLIENT_SECRET=your-client-secret
devgrid-cli sync

Or use a pre-fetched access token:

export DEVGRID_ACCESS_TOKEN=eyJ...
devgrid-cli sync

See Commands — Authentication for all options, including the deprecated API key fallback.

Environment targeting

For most users targeting production, no environment variables are required.

Next steps

• Commands — full command reference
• devgrid.yml — configure your project
• Troubleshooting — if something goes wrong