Google Drive (gws drive)

gws drive provides CLI access to Google Drive with structured JSON output.

Disclaimer: gws is not the official Google CLI. This is an independent, open-source project not endorsed by or affiliated with Google.

Dependency Check

Before executing any gws command, verify the CLI is installed:

gws version

If not found, install: go install github.com/omriariav/workspace-cli/cmd/gws@latest

Authentication

Requires OAuth2 credentials. Run gws auth status to check. If not authenticated: gws auth login (opens browser for OAuth consent). For initial setup, see the gws-auth skill.

Quick Command Reference

Detailed Usage

list — List files

gws drive list [flags]

Flags:

• •--folder string — Folder ID to list (default: "root")
• •--max int — Maximum number of files (default 50)
• •--order string — Sort order (default: "modifiedTime desc")

Examples:

gws drive list
gws drive list --folder 1abc123xyz --max 20
gws drive list --order "name"

search — Search for files

gws drive search <query> [flags]

Flags:

• •--max int — Maximum number of results (default 50)

Examples:

gws drive search "quarterly report"
gws drive search "budget 2024" --max 10

info — Get file info

gws drive info <file-id>

Gets detailed information about a file including name, type, size, owners, and permissions.

download — Download a file

gws drive download <file-id> [flags]

Flags:

• •--output string — Output file path (default: original filename)

Examples:

gws drive download 1abc123xyz
gws drive download 1abc123xyz --output ./local-copy.pdf

upload — Upload a file

gws drive upload <local-file> [flags]

Flags:

• •--folder string — Parent folder ID (default: root)
• •--name string — File name in Drive (default: local filename)
• •--mime-type string — MIME type (auto-detected if not specified)

Examples:

gws drive upload report.pdf
gws drive upload data.xlsx --folder 1abc123xyz
gws drive upload document.docx --name "My Report"

create-folder — Create a new folder

gws drive create-folder --name <name> [flags]

Flags:

• •--name string — Folder name (required)
• •--parent string — Parent folder ID (default: root)

Examples:

gws drive create-folder --name "Project Files"
gws drive create-folder --name "Subproject" --parent 1abc123xyz

move — Move a file

gws drive move <file-id> --to <folder-id>

Flags:

• •--to string — Destination folder ID (required)

Examples:

gws drive move 1abc123xyz --to 2def456uvw
gws drive move 1abc123xyz --to root

delete — Delete a file

gws drive delete <file-id> [flags]

By default, moves the file to trash. Use --permanent to permanently delete.

Flags:

• •--permanent — Permanently delete (skip trash)

Examples:

gws drive delete 1abc123xyz
gws drive delete 1abc123xyz --permanent

comments — List comments on a file

gws drive comments <file-id> [flags]

Lists all comments and replies on a Google Drive file (works with Docs, Sheets, Slides).

Flags:

• •--max int — Maximum number of comments (default 100)
• •--include-resolved — Include resolved comments
• •--include-deleted — Include deleted comments

Examples:

gws drive comments 1abc123xyz
gws drive comments 1abc123xyz --include-resolved

Output Modes

gws drive list --format json    # Structured JSON (default)
gws drive list --format text    # Human-readable text

Tips for AI Agents

• •Always use --format json (the default) for programmatic parsing
• •Use gws drive search to find files by name, then gws drive info <id> for details
• •File IDs from Google Docs/Sheets/Slides URLs can be extracted from the URL path
• •Delete moves to trash by default — use --permanent only when explicitly requested
• •When uploading, MIME type is auto-detected from the file extension
• •The comments command works on any Drive file type (Docs, Sheets, Slides, etc.)
• •Resolved comments are excluded by default; use --include-resolved to see them