Google Drive CLI

A command-line interface for Google Drive.

Features

- 🔐 OAuth2 authentication
- 👥 Multi-profile support (multiple Gdrive accounts)
- 📤 Upload files to Google Drive
- 📥 Download files from Google Drive (by path or ID)
- 📄 Export Google Docs/Sheets/Slides to various formats
- 📂 List files and folders
- 🔍 Advanced search with filters (type, date, owner, size, etc.)
- 🎨 Beautiful colored output with chalk
- ⚡ Loading spinners with ora

Installation

Install globally to use the gdrive command anywhere:

``bash
npm install -g gdrive-cli
`

Configuration




$3

1. Go to Google Cloud Console
2. Create a new project (or select existing one)
3. Enable Drive API
4. Create OAuth 2.0 credentials (Desktop app)
5. Download credentials as JSON




$3

Create config directory:

`bash
mkdir -p ~/.config/gdrive
`

Create ~/.config/gdrive/config.json:

`json
{
"profiles": {
"default": {
"GDRIVE_OAUTH_PATH": "/path/to/client_secret_xxx.json"
}
}
}
`

Where GDRIVE_OAUTH_PATH points to the OAuth client credentials JSON file you downloaded from Google Cloud Console (contains client_id, client_secret, etc.).

#### Multiple profiles

You can configure multiple Gdrive accounts by adding more profiles:

`json
{
"profiles": {
"default": {
"GDRIVE_OAUTH_PATH": "/path/to/personal_client_secret.json"
},
"work": {
"GDRIVE_OAUTH_PATH": "/path/to/work_client_secret.json"
}
}
}
`

Each profile can use a different Google Cloud OAuth app, allowing complete separation between accounts.




$3

`bash
gdrive auth login
`

This will:
- Open your browser for authorization
- Start a local server to capture the OAuth callback
- Save the token to ~/.config/gdrive/{profile}.token.json

For other profiles, use the --profile option:

`bash
gdrive --profile work auth login
`

Usage

$3

`bash
--profile Profile to use (default: "default")
--version Show version number
--help Show help
`

All commands support the --profile option:

`bash
gdrive --profile work email search "is:unread"
gdrive --profile work auth status
`

$3

`bash


Login

gdrive auth login

Check authentication status

gdrive auth status

Logout

gdrive auth logout
`

$3

#### Upload files

`bash


Upload to root directory

gdrive file upload ./report.pdf

Upload to specific folder

gdrive file upload ./report.pdf "Work/Reports"

Upload with JSON output

gdrive file upload ./data.csv "Data" --json
`

#### List files

`bash


List root directory

gdrive file ls

List specific folder

gdrive file ls "Work/Reports"

List with JSON output

gdrive file ls "Documents" --json
`

#### Download files by path

`bash


Download file from root

gdrive file get "report.pdf" "./local-report.pdf"

Download file from folder

gdrive file get "Work/Reports/Q1.pdf" "./Q1-report.pdf"

Download with JSON output

gdrive file get "data.csv" "./data.csv" --json
`

#### Export files by ID

Use export when you have the Google Drive file ID (useful for shared links or API integrations).

`bash


Download a regular file (PDF, image, etc.)


gdrive file export 1v4wlXvI_i8BCJZtBlxjHi3YJyOfebZGuqevq8cGcG2k ./output.pdf
`

Google Workspace files (Docs, Sheets, Slides) are automatically exported to their Office equivalent:

| Google Format | Default Export |
|---------------|----------------|
| Google Docs | .docx |
| Google Sheets | .xlsx |
| Google Slides | .pptx |

`bash


Export a Google Doc to docx (automatic)

gdrive file export 1abc123def456 ./document.docx

Export a Google Sheet to xlsx (automatic)

gdrive file export 1xyz789ghi012 ./spreadsheet.xlsx
`

Custom export formats with --format:

`bash


Export Google Doc as PDF

gdrive file export 1abc123def456 ./document.pdf --format pdf

Export Google Doc as plain text

gdrive file export 1abc123def456 ./document.txt --format txt

Export Google Doc as HTML

gdrive file export 1abc123def456 ./document.html --format html

Export Google Doc as Markdown

gdrive file export 1abc123def456 ./document.md --format md

Export Google Sheet as CSV

gdrive file export 1xyz789ghi012 ./data.csv --format csv

Export Google Sheet as PDF

gdrive file export 1xyz789ghi012 ./spreadsheet.pdf --format pdf
`

Supported export formats:

| Format | MIME Type | Best for |
|--------|-----------|----------|
| pdf | application/pdf | Universal sharing |
| docx | Word document | Google Docs |
| xlsx | Excel spreadsheet | Google Sheets |
| pptx | PowerPoint presentation | Google Slides |
| txt | Plain text | Google Docs |
| md | Markdown | Google Docs |
| html | HTML | Google Docs |
| csv | CSV | Google Sheets |

#### Search files

Search for files in Google Drive with powerful filters.

`bash


Basic full-text search (searches name and content)

gdrive file search "quarterly report"

Search by file name

gdrive file search --name "budget"

Search by file type

gdrive file search --type doc # Google Docs
gdrive file search --type sheet # Google Sheets
gdrive file search --type slide # Google Slides
gdrive file search --type folder # Folders only
gdrive file search --type pdf # PDF files
gdrive file search --type image # All images

Filter by date

gdrive file search --after 2024-01-01
gdrive file search --before 2024-12-31
gdrive file search --after 2024-01-01 --before 2024-06-30

