Skip to content

SETUP.md

Latest commit

 

History

History
199 lines (143 loc) · 5.38 KB

SETUP.md

File metadata and controls

199 lines (143 loc) · 5.38 KB
Raw

gcli — first-time setup

For whom: a step-by-step guide to set up gcli from scratch for your own Google account. Works for a human or for an AI coding agent (Claude Code) following along.

What this is

gcli is a command-line tool for working with Google services from the terminal:

  • Gmail — read, search, send mail
  • Google Drive — files, folders, upload/download
  • Google Sheets — read, write, create
  • Google Calendar — view, create, edit events
  • Google Docs — read, create, append text

Each user runs it against their own Google Cloud project and OAuth credentials. This repo contains no keys.

Prerequisites

  • macOS or Linux
  • Python 3.9+
  • pip3
  • A Google account
  • A browser (for the one-time OAuth authorization)

Step 1: Get the code

git clone https://github.com/ambymon/google-cli.git
cd google-cli

You only need these files (already in the repo):

google-cli/
  setup.py
  requirements.txt
  .gitignore
  gcli/
    __init__.py
    main.py
    auth.py
    output.py
    mail.py
    drive.py
    sheets.py
    calendar.py
    docs.py

IMPORTANT: the repo does not ship credentials.json or token.json. You create your own in the next steps. Never commit them.

Step 2: Create a Google Cloud project

These steps happen in the browser. An AI agent can't do them for you.

2.1 Create the project

  1. Open console.cloud.google.com
  2. Sign in with your Google account
  3. Click the project picker at the top → New Project
  4. Name it (e.g. my-cli-tools)
  5. Click Create
  6. Make sure the new project is selected at the top

2.2 Enable the APIs

Go to APIs & Services → Library and enable each of these (click Enable):

  1. Gmail API
  2. Google Drive API
  3. Google Sheets API
  4. Google Calendar API
  5. Google Docs API

2.3 Configure the OAuth consent screen

  1. Go to APIs & Services → OAuth consent screen
  2. Choose External (unless you're on Google Workspace) → Create
  3. Fill in:
    • App name: anything (e.g. My CLI)
    • User support email: your email
    • Developer contact email: your email
  4. Click Save and Continue
  5. On Scopes — just click Save and Continue (scopes are requested at login time)
  6. On Test users — add your own email (the same Google account)
  7. Save and Continue → Back to Dashboard

2.4 Create an OAuth Client ID

  1. Go to APIs & Services → Credentials
  2. Click Create Credentials → OAuth client ID
  3. Application type: Desktop app
  4. Name: anything (e.g. gcli)
  5. Click Create
  6. In the dialog, click Download JSON
  7. Save the file as credentials.json in the google-cli/ folder (next to setup.py)

Step 3: Install dependencies

From the google-cli/ folder:

pip3 install -r requirements.txt
pip3 install -e .

Check it installed:

gcli --help

It should list the command groups (mail, drive, sheets, calendar, docs, auth).

Step 4: Authorize

Run:

gcli auth status
  1. A browser opens with the Google authorization page
  2. Pick your account
  3. You may see "Google hasn't verified this app" — click Advanced → Go to My CLI (unsafe). This is normal for an app in testing mode that only you use.
  4. Click Continue / Allow for the requested permissions
  5. On success the terminal confirms it

A token.json file is created automatically — it stores your authorization token.

Step 5: Smoke test

gcli mail list --max 3
gcli drive ls
gcli calendar events
gcli sheets list
gcli docs list

If those work, you're done.

Using it from Claude Code (or any AI agent)

The agent calls gcli via shell commands. For programmatic parsing always add --json:

gcli --json mail list --max 5
gcli --json drive ls
gcli --json calendar events --days 7

Command reference

Service Commands
Gmail mail list, mail search "query", mail read <id>, mail send --to --subject --body, mail reply <id> --body, mail drafts, mail draft --to --subject --body
Drive drive ls [folder_id], drive search "name", drive upload <path>, drive download <id> <path>, drive mkdir "name", drive delete <id>
Sheets sheets list, sheets read <id> [--range], sheets write <id> --range --data, sheets create "name"
Calendar calendar events [--days N], calendar create --title --start --end, calendar edit <id>, calendar delete <id>
Docs docs list, docs read <id>, docs create "name" [--body], docs append <id> --text

Troubleshooting

Problem Fix
credentials.json not found Download the OAuth client JSON from Google Cloud Console (Step 2.4) and save it next to setup.py
Access blocked: app not verified Click Advanced → Go to ... (unsafe). Normal for testing mode
gcli: command not found Run pip3 install -e . again, or use python3 -m gcli
Token has been expired or revoked Delete token.json and run gcli auth status again
Quota exceeded Wait a minute and retry, or check API limits in Cloud Console

Security

  • Never share credentials.json or token.json — they grant access to your Google account
  • Both are in .gitignore
  • Tokens are stored locally only
  • Delete commands always ask for confirmation