Installing the CLI

Install the grounds CLI on macOS, Linux, or Windows.

The grounds CLI is a single static Go binary. No JVM, no Node, no system dependencies.

Install

macOS (Homebrew)

brew install --cask groundsgg/tap/grounds

Upgrade:

brew upgrade --cask groundsgg/tap/grounds

Linux / WSL (script)

curl -fsSL https://raw.githubusercontent.com/groundsgg/grounds-cli/main/install.sh | sh

This installs to /usr/local/bin/grounds (or ~/.local/bin if you sh -s -- --prefix=$HOME/.local).

Upgrade by re-running the same command.

Windows (scoop)

scoop bucket add groundsgg https://github.com/groundsgg/scoop-bucket
scoop install grounds

Manual download

Grab the binary for your OS/arch from the GitHub releases page and put it on your PATH.

chmod +x grounds
mv grounds /usr/local/bin/

From source

go install github.com/groundsgg/grounds-cli/cmd/grounds@latest

Requires Go 1.23+.

Verify

grounds version
grounds doctor

grounds doctor runs five checks: config, auth, api, gradle, java. The gradle and java checks are advisory — you only need them for actually pushing.

Shell completion

Generate completion scripts on demand:

grounds completion bash > /etc/bash_completion.d/grounds          # bash
grounds completion zsh  > "${fpath[1]}/_grounds"                  # zsh
grounds completion fish > ~/.config/fish/completions/grounds.fish # fish

Updating

The CLI checks for updates lazily and prints a banner when a newer version is published. There is no auto-upgrade — use your installer of choice (brew, scoop, the install script).

What’s where after install

Path	Purpose
~/.config/grounds/ (Linux), ~/Library/Application Support/grounds/ (macOS), %APPDATA%\grounds\ (Windows)	Config + credentials
$XDG_CACHE_HOME/grounds/	Resolved API metadata cache

Override with --config <dir> or GROUNDS_CONFIG_DIR.