> Note: `gdrive` is not currently published in the cmdhub registry. These docs are available by direct URL for development/reference use. # Google Drive CLI Files, folders, metadata, trash, and sharing permissions from the terminal. ## Install ```bash cmdhub get gdrive ``` ## Authentication OAuth2 ## Agent-Readable Catalog - Machine-readable command catalog: `/cli/gdrive/catalog.json` - Stable command anchors use the `cmd-...` IDs listed under each command. - Inspect this catalog before planning tool use for command paths, examples, flags, mutation markers, and dry-run support. ## Overview ```bash # Search for a file, inspect metadata, then list its sharing permissions gdrive file search --query "project notes" --limit 1 --jsonl \ | gdrive file get ``` ## CLI Overview Google Drive adapter CLI Work with Google Drive files, folders, and permissions. The intended workflow is: - list or search first - follow up with a short ref such as f1, d1, r1, or u1, or pipe jsonl into the next command - use resolve when you need to inspect what a short ref expands to Use --jsonl for self-pipe flows such as: gdrive file search --query status --jsonl | gdrive file get gdrive folder list --query eval --jsonl | gdrive file list ## Generated Coverage - Command groups: `13` - Total documented command nodes: `41` - Live examples: `4` - Lifecycle surfaces: `auth`, `doctor`, `capabilities`, `schema`, `resolve`, `version` - Machine-readable output: `--json`, `--jsonl` - Human views: `summary`, `full` ## Auth Contract - Auth mode: OAuth2 - Provider permission model: Google OAuth - Auth scopes: `openid`, `email`, `profile`, `https://www.googleapis.com/auth/drive` - Scope note: Used for Drive files, folders, metadata, trash, and permissions. - Standard commands: `auth login`, `auth logout`, `auth refresh`, `auth status`, `auth whoami` - `auth status --json` reports `tool`, `profile`, `provider`, `authenticated`, and `suggested_next_step`. - `auth whoami --json` is the stable way to answer identity questions. ## Agent Safety Notes - Discovery commands such as `list`, `search`, `get`, `resolve`, `schema`, `doctor`, `capabilities`, `status`, and `whoami` are the safest commands to run first. - Treat commands marked as mutating as state-changing local or provider operations. - Mutating command paths: `gdrive auth login`, `gdrive auth logout`, `gdrive auth refresh`, `gdrive file delete`, `gdrive file trash`, `gdrive file untrash`, `gdrive file update`, `gdrive file upload`, `gdrive folder create`, `gdrive login`, `gdrive logout`, `gdrive permission add`, `gdrive permission remove`, `gdrive profile create`, `gdrive profile delete`, `gdrive profile use` - No generated `--dry-run` flag was detected for this CLI. Use discovery commands before mutating commands. ## Global Flags - `--json` (bool): Emit JSON machine output - `--jsonl` (bool): Emit JSONL records for piping - `--output` (string): Compatibility output mode: json|jsonl. Prefer --json or --jsonl - `--view` (string): View mode: summary|full Default: `summary`. - `--profile` (string): Config/auth profile Default: `default`. - `--config` (string): Config path override - `--quiet` (bool): Suppress non-essential diagnostics - `--debug` (bool): Enable debug diagnostics - `--limit` (int): Maximum items to emit Default: `50`. - `--page-size` (int): Requested upstream page size Default: `50`. - `--cursor` (string): Continuation cursor - `--no-paginate` (bool): Fetch only one page - `--version` (bool): Print version information ## Command Reference ### `gdrive auth` - Anchor: `cmd-gdrive-auth` - Mutates state: `no` - Supports dry run: `no` Manage Google Drive authentication #### `gdrive auth login` - Anchor: `cmd-gdrive-auth-login` - Mutates state: `yes` - Supports dry run: `no` Authenticate with Google Drive Example: ```bash gdrive auth login gdrive auth login --help gdrive auth status ``` #### `gdrive auth logout` - Anchor: `cmd-gdrive-auth-logout` - Mutates state: `yes` - Supports dry run: `no` Remove stored credentials Example: ```bash gdrive auth login gdrive auth logout gdrive auth logout --help ``` #### `gdrive auth refresh` - Anchor: `cmd-gdrive-auth-refresh` - Mutates state: `yes` - Supports dry run: `no` Refresh stored token Example: ```bash gdrive auth refresh gdrive auth refresh --help ``` #### `gdrive auth status` - Anchor: `cmd-gdrive-auth-status` - Mutates state: `no` - Supports dry run: `no` Show auth status Example: ```bash gdrive auth status gdrive auth status --help ``` #### `gdrive auth whoami` - Anchor: `cmd-gdrive-auth-whoami` - Mutates state: `no` - Supports dry run: `no` Show current Drive identity Example: ```bash gdrive auth whoami gdrive auth whoami --help ``` ### `gdrive capabilities` - Anchor: `cmd-gdrive-capabilities` - Mutates state: `no` - Supports dry run: `no` Describe capabilities Example: ```bash gdrive capabilities --help ``` Flags: - `--section` (string): Limit output to scopes, schemas, or commands ### `gdrive config` - Anchor: `cmd-gdrive-config` - Mutates state: `no` - Supports dry run: `no` Inspect local configuration #### `gdrive config explain` - Anchor: `cmd-gdrive-config-explain` - Mutates state: `no` - Supports dry run: `no` Explain resolved configuration Example: ```bash gdrive config explain --help ``` ### `gdrive doctor` - Anchor: `cmd-gdrive-doctor` - Mutates state: `no` - Supports dry run: `no` Run gdrive diagnostics Example: ```bash gdrive doctor gdrive doctor --help gdrive doctor --json ``` ### `gdrive file` - Anchor: `cmd-gdrive-file` - Mutates state: `no` - Supports dry run: `no` Manage Drive files #### `gdrive file delete` - Anchor: `cmd-gdrive-file-delete` - Mutates state: `yes` - Supports dry run: `no` Permanently delete a file Example: ```bash gdrive file delete --all --yes f1 f2 gdrive file delete --help gdrive file delete f1 --yes ``` Flags: - `--all` (bool): Confirm batch permanent deletion - `--file` (string): File selector - `--yes` (bool): Confirm permanent deletion #### `gdrive file download` - Anchor: `cmd-gdrive-file-download` - Mutates state: `no` - Supports dry run: `no` Download file bytes Example: ```bash gdrive file download gdrive file download f1 --out ./notes.txt gdrive file search --query notes --jsonl | gdrive file download --out ./notes.txt ``` Flags: - `--file` (string): File selector - `--out` (string): Output path. Omit to print content. #### `gdrive file export` - Anchor: `cmd-gdrive-file-export` - Mutates state: `no` - Supports dry run: `no` Export a Google Docs file Example: ```bash gdrive file export gdrive file export f1 --mime-type application/pdf --out ./doc.pdf gdrive file export f1 --mime-type text/plain --out ./doc.txt ``` Flags: - `--file` (string): File selector - `--mime-type` (string): Export MIME type Default: `text/plain`. - `--out` (string): Output path. Omit to print content. #### `gdrive file get` - Anchor: `cmd-gdrive-file-get` - Mutates state: `no` - Supports dry run: `no` Get file metadata Example: ```bash gdrive file get gdrive file get f1 gdrive file get f1 f2 gdrive file search --query invoice --jsonl | gdrive file get ``` Flags: - `--file` (string): File selector #### `gdrive file list` - Anchor: `cmd-gdrive-file-list` - Mutates state: `no` - Supports dry run: `no` List files Example: ```bash gdrive file list gdrive file list --folder d1 gdrive file list --limit 10 gdrive file list --parent d1 --query notes gdrive folder list --jsonl | gdrive file list --limit 10 ``` Flags: - `--folder` (string): Folder selector - `--parent` (string): Alias for --folder - `--query` (string): Name/full-text query - `--trashed` (bool): Include trashed files #### `gdrive file search` - Anchor: `cmd-gdrive-file-search` - Mutates state: `no` - Supports dry run: `no` Search files by name or text Example: ```bash gdrive file search gdrive file search --folder d1 --query notes gdrive file search --parent d1 --query notes gdrive file search --query "quarterly plan" --limit 5 gdrive file search --query invoice gdrive file search --query project --limit 10 ``` Flags: - `--folder` (string): Folder selector - `--parent` (string): Alias for --folder - `--query` (string): Name/full-text query - `--trashed` (bool): Include trashed files #### `gdrive file trash` - Anchor: `cmd-gdrive-file-trash` - Mutates state: `yes` - Supports dry run: `no` Move a file to trash Example: ```bash gdrive file search --query old-notes --jsonl | gdrive file trash --all gdrive file trash --all f1 f2 gdrive file trash --help gdrive file trash f1 ``` Flags: - `--all` (bool): Confirm batch trash - `--file` (string): File selector #### `gdrive file untrash` - Anchor: `cmd-gdrive-file-untrash` - Mutates state: `yes` - Supports dry run: `no` Restore a file from trash Example: ```bash gdrive file search --query old-notes --trashed --jsonl | gdrive file untrash --all gdrive file untrash --all f1 f2 gdrive file untrash --help gdrive file untrash f1 ``` Flags: - `--all` (bool): Confirm batch untrash - `--file` (string): File selector #### `gdrive file update` - Anchor: `cmd-gdrive-file-update` - Mutates state: `yes` - Supports dry run: `no` Update file metadata or parents Example: ```bash gdrive file update --help gdrive file update f1 --add-parent d2 --remove-parent d1 gdrive file update f1 --description "Updated notes" gdrive file update f1 --name renamed.txt ``` Flags: - `--add-parent` (stringSlice): Folder selector to add as parent - `--description` (string): New description - `--file` (string): File selector - `--name` (string): New file name - `--remove-parent` (stringSlice): Folder selector to remove as parent - `--starred` (bool): Set starred #### `gdrive file upload` - Anchor: `cmd-gdrive-file-upload` - Mutates state: `yes` - Supports dry run: `no` Upload a local file Example: ```bash gdrive file upload --help gdrive file upload --path ./notes.txt --folder d1 --name notes.txt gdrive folder search --query "Project docs" --jsonl | gdrive file upload --path ./notes.txt ``` Flags: - `--description` (string): File description - `--folder` (string): Parent folder selector - `--mime-type` (string): Content MIME type - `--name` (string): Drive file name - `--path` (string): Local file path ### `gdrive folder` - Anchor: `cmd-gdrive-folder` - Mutates state: `no` - Supports dry run: `no` Manage Drive folders #### `gdrive folder create` - Anchor: `cmd-gdrive-folder-create` - Mutates state: `yes` - Supports dry run: `no` Create a folder Example: ```bash gdrive folder create --help gdrive folder create --name "Project docs" gdrive folder create --name Archive --parent d1 ``` Flags: - `--description` (string): Folder description - `--name` (string): Folder name - `--parent` (string): Parent folder selector #### `gdrive folder get` - Anchor: `cmd-gdrive-folder-get` - Mutates state: `no` - Supports dry run: `no` Get folder metadata Example: ```bash gdrive folder get gdrive folder get d1 gdrive folder get d1 d2 gdrive folder list --jsonl | gdrive folder get ``` #### `gdrive folder list` - Anchor: `cmd-gdrive-folder-list` - Mutates state: `no` - Supports dry run: `no` List folders Example: ```bash gdrive folder list gdrive folder list --limit 10 gdrive folder list --query Project ``` Flags: - `--query` (string): Folder name query - `--trashed` (bool): Include trashed folders #### `gdrive folder search` - Anchor: `cmd-gdrive-folder-search` - Mutates state: `no` - Supports dry run: `no` Search folders by name Example: ```bash gdrive folder search gdrive folder search --query "Project docs" gdrive folder search --query archive --trashed gdrive folder search --query project --limit 10 ``` Flags: - `--query` (string): Folder name query - `--trashed` (bool): Include trashed folders ### `gdrive login` - Anchor: `cmd-gdrive-login` - Mutates state: `yes` - Supports dry run: `no` Authenticate with Google Drive Example: ```bash gdrive auth status gdrive login ``` ### `gdrive logout` - Anchor: `cmd-gdrive-logout` - Mutates state: `yes` - Supports dry run: `no` Remove stored credentials Example: ```bash gdrive auth login gdrive logout ``` ### `gdrive permission` - Anchor: `cmd-gdrive-permission` - Mutates state: `no` - Supports dry run: `no` Manage Drive permissions #### `gdrive permission add` - Anchor: `cmd-gdrive-permission-add` - Mutates state: `yes` - Supports dry run: `no` Add a permission Example: ```bash gdrive permission add --file f1 --type anyone --role reader --yes gdrive permission add --file f1 --type user --email user@example.com gdrive permission add --help ``` Flags: - `--allow-discovery` (bool): Allow public/domain discovery - `--domain` (string): Domain for domain permission - `--email` (string): Email address for user/group permission - `--file` (string): File selector - `--role` (string): Permission role: reader|commenter|writer Default: `reader`. - `--type` (string): Permission type: user|group|domain|anyone (required) - `--yes` (bool): Confirm creation of a public anyone permission #### `gdrive permission list` - Anchor: `cmd-gdrive-permission-list` - Mutates state: `no` - Supports dry run: `no` List file permissions Example: ```bash gdrive file search --query notes --jsonl | gdrive permission list gdrive permission list gdrive permission list --file f1 ``` Flags: - `--file` (string): File selector #### `gdrive permission remove` - Anchor: `cmd-gdrive-permission-remove` - Mutates state: `yes` - Supports dry run: `no` Remove a permission Example: ```bash gdrive permission remove --file f1 --permission r1 --yes gdrive permission remove --file f1 r1 --yes gdrive permission remove --help ``` Flags: - `--all` (bool): Confirm batch permission removal - `--file` (string): File selector - `--permission` (string): Permission selector - `--yes` (bool): Confirm permission removal ### `gdrive profile` - Anchor: `cmd-gdrive-profile` - Mutates state: `no` - Supports dry run: `no` Manage provider profiles #### `gdrive profile create` - Anchor: `cmd-gdrive-profile-create` - Mutates state: `yes` - Supports dry run: `no` Create an unauthenticated provider profile Example: ```bash gdrive profile create --help ``` #### `gdrive profile delete` - Anchor: `cmd-gdrive-profile-delete` - Mutates state: `yes` - Supports dry run: `no` Delete a local provider profile Example: ```bash gdrive profile delete --help ``` #### `gdrive profile list` - Anchor: `cmd-gdrive-profile-list` - Mutates state: `no` - Supports dry run: `no` List provider profiles Example: ```bash gdrive profile list --help ``` #### `gdrive profile rename` - Anchor: `cmd-gdrive-profile-rename` - Mutates state: `no` - Supports dry run: `no` Rename a local provider profile Example: ```bash gdrive profile rename --help ``` #### `gdrive profile use` - Anchor: `cmd-gdrive-profile-use` - Mutates state: `yes` - Supports dry run: `no` Set the default provider profile Example: ```bash gdrive profile use --help ``` ### `gdrive resolve` - Anchor: `cmd-gdrive-resolve` - Mutates state: `no` - Supports dry run: `no` Resolve a local ref, short id, or URL alias Example: ```bash gdrive resolve --help gdrive resolve ``` ### `gdrive schema` - Anchor: `cmd-gdrive-schema` - Mutates state: `no` - Supports dry run: `no` Emit gdrive schema hints Example: ```bash gdrive schema gdrive schema --help gdrive schema file.get --out --json gdrive schema file.upload --input ``` Flags: - `--in` (bool): Show input schema - `--input` (bool): Show input schema - `--out` (bool): Show output schema ### `gdrive version` - Anchor: `cmd-gdrive-version` - Mutates state: `no` - Supports dry run: `no` Show gdrive version information Example: ```bash gdrive version --help ``` ## Live Examples ### Auth #### Check current Drive identity Returns the active Google Drive account. _Example metadata: requires auth; provider state: live._ ```bash gdrive auth whoami ``` ```text Authenticated as kestrelphilip@gmail.com Profile: kestrelphilip@gmail.com Next steps: - Files: gdrive file list --limit 10 - Folders: gdrive folder list --limit 10 - Capabilities: gdrive capabilities ``` ### Files #### List recent files Lists recent non-trashed files. _Example metadata: requires auth; provider state: live._ ```bash gdrive file list --limit 5 ``` ```text REF NAME STATE UPDATED f1 Google Cloud Free Trial Email.txt active Mon 27 Apr 17:54 f2 test active Fri 24 Apr 19:16 Next steps: - Open: gdrive file get f1 - Search: gdrive file search --query project --limit 10 - Files: gdrive file list --limit 10 - Folders: gdrive folder list --limit 10 ``` #### Search files Searches Drive files by text. _Example metadata: requires auth; provider state: live._ ```bash gdrive file search --query eval --limit 5 ``` ```text No file found. Next steps: - List: gdrive file list --limit 10 - Status: gdrive auth status - Folders: gdrive folder list --limit 10 - Capabilities: gdrive capabilities ``` ### Folders #### List folders Lists visible folders. _Example metadata: requires auth; provider state: live._ ```bash gdrive folder list --limit 5 ``` ```text REF NAME STATE UPDATED d1 test active Fri 24 Apr 19:16 Next steps: - Open: gdrive folder get d1 - Search: gdrive folder search --query project --limit 10 - Files: gdrive file list --limit 10 - Folders: gdrive folder list --limit 10 ```