gdcli

badlogic's avatarfrom badlogic

Google Drive CLI for listing, searching, uploading, downloading, and sharing files and folders.

⭐72stars🔀6forks📁View on GitHub🕐Updated Dec 23, 2025
[Files and Documents]

When & Why to Use This Skill

The Google Drive CLI (gdcli) skill enables Claude to interact directly with Google Drive for comprehensive file and folder management. It provides a powerful interface for listing, searching, uploading, downloading, and sharing assets, utilizing advanced query syntax for precise metadata filtering and full-text content search.

Use Cases

  • 1. Automated Cloud Storage Management: Streamline workflows by allowing the agent to organize, upload, or download files from Google Drive without manual browser intervention.
  • 2. Advanced Document Retrieval: Use complex queries to find specific documents based on file type, modification date, or content, making it ideal for managing large-scale knowledge bases.
  • 3. Seamless Collaboration: Quickly generate public share links or manage folder permissions to facilitate rapid sharing of assets with team members.
  • 4. Agentic Data Pipelines: Enable AI agents to save their outputs directly to the cloud or read context from existing Google Drive documents to enhance task execution.
namegdcli
descriptionGoogle Drive CLI for listing, searching, uploading, downloading, and sharing files and folders.

Google Drive CLI

Command-line interface for Google Drive operations.

Installation

npm install -g @mariozechner/gdcli

Setup

Google Cloud Console (one-time)

  1. Create a new project (or select existing)
  2. Enable the Google Drive API
  3. Set app name in OAuth branding
  4. Add test users (all Gmail addresses you want to use)
  5. Create OAuth client:
    • Click "Create Client"
    • Application type: "Desktop app"
    • Download the JSON file

Configure gdcli

First check if already configured:

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

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:

# 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