| name | gws-drive |
| description | Google Drive CLI operations via gws. Use when users need to list, search, upload, download, manage files/folders, permissions, approvals, revisions, comments, shared drives, and more. Triggers: drive, files, upload, download, folders, google drive, file management, permissions, approvals, share, shared drives. |
| metadata | {"short-description":"Google Drive CLI operations","compatibility":"claude-code, codex-cli"} |
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
Files & Folders
| Task | Command |
|---|
| List files | gws drive list |
| List files in folder | gws drive list --folder <folder-id> |
| Search files | gws drive search "quarterly report" |
| Get file info | gws drive info <file-id> |
| Download a file | gws drive download <file-id> |
| Upload a file | gws drive upload report.pdf |
| Create a folder | gws drive create-folder --name "Project Files" |
| Move a file | gws drive move <file-id> --to <folder-id> |
| Delete a file | gws drive delete <file-id> |
| Copy a file | gws drive copy <file-id> |
| Convert Office file | gws drive convert <file-id> |
| Export file | gws drive export --file-id <id> --mime-type application/pdf --output report.pdf |
| Update metadata | gws drive update --file-id <id> --name "New Name" |
| Empty trash | gws drive empty-trash |
| Drive info | gws drive about |
| Recent changes | gws drive changes |
Permissions
| Task | Command |
|---|
| List permissions | gws drive permissions --file-id <id> |
| Share with user | gws drive share --file-id <id> --type user --role writer --email user@example.com |
| Share with anyone | gws drive share --file-id <id> --type anyone --role reader |
| Get permission | gws drive permission --file-id <id> --permission-id <perm-id> |
| Update permission | gws drive update-permission --file-id <id> --permission-id <perm-id> --role reader |
| Remove permission | gws drive unshare --file-id <id> --permission-id <perm-id> |
Comments & Replies
| Task | Command |
|---|
| List comments | gws drive comments <file-id> |
| Get comment | gws drive comment --file-id <id> --comment-id <cid> |
| Add comment | gws drive add-comment --file-id <id> --content "Great work!" |
| Delete comment | gws drive delete-comment --file-id <id> --comment-id <cid> |
| Resolve comment | gws drive resolve-comment --file-id <id> --comment-id <cid> |
| Unresolve comment | gws drive unresolve-comment --file-id <id> --comment-id <cid> |
| List replies | gws drive replies --file-id <id> --comment-id <cid> |
| Reply to comment | gws drive reply --file-id <id> --comment-id <cid> --content "Thanks!" |
| Get reply | gws drive get-reply --file-id <id> --comment-id <cid> --reply-id <rid> |
| Delete reply | gws drive delete-reply --file-id <id> --comment-id <cid> --reply-id <rid> |
Approvals
| Task | Command |
|---|
| List approvals | gws drive approvals <file-id> |
| Get approval | gws drive approval <file-id> <approval-id> |
| Start approval | gws drive start-approval --file-id <id> --reviewers reviewer@example.com |
| Approve | gws drive approve --file-id <id> --approval-id <approval-id> |
| Decline | gws drive decline --file-id <id> --approval-id <approval-id> |
| Reassign reviewers | gws drive reassign-approval --file-id <id> --approval-id <approval-id> --add-reviewer reviewer@example.com |
| Cancel approval | gws drive cancel-approval --file-id <id> --approval-id <approval-id> |
| Comment on approval | gws drive comment-approval --file-id <id> --approval-id <approval-id> --message "Looks good" |
Revisions
| Task | Command |
|---|
| List revisions | gws drive revisions --file-id <id> |
| Get revision | gws drive revision --file-id <id> --revision-id <rid> |
| Delete revision | gws drive delete-revision --file-id <id> --revision-id <rid> |
Shared Drives
| Task | Command |
|---|
| List shared drives | gws drive shared-drives |
| Get shared drive | gws drive shared-drive --id <drive-id> |
| Create shared drive | gws drive create-drive --name "Engineering" |
| Update shared drive | gws drive update-drive --id <drive-id> --name "New Name" |
| Delete shared drive | gws drive delete-drive --id <drive-id> |
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)--raw — Treat query as raw V3 query syntax
Examples:
gws drive search "quarterly report"
gws drive search "budget 2024" --max 10
gws drive search "mimeType='application/pdf' and trashed=false" --raw
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)
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)
move — Move a file
gws drive move <file-id> --to <folder-id>
delete — Delete a file
gws drive delete <file-id> [flags]
By default, moves to trash. Use --permanent to permanently delete.
copy — Copy a file
gws drive copy <file-id> [flags]
Flags:
--name string — Name for the copy--folder string — Destination folder ID
convert — Convert Office file to Google format
gws drive convert <file-id> [flags]
Converts DOCX/XLSX/PPTX to native Google Docs/Sheets/Slides. Creates a new file (does not modify the original). Target format is auto-detected from source MIME type.
Flags:
--name string — Name for the converted file (default: original name)--folder string — Destination folder ID--to string — Target format: docs, sheets, slides (auto-detected if omitted)
export — Export a Google Workspace file
gws drive export --file-id <id> --mime-type <mime> --output <path>
Exports Docs, Sheets, Slides to formats like PDF, CSV, DOCX, etc.
Flags:
--file-id string — File ID (required)--mime-type string — Export MIME type (required, e.g. application/pdf, text/csv)--output string — Output file path (required)
update — Update file metadata
gws drive update --file-id <id> [flags]
Flags:
--file-id string — File ID (required)--name string — New file name--description string — New description--starred — Star or unstar the file--trashed — Trash or untrash the file
empty-trash — Empty trash
gws drive empty-trash
Permanently deletes all files in the trash. Cannot be undone.
about — Drive storage and user info
gws drive about
Returns user info and storage quota (limit, usage, usage in Drive, usage in trash).
changes — List recent file changes
gws drive changes [flags]
Polling pattern: the first call (without --page-token) fetches the current start token
and typically returns zero results. Save the returned new_start_page_token and pass it
in subsequent calls to detect new changes.
Flags:
--max int — Maximum number of changes (default 100)--page-token string — Page token from a previous call (auto-fetches start token if empty)
permissions — List permissions
gws drive permissions --file-id <id>
share — Share a file
gws drive share --file-id <id> --type <type> --role <role> [flags]
Flags:
--file-id string — File ID (required)--type string — Permission type: user, group, domain, anyone (required)--role string — Role: reader, commenter, writer, organizer, owner (required)--email string — Email address (for user/group type)--domain string — Domain (for domain type)--send-notification — Send notification email (default: true)
unshare — Remove a permission
gws drive unshare --file-id <id> --permission-id <perm-id>
permission — Get permission details
gws drive permission --file-id <id> --permission-id <perm-id>
update-permission — Update a permission
gws drive update-permission --file-id <id> --permission-id <perm-id> --role <role>
comments — List comments
gws drive comments <file-id> [flags]
Flags:
--max int — Maximum number of comments (default 100)--include-resolved — Include resolved comments--include-deleted — Include deleted comments
comment — Get a single comment
gws drive comment --file-id <id> --comment-id <cid>
add-comment — Add a comment
gws drive add-comment --file-id <id> --content "comment text"
gws drive add-comment --file-id <id> --content "Fix this" --quoted-text "the text to anchor to"
Flags:
--file-id string — File ID (required)--content string — Comment content (required)--quoted-text string — Anchor comment to this quoted text in the document
delete-comment — Delete a comment
gws drive delete-comment --file-id <id> --comment-id <cid>
resolve-comment — Resolve a comment
Posts a reply with action=resolve (the documented Drive API path for state
transitions). The original comment content is never modified. Pass an
optional --content to attach a closing note.
gws drive resolve-comment --file-id <id> --comment-id <cid>
gws drive resolve-comment --file-id <id> --comment-id <cid> --content "fixed in #1234"
unresolve-comment — Reopen a resolved comment
Posts a reply with action=reopen. The original comment content is never
modified. Pass an optional --content to attach a reopening note.
gws drive unresolve-comment --file-id <id> --comment-id <cid>
gws drive unresolve-comment --file-id <id> --comment-id <cid> --content "still broken on safari"
replies — List replies
gws drive replies --file-id <id> --comment-id <cid>
reply — Create a reply
gws drive reply --file-id <id> --comment-id <cid> --content "reply text"
get-reply — Get a reply
gws drive get-reply --file-id <id> --comment-id <cid> --reply-id <rid>
delete-reply — Delete a reply
gws drive delete-reply --file-id <id> --comment-id <cid> --reply-id <rid>
approvals — List file approvals
gws drive approvals <file-id> [flags]
Flags:
--max int — Maximum number of approvals (default 100)
approval — Get an approval
gws drive approval <file-id> <approval-id>
start-approval — Start an approval workflow
gws drive start-approval --file-id <id> --reviewers reviewer@example.com [flags]
Flags:
--file-id string — File ID (required)--reviewers string — Comma-separated reviewer email addresses (required)--due-time string — Approval due time (RFC3339)--message string — Message to send to reviewers--lock-file — Lock the file while approval is in progress
approve — Approve a file approval
gws drive approve --file-id <id> --approval-id <approval-id> [--message "Approved"]
decline — Decline a file approval
gws drive decline --file-id <id> --approval-id <approval-id> [--message "Needs changes"]
reassign-approval — Reassign approval reviewers
gws drive reassign-approval --file-id <id> --approval-id <approval-id> --add-reviewer new@example.com
gws drive reassign-approval --file-id <id> --approval-id <approval-id> --replace-reviewer old@example.com=new@example.com
Flags:
--add-reviewer string — Comma-separated reviewer emails to add--replace-reviewer string — Comma-separated replacements in old@example.com=new@example.com form--message string — Message to send to reviewers
cancel-approval — Cancel an approval
gws drive cancel-approval --file-id <id> --approval-id <approval-id> [--message "Cancelling"]
comment-approval — Comment on an approval
gws drive comment-approval --file-id <id> --approval-id <approval-id> --message "Please review"
revisions — List revisions
gws drive revisions --file-id <id>
revision — Get revision details
gws drive revision --file-id <id> --revision-id <rid>
delete-revision — Delete a revision
gws drive delete-revision --file-id <id> --revision-id <rid>
shared-drives — List shared drives
gws drive shared-drives [flags]
Flags:
--max int — Maximum number of drives (default 100)--query string — Search query
shared-drive — Get shared drive info
gws drive shared-drive --id <drive-id>
create-drive — Create a shared drive
gws drive create-drive --name "Drive Name"
update-drive — Update a shared drive
gws drive update-drive --id <drive-id> --name "New Name"
delete-drive — Delete a shared drive
gws drive delete-drive --id <drive-id>
Output Modes
gws drive list --format json
gws drive list --format yaml
gws drive list --format 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
- Use
gws drive about to check storage quota before large uploads
- Use
gws drive changes to monitor recent file activity
- For sharing, use
--type anyone --role reader for public access
- For Workspace file exports, common MIME types:
application/pdf, text/csv, application/vnd.openxmlformats-officedocument.wordprocessingml.document
