Start

Quickstart

GitHub Edit page

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 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,

    3. 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

    4. for "External" + your email; that is enough for personal use.

  4. Create a Desktop app OAuth client at

    5. 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.

External + Testing OAuth apps issue refresh tokens that expire after seven days. Publish the OAuth app for long-lived tokens, or be ready to re-run gog auth add weekly.

#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.

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

# 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.

#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