---
name: gog-auth
description: "Inspect and fix Google auth for the gog CLI: list/add/remove accounts, diagnose keyring and refresh-token problems, manage OAuth client credentials, aliases, and Workspace service accounts. Use before any other gog command when auth state is unknown or broken."
---

# gog auth

Auth and credential management for `gog`. Run these to verify an account exists,
diagnose a failure, or set up a new login. Almost every other `gog` skill
depends on this being healthy first.

## Diagnose (safe for agents)

```bash
gog auth list --check --json --no-input        # accounts + per-account service scopes
gog auth status --json --no-input              # config + keyring backend
gog auth doctor --check --json --no-input       # diagnose keyring / refresh-token issues
gog auth services --json                        # supported services and scopes
gog auth credentials list --json                # stored OAuth client credentials (no secrets)
gog auth alias list --json
```

## Add / remove (partly interactive — human completes browser consent)

```bash
gog auth add you@example.com --services all-user --force-consent
gog auth remove you@example.com
gog auth import --no-input < refresh_token        # non-interactive token import
```

On reauth, **preserve existing broad scope** — inspect the account's current
`services` from `auth list` first; prefer `--services all-user --force-consent`
and do not silently narrow scopes unless the user asks. Narrow services only for
throwaway/bot accounts. Enforce safety at command time (allowlists, dry-runs),
not by under-scoping durable user auth.

## Service accounts (Workspace-only, domain-wide delegation)

```bash
gog auth service-account status --json
gog auth service-account set <key.json>
```

Service accounts mainly fit Admin, Groups, and Keep; they do not solve consumer
`@gmail.com` OAuth.

## Safety

- **Never print** access tokens, refresh tokens, OAuth client secrets, or keyring
  passwords. `auth tokens export`/`import` handle secret files — keep their
  contents out of output.
- Headless/containers: `GOG_KEYRING_BACKEND=file` + `GOG_KEYRING_PASSWORD` (and
  `HOME`) must be present in the process that launches `gog` — verify the
  service environment, not just the login shell.
- Use `--no-input` so keyring/consent prompts fail clearly instead of hanging.

## Discovery

Subcommands and flags change across versions — confirm before relying on them:
`gog auth --help` · `gog auth <cmd> --help` · `gog schema auth <cmd> --json`
Reference: <https://gogcli.sh/>
