132 lines
4.0 KiB
Markdown
132 lines
4.0 KiB
Markdown
---
|
|
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](auth-clients.md) after this.
|
|
|
|
## 1. Install
|
|
|
|
```bash
|
|
brew install gogcli
|
|
gog --version
|
|
```
|
|
|
|
Other options (Docker, Windows ZIPs, source builds) are documented on
|
|
[Install](install.md).
|
|
|
|
## 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](https://console.cloud.google.com/apis/library)
|
|
is the fastest way to enable several at once.
|
|
3. Configure the [OAuth consent screen](https://console.cloud.google.com/auth/branding)
|
|
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](auth-clients.md).
|
|
|
|
> 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
gog auth list --check
|
|
gog auth doctor --check
|
|
```
|
|
|
|
## 5. Set a default account
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
gog completion bash >> ~/.bash_completion
|
|
gog completion zsh > "${fpath[1]}/_gog"
|
|
gog completion fish > ~/.config/fish/completions/gog.fish
|
|
```
|
|
|
|
## Where next
|
|
|
|
- [Auth Clients](auth-clients.md) — named clients, service accounts, ADC,
|
|
Workspace domain-wide delegation, OIDC subject migration.
|
|
- [Safety Profiles](safety-profiles.md) — runtime allow/deny lists and baked
|
|
agent-safe binaries.
|
|
- [Gmail Workflows](gmail-workflows.md) and [Drive Audits](drive-audits.md) for
|
|
the two surfaces most people start automating.
|
|
- [Command Index](commands/) — generated reference for every subcommand.
|