Skip to content

install.md

Latest commit

 

History

History
157 lines (114 loc) · 4.58 KB

install.md

File metadata and controls

157 lines (114 loc) · 4.58 KB

Install

gog ships as a single binary. The visible version is injected at build time: release builds use the tag, while local builds use git describe.

Homebrew (macOS, Linux)

brew install gogcli
gog --version

The Homebrew formula lives in steipete/homebrew-tap and installs the gog binary. Release verification should run:

brew test steipete/tap/gogcli
gog --version

Docker / GHCR

Release tags publish a non-root GitHub Container Registry image:

docker run --rm ghcr.io/openclaw/gogcli:latest version
docker run --rm ghcr.io/openclaw/gogcli:v0.15.0 version

Authenticated container runs should mount a persistent config directory and use the encrypted file keyring:

docker volume create gogcli-config

docker run --rm -it \
  -e GOG_KEYRING_BACKEND=file \
  -e GOG_KEYRING_PASSWORD \
  -v gogcli-config:/home/gog/.config/gogcli \
  ghcr.io/openclaw/gogcli:latest \
  auth add [email protected] --services gmail,calendar,drive

Keep GOG_KEYRING_PASSWORD in the shell session or your CI secret store. Do not bake it into images, scripts, or checked-in profiles.

Headless agents and systemd

For headless agents, configure gog with the encrypted file keyring and pass the same environment to the process that will actually invoke gog. A command working in your login shell only proves that shell has the password; it does not prove a systemd service, gateway, or agent subprocess inherited it.

Use this as the minimum runtime environment:

Environment=GOG_KEYRING_BACKEND=file
Environment=GOG_KEYRING_PASSWORD=replace-with-secret-manager-injection
Environment=HOME=/home/openclaw

Then reload and restart the service before testing from the same entrypoint the agent uses:

systemctl --user daemon-reload
systemctl --user restart openclaw-gateway.service

systemctl --user show openclaw-gateway.service \
  --property=Environment

openclaw agent --agent main --message \
  'Run: gog auth doctor --check --no-input && gog gmail search "newer_than:1d" --max 1 --json'

If the shell command succeeds but the agent still reports keyring.password, fix the agent or service environment first. Re-authenticating usually does not help when gog auth doctor --check already shows readable tokens in the shell.

Windows

Download the matching ZIP from the latest release:

  • gogcli_<version>_windows_amd64.zip
  • gogcli_<version>_windows_arm64.zip

Extract gog.exe and put its directory on PATH.

GitHub releases (raw binaries)

Release assets are uploaded by GoReleaser:

  • gogcli_<version>_darwin_amd64.tar.gz
  • gogcli_<version>_darwin_arm64.tar.gz
  • gogcli_<version>_linux_amd64.tar.gz
  • gogcli_<version>_linux_arm64.tar.gz
  • gogcli_<version>_windows_amd64.zip
  • gogcli_<version>_windows_arm64.zip
  • checksums.txt

Browse the releases page for the latest tag and the full asset list.

Build from source

git clone https://github.com/openclaw/gogcli.git
cd gogcli
make
./bin/gog --version

Source builds require the Go version declared in go.mod.

Safety-profile binaries

When gog is going to be invoked by an agent, sandbox, or other caller that should not be able to broaden its own permissions, build a safety-profile binary instead of the default one. See Safety Profiles.

./build-safe.sh safety-profiles/agent-safe.yaml -o bin/gog-agent-safe
./build-safe.sh safety-profiles/readonly.yaml   -o bin/gog-readonly

Verify the install

gog --version
gog auth keyring         # report current keyring backend
gog --help               # discover top-level commands

After running gog auth credentials and gog auth add, gog auth doctor --check reports keyring health, refresh-token validity, and Workspace-specific failure modes.

Updating

  • Homebrew: brew upgrade gogcli.
  • Docker: pull a new tag (ghcr.io/openclaw/gogcli:vX.Y.Z).
  • GitHub release archives: download the new tarball/ZIP and replace the binary.
  • Source builds: git pull && make — the version string comes from git describe.

Refresh tokens and OAuth clients are forward-compatible across point releases; no migration step is required for normal upgrades.

Related command pages