<div align="center" <img src=".github/assets/logo.svg" alt="gcli Logo" width="200" <h1gcli</h1
<a href="https://github.com/tanq16/gcli/actions/workflows/release.yaml"<img alt="Build Workflow" src="https://github.com/tanq16/gcli/actions/workflows/release.yaml/badge.svg"</a <a href="https://github.com/tanq16/gcli/releases"<img alt="GitHub Release" src="https://img.shields.io/github/v/release/tanq16/gcli"</a<br<br <a href="#capabilities"Capabilities</a • <a href="#installation"Installation</a • <a href="#authentication"Authentication</a • <a href="#usage"Usage</a • <a href="#output-modes--scripting"Output Modes</a • <a href="#tips-and-notes"Tips & Notes</a </div
---
gcli is a fully command-line tool for Google Drive (the primary product) and Gmail (a secondary, general-aid). Drive is treated as optimized storage: upload, download, cat, mirroring sync, and sharing, all with a Linux-style command surface, a shared concurrent transfer engine, and recoverable deletes. Gmail covers everyday email automation, send, reply, forward, drafts, and thread state, and nothing more. Every command speaks three output tiers so the same tool works for a human at a terminal, a --debug session, and a fully non-interactive --for-ai agent.
Capabilities
| Service | Commands | Description | |---------|----------|-------------| | Auth | login, login --setup, logout, whoami | BYO OAuth (PKCE, paste-the-redirect-URL), guided setup wizard, revoke, and account/storage status | | Drive | ls (list), info, search | Browse folders, inspect one item, search by name/content/type/time/size | | Drive | up (upload), dl (download), cat | Concurrent, resumable transfers; stream remote bytes to stdout | | Drive | sync | Destructive-mirror folder↔folder (or file↔file) with recoverable deletes, --reverse, --backup, --dry-run | | Drive | mkdir, mv (move), rm (remove/delete), purge | Create, move+rename, trash (recoverable), and permanently delete | | Drive | trash list/restore/empty | List, restore by name, and empty Drive trash | | Drive | share, unshare | Grant/revoke by email, anyone-with-link, expiring links; list current shares | | Mail | list, search, get (view) | List/search threads; read a full thread (HTML rendered to text) | | Mail | send, reply, forward | Compose with attachments and signatures; forward re-attaches originals | | Mail | mark <verb | read, unread, star, unstar, archive, trash, spam | | Mail | drafts (draft) list/get/edit/send/rm | Manage Gmail drafts; create a draft with --draft on any compose command |
File revisions are exposed as flags on existing commands, not a separate group: info --revisions (list), download --revision <id (fetch an old version), upload --keep-revision (pin the pushed head).
Installation
Binary
Download from releases:
# Linux/macOS
ARCH=$(uname -m); [ "$ARCH" = "x86_64" ] && ARCH=amd64; [ "$ARCH" = "aarch64" ] && ARCH=arm64
curl -sL https://github.com/tanq16/gcli/releases/latest/download/gcli-$(uname -s | tr '[:upper:]' '[:lower:]')-$ARCH -o gcli
chmod +x gcli
sudo mv gcli /usr/local/bin/go install
go install github.com/tanq16/gcli@latestBuild from Source
git clone https://github.com/tanq16/gcli
cd gcli
make buildAuthentication
gcli uses a bring-your-own OAuth client (BYO). There is no shipped shared client: an embedded secret in open-source cannot stay confidential, and a single client would hit Google's 100-user unverified cap across all installs. Setup is a one-time Google Cloud task; the wizard asks whether you already have a Desktop-app client, and if not prints a short block (two API links + the console steps) before taking your Client ID and secret:
gcli login --setup # guided wizard: enable APIs, consent screen, Desktop-app client
gcli login # opens your browser (or prints the URL); you paste the redirect URL back
gcli whoami # which account am I, and will a backup fit?
gcli logout # revoke the refresh token with Google, then delete it locally