Skip to main content
skill CX Codex

gdcli — Claude Code skill: Google Drive CLI for your editor

A skill that brings Google Drive operations to the terminal: list files, search by name or content, download and upload, create folders, share files. Triggered by commands like gdcli <email> ls or gdcli <email> search.

MIT 169 installs ★ 2,663 updated 2026-06-06

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add badlogic/pi-skills --skill gdcli -a claude-code
Open on GitHub

What gdcli does

gdcli wraps the Google Drive API as a set of command-line tools. After initial setup—creating an OAuth app in Google Cloud Console, a one-time step per account—the agent can browse folders, search files by name with ls --query, search file contents with search, download and upload files, make folders, and toggle public access. Credentials live in ~/.gdcli/credentials.json and account tokens in ~/.gdcli/accounts.json.

Setup requires npm and Google Cloud Console access: create a project, enable the Drive API, configure OAuth (the skill checks gdcli accounts list first, then takes the path to your downloaded JSON and adds your email via gdcli accounts add <email>). For headless environments, the --manual flag bypasses the browser flow.

Two search commands serve different purposes: search "text" hunts inside file contents (fullText), while ls --query "field = value" filters by metadata—name, type, modification date, ownership. For filename searches, use ls --query, not search.

What it helps with

  • search Google Drive files by name or metadata
  • download a file from Google Drive to your project by ID
  • upload a local file to Google Drive in a specific folder
  • create a new folder on Google Drive from a script or agent command
  • make a file publicly accessible with a shareable link

Example prompts for the agent

  • Find all PDFs in my Drive modified in January
  • Download the file with ID abc123def456 into the current project folder
  • Create a folder called 'reports' in Drive root and upload src/report.pdf to it

How to install gdcli

1Skills CLI (Vercel)

npx skills add badlogic/pi-skills --skill gdcli -a claude-code

2Manually: put the files in place

~/.claude/skills/gdcli/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/gdcli/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about gdcli

How do I install gdcli in Claude Code?

Run npx skills add badlogic/pi-skills --skill gdcli -a claude-code, then open ~/.claude/skills/gdcli/SKILL.md in your editor. Before first use, set up a Google Cloud project with Drive API enabled and run gdcli accounts add <email>.

What does gdcli do?

It's a command-line interface for Google Drive: the agent lists and searches files, downloads and uploads, creates folders, and shares files. Commands like gdcli <email> ls, gdcli <email> search, gdcli <email> upload.

Should I use search or ls --query to find files?

Use search "text" for full-text search inside file contents. For filename, type, or date searches, use ls --query "name contains 'report'" or ls --query "modifiedTime > '2024-01-01'".

Source text

SKILL.md · MIT
---
name: gdcli
description: Google Drive CLI for listing, searching, uploading, downloading, and sharing files and folders.
---

# Google Drive CLI

Command-line interface for Google Drive operations.

## Installation

```bash
npm install -g @mariozechner/gdcli
```

## Setup

### Google Cloud Console (one-time)

1. [Create a new project](https://console.cloud.google.com/projectcreate) (or select existing)
2. [Enable the Google Drive API](https://console.cloud.google.com/apis/api/drive.googleapis.com)
3. [Set app name](https://console.cloud.google.com/auth/branding) in OAuth branding
4. [Add test users](https://console.cloud.google.com/auth/audience) (all Gmail addresses you want to use)
5. [Create OAuth client](https://console.cloud.google.com/auth/clients):
   - Click "Create Client"
   - Application type: "Desktop app"
   - Download the JSON file

### Configure gdcli

First check if already configured:
```bash
gdcli accounts list
```

If no accounts, guide the user through setup:
1. Ask if they have a Google Cloud project with Drive API enabled
2. If not, walk them through the Google Cloud Console steps above
3. Have them download the OAuth credentials JSON
4. Run: `gdcli accounts credentials ~/path/to/credentials.json`
5. Run: `gdcli accounts add <email>` (use `--manual` for browserless OAuth)

## Usage

Run `gdcli --help` for full command reference.

Common operations:
- `gdcli <email> ls [folderId]` - List files/folders
- `gdcli <email> ls --query "<query>"` - List with Drive query filter
- `gdcli <email> search "<text>"` - Full-text content search
- `gdcli <email> download <fileId> [destPath]` - Download a file
- `gdcli <email> upload <localPath> [--folder <folderId>]` - Upload a file
- `gdcli <email> mkdir <name>` - Create a folder
- `gdcli <email> share <fileId> --anyone` - Share publicly

## Search

**Two different commands:**
- `search "<text>"` - Searches inside file contents (fullText)
- `ls --query "<query>"` - Filters by metadata (name, type, date, etc.)

**Use `ls --query` for filename searches!**

## Query Syntax (for ls --query)

Format: `field operator value`. Combine with `and`/`or`, group with `()`.

**Operators:** `=`, `!=`, `contains`, `<`, `>`, `<=`, `>=`

**Examples:**
```bash
# By filename
ls --query "name = 'report.pdf'"           # exact match
ls --query "name contains 'IMG'"           # prefix match

# By type
ls --query "mimeType = 'application/pdf'"
ls --query "mimeType contains 'image/'"
ls --query "mimeType = 'application/vnd.google-apps.folder'"  # folders

# By date
ls --query "modifiedTime > '2024-01-01'"

# By owner/sharing
ls --query "'me' in owners"
ls --query "sharedWithMe"

# Exclude trash
ls --query "trashed = false"

# Combined
ls --query "name contains 'report' and mimeType = 'application/pdf'"
```

Ref: https://developers.google.com/drive/api/guides/ref-search-terms

## Data Storage

- `~/.gdcli/credentials.json` - OAuth client credentials
- `~/.gdcli/accounts.json` - Account tokens
- `~/.gdcli/downloads/` - Default download location

© badlogic · MIT · badlogic/pi-skills

Similar skills

All skills for Cloud: AWS, Azure, GCP →

From the same set8

More in the catalog

Project sponsors

Companies that keep this analytics open