Skip to content

paths.md

Latest commit

 

History

History
82 lines (63 loc) · 2.63 KB

paths.md

File metadata and controls

82 lines (63 loc) · 2.63 KB

Paths and State

gog separates configuration, durable data, mutable state, and regenerable cache paths. This keeps OAuth material and service-account keys out of config directories that are commonly synced as dotfiles, while still preserving legacy reads for existing installs.

Resolution Order

For config, data, state, and cache, the first configured path wins:

  1. GOG_CONFIG_DIR, GOG_DATA_DIR, GOG_STATE_DIR, or GOG_CACHE_DIR
  2. --home <path> for one invocation
  3. GOG_HOME
  4. The matching XDG variable: XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, or XDG_CACHE_HOME
  5. The platform default

GOG_*_DIR, GOG_HOME, and --home must resolve to absolute paths. Relative XDG values are ignored, matching the XDG Base Directory specification.

When GOG_HOME=/persist/gogcli, gog uses a flat kind layout:

/persist/gogcli/config
/persist/gogcli/data
/persist/gogcli/state
/persist/gogcli/cache

Per-kind overrides are literal directories. For example, GOG_DATA_DIR=/secure/gog-data stores data files directly below /secure/gog-data, without appending another gogcli component.

What Goes Where

  • Config: config.json, config locks, and backup configuration.
  • Data: OAuth client metadata, file-keyring entries, and service-account keys.
  • State: Gmail watch cursors and email tracking state.
  • Cache: Gmail backup intermediate cache.
  • Downloads: unchanged by the XDG/GOG split. Drive downloads and Gmail attachments keep their existing default directory unless the command's --out flag points elsewhere.

Compatibility

Existing installs are read-compatible:

  • OAuth credentials are read from the old config directory when the new data path does not contain them.
  • File-keyring users keep using the old keyring directory when it exists and no explicit data override is set.
  • Service-account keys are looked up in both the new data path and the old config path.
  • Tracking and Gmail watch state read legacy locations when new state files are absent.

New writes use the new path for the selected kind. auth credentials remove and service-account removal clean up both new and legacy locations where safe.

Containers and Agents

For a single persistent root:

docker run --rm -it \
  -e GOG_HOME=/persist/gogcli \
  -e GOG_KEYRING_BACKEND=file \
  -e GOG_KEYRING_PASSWORD \
  -v gogcli-state:/persist/gogcli \
  ghcr.io/openclaw/gogcli:latest \
  auth add you@gmail.com --services gmail,calendar,drive

For split lifetimes:

export GOG_CONFIG_DIR=/etc/gogcli
export GOG_DATA_DIR=/var/lib/gogcli
export GOG_STATE_DIR=/var/lib/gogcli-state
export GOG_CACHE_DIR=/var/cache/gogcli