# Google Drive on boxd

> Google Drive is a cloud storage solution for uploading, sharing, and collaborating on files across devices, with robust search and offline access.

- Page: https://boxd.sh/integrations/googledrive/
- CLI: `run googledrive` (90 commands, 62 marked common)
- SDK: `import { googledrive } from "@boxd/run"`; every parameter and response type is at `@boxd/run/googledrive`
- Triggers: 7
- Connect: `run auth googledrive` (Sign in with Google Drive), or https://app.boxd.sh/integrations/detail/googledrive
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth googledrive      # once: prints a link to connect your account
run googledrive           # list its commands
run googledrive find-file
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { googledrive } from "@boxd/run";

const result = await googledrive.findFile({});
console.log(result);

googledrive.on("file-created", async (event) => {
  // File Created: runs on this machine, once per event
  console.log(event);
});
```

Run it with `run googledrive.run.ts`. A script that calls `.on()` keeps running as a job and handles each event.

## Commands

Required flags are listed; `run googledrive <command> --help` lists the optional ones. "common" marks what `run googledrive` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `add-file-sharing-preference` ·common ·deprecated | `googledrive.addFileSharingPreference()` | `--file-id` `--role` `--type` | 3 | Use create-permission instead; use update-permission to modify existing permissions (avoids duplicate entries) |
| `add-parent` | `googledrive.addParent()` | `--fileId` `--id` | 3 | Add a parent folder for a file using Google Drive API v2 |
| `add-property` | `googledrive.addProperty()` | `--fileId` `--property-key` `--property-value` | 12 | Add a property to a file, or update it if it already exists (v2 API) |
| `copy-file` ·deprecated | `googledrive.copyFile()` | `--file-id` | 1 | Use copy-file-advanced instead |
| `copy-file-advanced` | `googledrive.copyFileAdvanced()` | `--fileId` | 32 | Creates a copy of a file and applies any requested updates with patch semantics |
| `create-comment` ·common | `googledrive.createComment()` | `--content` `--file-id` | 3 | Create a comment on a file in Google Drive |
| `create-drive` ·common | `googledrive.createDrive()` | `--name` | 5 | Create a new shared drive |
| `create-file` ·common | `googledrive.createFile()` | — | 7 | Creates a new file or folder in Google Drive |
| `create-file-from-text` | `googledrive.createFileFromText()` | `--file-name` `--text-content` | 2 | Creates a new file in Google Drive from provided text content (up to 10MB), supporting various formats including automatic conversion to Google Workspace types |
| `create-folder` ·common | `googledrive.createFolder()` | `--name` | 1 | Creates a new folder in Google Drive, optionally within an EXISTING parent folder specified by its ID or name |
| `create-permission` ·common | `googledrive.createPermission()` | `--file-id` `--role` `--type` | 10 | Create a permission for a file or shared drive |
| `create-permissions-batch` ·common | `googledrive.createPermissionsBatch()` | `--permissions` | 0 | Creates multiple permissions for files or shared drives in a single batch request |
| `create-reply` ·common | `googledrive.createReply()` | `--comment-id` `--content` `--file-id` | 2 | Create a reply to a comment in Google Drive |
| `create-shortcut-to-file` ·common | `googledrive.createShortcutToFile()` | `--name` `--target-id` | 5 | Create a shortcut to a file or folder in Google Drive |
| `create-team-drive` | `googledrive.createTeamDrive()` | `--name` | 4 | Create a Team Drive |
| `delete-child` | `googledrive.deleteChild()` | `--childId` `--folderId` | 12 | Remove a child from a folder using Google Drive API v2 |
| `delete-comment` ·common | `googledrive.deleteComment()` | `--comment-id` `--file-id` | 0 | Permanently deletes a comment thread (and all its replies) from a Google Drive file, this action is irreversible |
| `delete-drive` ·common | `googledrive.deleteDrive()` | `--driveId` | 2 | Permanently delete a shared drive |
| `delete-file` ·common ·deprecated | `googledrive.deleteFile()` | `--fileId` | 2 | Use google-drive-delete-folder-or-file-action instead |
| `delete-parent` | `googledrive.deleteParent()` | `--fileId` `--parentId` | 12 | Remove a parent from a file using Google Drive API v2 |
| `delete-permission` ·common | `googledrive.deletePermission()` | `--file-id` `--permission-id` | 2 | Deletes a permission from a file by permission ID |
| `delete-property` | `googledrive.deleteProperty()` | `--fileId` `--propertyKey` | 12 | Delete a property from a file using Google Drive API v2 |
| `delete-reply` ·common | `googledrive.deleteReply()` | `--comment-id` `--file-id` `--reply-id` | 0 | Delete a specific reply by reply ID |
| `delete-revision` | `googledrive.deleteRevision()` | `--file-id` `--revision-id` | 0 | Permanently delete a file revision |
| `delete-team-drive` | `googledrive.deleteTeamDrive()` | `--teamDriveId` | 0 | Permanently delete a Team Drive |
| `download-file` ·common | `googledrive.downloadFile()` | `--fileId` | 1 | Downloads a file from Google Drive by its ID |
| `download-file-operation` ·common | `googledrive.downloadFileOperation()` | `--file-id` | 2 | Download file content using long-running operations |
| `download-file2` ·common ·deprecated | `googledrive.downloadFile2()` | `--file-id` | 0 | Use download-file-operation instead |
| `edit-file` | `googledrive.editFile()` | `--content` `--file-id` | 1 | Updates an existing Google Drive file with binary content by overwriting its entire content with new text (max 10MB) |
| `empty-trash` ·common | `googledrive.emptyTrash()` | — | 2 | Permanently and irreversibly delete ALL trashed files in the user's Google Drive or a specified shared drive |
| `export-google-workspace-file` ·common | `googledrive.exportGoogleWorkspaceFile()` | `--fileId` `--mimeType` | 0 | Exports a Google Workspace document to the requested MIME type and returns exported file content |
| `find-file` ·common | `googledrive.findFile()` | — | 22 | The comprehensive Google Drive search tool that handles all file and folder discovery needs |
| `find-folder` | `googledrive.findFolder()` | — | 10 | Finds one page of Google Drive folders by name and optional parent |
| `generate-ids` ·common | `googledrive.generateIds()` | — | 3 | Generates a set of file IDs which can be provided in create or copy requests |
| `get-about` ·common | `googledrive.getAbout()` | — | 1 | Retrieve information about the user, the user's Drive, and system capabilities |
| `get-app` | `googledrive.getApp()` | `--appId` | 0 | Get information about a specific Drive app by ID |
| `get-change` | `googledrive.getChange()` | `--changeId` | 15 | Get a specific change by ID from Google Drive v2 API |
| `get-changes-start-page-token` ·common | `googledrive.getChangesStartPageToken()` | — | 4 | Get the starting pageToken for listing future changes in Google Drive |
| `get-child` | `googledrive.getChild()` | `--childId` `--folderId` | 11 | Get a specific child reference for a folder using Drive API v2 |
| `get-comment` ·common | `googledrive.getComment()` | `--commentId` `--fileId` | 1 | Get a comment by ID |
| `get-drive` ·common | `googledrive.getDrive()` | `--drive-id` | 1 | Get a shared drive by ID |
| `get-file-metadata` ·common | `googledrive.getFileMetadata()` | `--fileId` | 4 | Get a file's metadata by ID |
| `get-file-property` ·common | `googledrive.getFileProperty()` | `--fileId` `--propertyKey` | 1 | Get a property by its key using Google Drive API v2 |
| `get-file-v2` ·deprecated | `googledrive.getFileV2()` | `--fileId` | 19 | Use GetFileMetadata instead |
| `get-parent` | `googledrive.getParent()` | `--fileId` `--parentId` | 11 | Get a specific parent reference for a file using Drive API v2 |
| `get-permission` ·common | `googledrive.getPermission()` | `--file-id` `--permission-id` | 3 | Gets a permission by ID |
| `get-permission-id-for-email` | `googledrive.getPermissionIdForEmail()` | `--email` | 11 | Get the permission ID for an email address using the Drive API v2 |
| `get-reply` ·common | `googledrive.getReply()` | `--commentId` `--fileId` `--replyId` | 1 | Get a specific reply to a comment on a file |
| `get-revision` ·common | `googledrive.getRevision()` | `--file-id` `--revision-id` | 1 | Get a specific revision's metadata (name, modifiedTime, keepForever, etc.) by revision ID |
| `get-team-drive` | `googledrive.getTeamDrive()` | `--teamDriveId` | 1 | Get metadata about a Team Drive by ID |
| `google-drive-delete-folder-or-file-action` | `googledrive.googleDriveDeleteFolderOrFileAction()` | `--fileId` | 1 | Delete a file or folder in Google Drive |
| `hide-drive` ·common | `googledrive.hideDrive()` | `--drive-id` | 0 | Hide a shared drive from the default view |
| `insert-child` | `googledrive.insertChild()` | `--folderId` `--id` | 14 | Insert a file into a folder using Drive API v2 |
| `list-access-proposals` ·common | `googledrive.listAccessProposals()` | `--fileId` | 2 | List pending access proposals on a file |
| `list-approvals` ·common | `googledrive.listApprovals()` | `--fileId` | 2 | List approvals on a file for workflow-based access control |
| `list-changes` ·common | `googledrive.listChanges()` | — | 11 | List the changes for a user or shared drive |
| `list-children-v2` | `googledrive.listChildrenV2()` | `--folderId` | 15 | List a folder's children using Google Drive API v2 |
| `list-comments` ·common | `googledrive.listComments()` | `--fileId` | 5 | List all comments for a file in Google Drive |
| `list-file-labels` ·common | `googledrive.listFileLabels()` | `--file-id` | 2 | List the labels already applied to a file in Google Drive |
| `list-file-properties` | `googledrive.listFileProperties()` | `--fileId` | 11 | List a file's properties in Google Drive API v2 |
| `list-files` ·common ·deprecated | `googledrive.listFiles()` | — | 13 | Use find-file instead |
| `list-permissions` ·common | `googledrive.listPermissions()` | `--fileId` | 5 | List a file's permissions |
| `list-replies` ·common | `googledrive.listReplies()` | `--comment-id` `--file-id` | 4 | List replies to a comment in Google Drive |
| `list-revisions` ·common | `googledrive.listRevisions()` | `--fileId` | 3 | List a file's revision metadata (not content) in Google Drive |
| `list-shared-drives` ·common | `googledrive.listSharedDrives()` | — | 4 | List the user's shared drives |
| `list-team-drives` | `googledrive.listTeamDrives()` | — | 15 | List Team Drives (deprecated, use List Shared Drives instead) |
| `modify-file-labels` ·common | `googledrive.modifyFileLabels()` | `--file-id` `--label-modifications` | 1 | Modifies the set of labels applied to a file |
| `move-file` ·common | `googledrive.moveFile()` | `--file-id` | 8 | Move a file from one folder to another in Google Drive |
| `parse-file` ·common ·deprecated | `googledrive.parseFile()` | `--file-id` | 1 | Exports Google Workspace files (max 10MB) to a specified format using `mime_type`, or downloads other file types; use `download-file` instead |
| `patch-permission` ·common | `googledrive.patchPermission()` | `--file-id` `--permission-id` | 8 | Update a permission using patch semantics |
| `patch-property` | `googledrive.patchProperty()` | `--fileId` `--propertyKey` | 13 | Update a property on a file using PATCH semantics (v2 API) |
| `resumable-upload` ·common | `googledrive.resumableUpload()` | `--file-to-upload` | 5 | Start and complete a Google Drive resumable upload session |
| `stop-watch-channel` ·common | `googledrive.stopWatchChannel()` | `--id` `--resourceId` | 8 | Stop watching resources through a specified channel |
| `trash-file` ·common | `googledrive.trashFile()` | `--file-id` | 2 | Move a file or folder to trash (soft delete) |
| `unhide-drive` ·common | `googledrive.unhideDrive()` | `--driveId` | 0 | Unhide a shared drive |
| `untrash-file` ·common | `googledrive.untrashFile()` | `--file-id` | 1 | Restore a file from the trash |
| `update-comment` ·common | `googledrive.updateComment()` | `--comment-id` `--file-id` | 3 | Update an existing comment on a Google Drive file |
| `update-drive` ·common | `googledrive.updateDrive()` | `--driveId` | 7 | Update the metadata for a shared drive |
| `update-file-metadata-patch` ·common | `googledrive.updateFileMetadataPatch()` | `--fileId` | 22 | Update file metadata using the Drive API v2 PATCH method |
| `update-file-property` | `googledrive.updateFileProperty()` | `--fileId` `--propertyKey` | 14 | Update a property on a file using Google Drive API v2 |
| `update-file-put` ·common | `googledrive.updateFilePut()` | `--fileId` | 12 | Updates file metadata |
| `update-file-revision-metadata` ·common | `googledrive.updateFileRevisionMetadata()` | `--file-id` `--revision-id` | 4 | Updates ONLY the metadata properties of a specific file revision (keepForever, published, publishAuto, publishedOutsideDomain) |
| `update-permission` ·common | `googledrive.updatePermission()` | `--fileId` `--permission` `--permissionId` | 5 | Update a permission with patch semantics |
| `update-reply` ·common | `googledrive.updateReply()` | `--comment-id` `--content` `--file-id` `--reply-id` | 1 | Update a reply to a comment on a Google Drive file |
| `update-team-drive` | `googledrive.updateTeamDrive()` | `--teamDriveId` | 6 | Update a Team Drive's metadata |
| `upload-file` ·common | `googledrive.uploadFile()` | `--file-to-upload` | 1 | Uploads a file (max 5MB) to Google Drive, placing it in the specified folder or root if no valid folder ID is provided |
| `upload-from-url` ·common | `googledrive.uploadFromUrl()` | `--name` `--source-url` | 5 | Fetch a file from a provided URL server-side and upload it into Google Drive |
| `upload-update-file` ·common | `googledrive.uploadUpdateFile()` | `--fileId` `--file-to-upload` | 7 | Update file content in Google Drive by uploading new binary content |
| `watch-changes` ·common | `googledrive.watchChanges()` | `--address` `--id` `--type` | 14 | Subscribe to changes for a user or shared drive in Google Drive |
| `watch-file` ·common | `googledrive.watchFile()` | `--address` `--fileId` `--id` `--type` | 9 | Subscribe to push notifications for changes to a specific file |

## Triggers

`googledrive.on("<event>", handler)` in a script; required config goes before the handler as an object.

| Event | Name | Required config | Description |
|---|---|---|---|
| `"comment-added"` | Comment Added (Docs/Sheets/Slides) | — | Triggers when a new comment is added to Google Docs, Sheets, or Slides |
| `"file-created"` | File Created | — | Triggers when a new file is created in Google Drive |
| `"file-deleted-or-trashed"` | File Deleted or Trashed | — | Triggers when a file is moved to trash or permanently deleted in Drive |
| `"file-shared-permissions-added"` | File Shared (Permissions Added) | — | Triggers when new sharing permissions are granted to a file or folder |
| `"file-updated"` | File Updated | — | Triggers when a file's metadata or content changes in Google Drive |
| `"google-drive-changes"` | Google Drive Changes | — | Triggers when changes are detected in a Google Drive |
| `"new-file-matching-query"` | New File Matching Query | — | Triggers when a new Google Drive file matches a provided query |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.