Skip to content

quickstart.md

Latest commit

 

History

History
174 lines (134 loc) · 6.08 KB

quickstart.md

File metadata and controls

174 lines (134 loc) · 6.08 KB
title Quickstart
description Five minutes from a clean machine to a working gog setup with one Google account.

Quickstart

Five minutes from a clean machine to authenticated Gmail, Calendar, and Drive queries. For a deeper look at OAuth clients, service accounts, and named profiles, read Auth Clients after this.

1. Install

brew install openclaw/tap/gogcli
gog --version

Other options (Docker, Windows ZIPs, source builds) are documented on Install.

2. Get an OAuth client

gog talks to Google APIs as you, using your own Cloud project. The one-time setup is:

  1. Open https://console.cloud.google.com/projectcreate and create a project.
  2. Enable the APIs you intend to use: Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Apps Script, People (Contacts), Tasks, Classroom — whatever you actually need. The API library is the fastest way to enable several at once.
  3. Configure the OAuth consent screen for "External" + your email; that is enough for personal use.
  4. Create a Desktop app OAuth client at https://console.cloud.google.com/auth/clients and download the JSON.

Personal gmail.com accounts work for normal user APIs (Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Apps Script, Contacts/People, Tasks, Classroom). Workspace-only APIs (Admin Directory, Cloud Identity Groups, Chat, Keep with domain-wide delegation) require a managed domain — see Auth Clients.

Avoid weekly reauthorization: External + Testing OAuth apps issue refresh tokens for user-data scopes that expire after seven days. In the same Cloud project, open Audience, click Publish app, then Confirm. This changes the app to In production; it does not submit the app for verification. If you already authorized in Testing, re-run gog auth add once with the same services and --force-consent. Personal unverified apps can run In production, but sensitive scopes show a warning and remain subject to the lifetime 100-user cap. See Google's expiration rules and unverified-app limits.

3. Store the OAuth client

gog auth credentials ~/Downloads/client_secret_*.json

The file is copied to your per-user config ($XDG_CONFIG_HOME/gogcli/ or the OS-equivalent) with mode 0600.

4. Authorize an account

gog auth add you@gmail.com --services gmail,calendar,drive,docs,sheets,contacts

A browser tab opens, you grant the requested scopes, and gog stores a refresh token in your OS keyring (Keychain on macOS, Secret Service on Linux, Credential Manager on Windows). Headless? Add --manual for a paste-the-URL flow, or --remote --step 1/--step 2 for fully split server runs.

Installed-app authorization uses S256 PKCE. Complete a manual or remote flow with the same gog home and client that generated its URL. After upgrading from a pre-PKCE release, restart any unfinished flow at step 1.

Verify:

gog auth list --check
gog auth doctor --check

5. Set a default account

export GOG_ACCOUNT=you@gmail.com
# or persist a default with gog auth alias
gog auth alias set default you@gmail.com

Now you can drop --account from every command.

6. Run real commands

# Gmail
gog gmail search 'newer_than:7d' --max 10
gog gmail get <messageId> --sanitize-content --json

# Calendar
gog calendar events --today
gog calendar create --summary "Review" \
  --from "2026-05-06T10:00:00+02:00" \
  --to   "2026-05-06T10:30:00+02:00"

# Drive
gog drive ls --max 20
gog drive tree --parent <folderId> --depth 2
gog drive du   --parent <folderId> --max 20 --json
gog drive shortcut create <fileId> --parent <folderId>

# Docs / Sheets / Slides
gog docs cat <docId> --tab "Notes"
gog sheets get <spreadsheetId> 'Sheet1!A1:D20' --json
gog slides create-from-markdown "Weekly update" --content-file slides.md

# Profile
gog me

--json produces a stable JSON envelope on stdout; --plain produces TSV. Human-facing progress, hints, and warnings always go to stderr, so pipes stay parseable.

Workspace admins can create users and manage organizational units after configuring Admin SDK access and domain-wide delegation:

gog --account admin@example.com admin users create ada@example.com \
  --first-name Ada \
  --last-name Lovelace \
  --change-password

gog --account admin@example.com admin orgunits list --type all

Cloud Identity Groups also require the Workspace service account and the https://www.googleapis.com/auth/cloud-identity.groups.readonly delegated scope:

gog --account admin@example.com groups list

With an explicit access token or GOG_AUTH_MODE=adc, groups list and Groups backups also need --account <workspace-email> for their transitive membership search. groups members can use the active principal without that flag. calendar team uses the same Groups auth boundary. These Cloud Identity lookups do not fall back to stored user OAuth.

See Workspace Admin for service-account setup, generated passwords, recovery fields, organizational units, and cleanup commands.

7. Shell completion (optional)

gog completion bash    >> ~/.bash_completion
gog completion zsh     >  "${fpath[1]}/_gog"
gog completion fish    >  ~/.config/fish/completions/gog.fish

Where next

  • Auth Clients — named clients, service accounts, ADC, Workspace domain-wide delegation, OIDC subject migration.
  • Workspace Admin — create, inspect, suspend, delete, and list Workspace users, organizational units, and groups.
  • Safety Profiles — runtime allow/deny lists and baked agent-safe binaries.
  • Gmail Workflows and Drive Audits for the two surfaces most people start automating.
  • Command Index — generated reference for every subcommand.