gogcli: one Google Workspace CLI with readonly flags, exact command allowlists, and baked safety profiles

Three install paths with different costs, and a module path that moved

Homebrew is the shortest route on macOS and Linux:

brew install openclaw/tap/gogcli
gog --version

The Go route installs the same binary from source and carries a stricter floor. `go.mod` declares `go 1.26.0` with a `go1.27.3` toolchain, so a machine on an older Go toolchain will download a toolchain rather than fail cleanly.

go install github.com/openclaw/gogcli/cmd/gog@latest
gog --version

Docker images, Windows archives, raw macOS and Linux binaries, and source builds are all documented separately in the install guide. Prebuilt macOS binaries require macOS 15 or later, which rules out older Macs without a build from source.

One trap is worth naming: install scripts written against the former `github.com/steipete/gogcli` module path should now point at `github.com/openclaw/gogcli`. Anything pinned to the old path is building a different module identity than the one the release notes describe.

Nothing works until a Desktop OAuth client is registered and checked

The first run is not a command you can try immediately. You create a Desktop OAuth client in a Google Cloud project, download its JSON file, and authorize only the services you need:

gog auth credentials set ~/Downloads/client_secret_*.json
gog auth add [email protected] --services gmail,calendar,drive
export [email protected]
gog auth doctor --check
gog gmail search 'newer_than:7d' --max 10

Running `gog auth doctor --check` before the first real command checks the authorization you just set up.

The linked quickstart also covers API enablement, the OAuth consent screen, weekly token expiry avoidance, headless authorization, and account defaults.

Set `GOG_ACCOUNT` if you have more than one identity. Without it, the routing is implicit, which is exactly the wrong default for a script that runs unattended.

The documented Gmail scopes are broad until you pass a narrowing flag

The generated scope table records Gmail user authorization as `gmail.modify`, `gmail.settings.basic`, and `gmail.settings.sharing`. Those are mailbox modification and settings management permissions, granted by the default Gmail entry.

Narrower access exists, but you have to ask for it. The least-privilege path is `gog auth add [email protected] --services gmail --gmail-scope send` for sending only, or `--gmail-scope read-send` to also read messages without mailbox-modification or settings-management permissions.

So the boundary is opt-in in two steps: choose the service, then choose the scope. Skipping the scope flag leaves you with an authorization that can modify a mailbox, which matters if that token ends up in a CI job, a container, or an agent context.

Worth knowing before you wire this up: Calendar authorization is a single broad scope, `https://www.googleapis.com/auth/calendar`. Chat and Classroom carry long fixed scope lists that include create permissions, such as `chat.messages.reactions.create`. Not every service in the table has the fine-grained option Gmail does, so the Gmail flag does not become a general policy you can apply across Workspace.

Runtime boundaries come from flags, and missing one widens what an agent can do

The safe-invocation shape stacks several flags rather than relying on a single mode:

gog --account [email protected] \
  --enable-commands-exact gmail.search,gmail.get \
  --gmail-no-send --readonly --no-input --wrap-untrusted --json \
  gmail search 'newer_than:7d'

Each piece does a different job. `--readonly` restricts to reads, `--enable-commands-exact` names the only commands permitted, `--gmail-no-send` blocks sending, `--no-input` prevents interactive prompts, and `--wrap-untrusted` marks retrieved content as untrusted so a model does not treat mail bodies as instructions.

The failure mode is omission. Drop `--enable-commands-exact` and you have a full command surface with a read-only flag; drop `--no-input` on a CI runner and the command can block on a prompt with nobody watching. The flags are the enforcement, not documentation, so they belong in a wrapper script or a base command string rather than in each call site.

Output discipline helps here too: `--json` for structured data, `--plain` for stable TSV, prompts and warnings on stderr, so a piped consumer is not fed progress text.

Safety profiles bake policy at build time instead of run time

Runtime flags still depend on whoever assembles the command. `build-safe.sh` and the `safety-profiles/` directory exist to close that gap by producing a binary with command policy and locked flag values fixed at build time, and the Makefile wires it as a first-class target: the `build-safe` goal calls `./build-safe.sh` with the `PROFILE` environment variable, defaulting to `safety-profiles/agent-safe.yaml`, and writes to `OUTPUT`, defaulting to a `gog-safe` binary in `bin/`.

A baked binary cannot be talked out of its policy by a prompt, a config edit, or a command pasted from a chat window. That is the difference worth caring about if an agent is the caller: the policy travels with the executable rather than with the request.

The cost is a second artifact to version, build, and distribute, and a profile file that becomes part of your security posture. The repository also ships `.env.example` with `GOG_TEST_ACCOUNT` and `GOG_TEST_DOC_ID`, plus an `evals/` directory, so there is a place where the profile and a test account meet.

One detail worth knowing in review: the Makefile sets `GO_TEST_FLAGS ?= -vet=off` for test runs, on the grounds that `make lint` already covers vet-equivalent checks. Fine for the maintainers, worth knowing if you treat upstream test output as a signal.

The MCP server is typed and read-only, and writes need named authorization

`gog mcp` exposes a typed stdio MCP server. There is no generic shell or command bridge in it, which is the point: an agent gets a typed tool surface rather than a way to run arbitrary strings.

It is read-only by default. Writes require explicit command and tool authorization, so enabling a mutating path is a deliberate configuration step rather than a side effect of connecting the server.

The rest of the contract-generating machinery follows the same idea. Running `gog` with no arguments prints the executable path, a description, and local auth and config status; when JSON output is selected through the environment, that no-args view emits only the status JSON object, so a status probe stays parseable. The binary generates its own command schema, reference pages, and agent skills from the same command tree:

gog schema --json
gog schema gmail search --json
gog help drive inventory

The practical consequence: model-facing artifacts cannot drift from the binary, but they are produced from whatever version you run. Pin the version if your agent prompt depends on the schema shape, and re-check `gog schema` after upgrades rather than assuming compatibility.

Account routing spans five credential kinds, and headless hosts change the token backend

One installation routes among multiple Google accounts, named OAuth client projects, direct access tokens, Application Default Credentials, and Workspace service accounts. Aliases make the routing readable:

gog auth list --check
gog auth alias set work [email protected]
gog --account work gmail search 'is:unread'

Storage is the part that differs by environment. Tokens use the platform keyring by default, and headless systems can use an encrypted file backend instead. `docs/paths.md` covers `GOG_HOME`, XDG paths, and keyring storage, so where your tokens land is configurable but not automatic.

There are also hard account boundaries. Consumer Google accounts work with the user-facing APIs. Admin Directory, Cloud Identity Groups, Chat, Keep, and domain-wide delegation require a managed Google Workspace domain. If your plan assumes an admin console or group automation on a consumer account, that path is closed regardless of flags, and the Workspace Admin guide is the place to confirm the setup.

On a headless host, choose the token backend first: tokens use the platform keyring by default, and headless systems can use the encrypted file backend.

Editorial conclusion

gog fits teams that run Workspace from scripts, CI, or agents and want one binary with account routing plus JSON output. Adopt it only if you actually pass the narrowing flags: `--gmail-scope send` or `--gmail-scope read-send`, `--enable-commands-exact`, and `--readonly`, because the default Gmail authorization is broader than the least-privilege story implies. It does not fit a setup that needs Admin Directory, Cloud Identity Groups, Chat, Keep, or domain wide delegation without a managed Workspace domain. Before committing, confirm your OAuth client setup, choose your token backend for headless hosts, and decide whether you want the standard binary or a safety profile build.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes