Skip to content

quickstart.md

Latest commit

 

History

History
131 lines (99 loc) · 4.03 KB

quickstart.md

File metadata and controls

131 lines (99 loc) · 4.03 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 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.

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
⚡