Filter by owner

gdrive file search --owner "colleague@gmail.com"

Filter by size

gdrive file search --min-size 10MB
gdrive file search --max-size 100MB
gdrive file search --min-size 1MB --max-size 50MB

Special filters

gdrive file search --starred # Starred files only
gdrive file search --shared-with-me # Files shared with me
gdrive file search --trashed # Search in trash

Search in specific folder (by folder ID)

gdrive file search --parent 1abc123def456

Combine multiple filters

gdrive file search --type doc --starred --after 2024-01-01
gdrive file search --type sheet --owner "team@company.com" --name "budget"

Limit results and sort

gdrive file search --type pdf --limit 10
gdrive file search --type doc --order-by name

JSON output for scripting

gdrive file search --type folder --json
gdrive file search "report" --json | jq '.[].id'
`

Supported file types:

| Alias | Description |
|-------|-------------|
| doc, document | Google Docs |
| sheet, spreadsheet | Google Sheets |
| slide, presentation | Google Slides |
| folder | Folders |
| form | Google Forms |
| drawing | Google Drawings |
| pdf | PDF files |
| image | All image types |
| video | All video types |
| audio | All audio types |
| text | Plain text files |
| csv | CSV files |
| json | JSON files |
| docx, xlsx, pptx | Microsoft Office |

Search options reference:

| Option | Short | Description |
|--------|-------|-------------|
| --type | -t | File type filter |
| --name | -n | Name contains pattern |
| --parent | -p | Files in specific folder |
| --after | | Modified after date (YYYY-MM-DD) |
| --before | | Modified before date (YYYY-MM-DD) |
| --owner | -o | Files owned by email |
| --min-size | | Minimum file size (e.g., 10MB) |
| --max-size | | Maximum file size (e.g., 1GB) |
| --shared | | Only shared/public files |
| --not-shared | | Only private files |
| --shared-with-me | | Files shared with me |
| --starred | | Only starred files |
| --trashed | | Search in trash |
| --full-text | -f | Full-text content search |
| --limit | -l | Max results (default: 50) |
| --order-by | | Sort by: name, modifiedTime |
| --json | | Output as JSON |

Examples

$3

`bash


Step 1: Check authentication

gdrive auth status

Step 2: List target directory to verify it exists

gdrive file ls "Work"

Step 3: Upload the file

gdrive file upload ./report.pdf "Work/Reports"
`

$3

`bash


Step 1: List directory to find the file

gdrive file ls "Work/Reports"

Step 2: Download the file

gdrive file get "Work/Reports/Q1.pdf" "./Q1.pdf"
`

$3

`bash


Step 1: List directory to get the file ID

gdrive file ls "Documents" --json | jq '.[] | {name, id}'

Step 2: Export using the ID

gdrive file export 1abc123def456 ./document.docx

Or export a Google Doc to PDF

gdrive file export 1abc123def456 ./document.pdf --format pdf
`

$3

`bash


Create organization by uploading to specific folders

gdrive file upload ./design.pdf "Projects/WebApp/Design"
gdrive file upload ./code.zip "Projects/WebApp/Code"
gdrive file upload ./report.pdf "Projects/WebApp/Reports"

List all files in project

gdrive file ls "Projects/WebApp"
`

Output Formats

Most commands support the --json flag for machine-readable output:

`bash


Get JSON output for upload

gdrive file upload ./file.pdf --json | jq '.id'

Get JSON output for file listing

gdrive file ls --json | jq '.[] | .name'
`

Technical Details

$3

- commander - CLI framework
- googleapis - Google APIs client library
- google-auth-library - OAuth2 authentication
- mime-types - MIME type detection for file uploads
- chalk - Colored terminal output
- ora - Loading spinners
- open - Open browser for OAuth flow

$3

The CLI requires the following scopes:
- https://www.googleapis.com/auth/drive -
- https://www.googleapis.com/auth/drive.file - Create and modify files

$3

File paths in Google Drive are specified using forward slashes:
- Root directory: "" (empty string) or omit the parameter
- Subfolder: "Work/Reports"
- File in subfolder: "Work/Reports/Q1.pdf"

$3

- Files larger than 5TB cannot be uploaded (Google Drive API limit)
- Folder paths must exist before uploading (folders are not created automatically)
- Downloaded files overwrite existing local files without warning
- Google Workspace files (Docs, Sheets, Slides) can only be downloaded via export (not get)
- Export size limits apply to Google Workspace files (10MB for most exports, 100 sheets for spreadsheets)

Troubleshooting

$3

`bash


Check authentication status

gdrive auth status

Re-authenticate if needed

gdrive auth login
`

$3

Create the configuration file:

`bash
mkdir -p ~/.config/gdrive
nano ~/.config/gdrive/config
`

Add your credentials path:
`
GDRIVE_OAUTH_PATH=/path/to/oauth.keys.json
`

$3

For local files:
`bash


Use absolute paths or verify relative paths


gdrive file upload /absolute/path/to/file.pdf
gdrive file upload ./relative/path/to/file.pdf
`

For Google Drive files:
`bash


List the directory first to see available files

gdrive file ls "Work/Reports"

Then download with the correct path

gdrive file get "Work/Reports/Q1.pdf" "./Q1.pdf"
`

$3

List parent folders to verify the path:

`bash


Check root directory

gdrive file ls

Check subdirectory

gdrive file ls "Work"
``

License

MIT