Google Drive Agent

The gdrive agent connects to Google Drive via API v3 using service account or OAuth credentials. It downloads and exports Google Docs, Sheets, and other files, lists folder contents, and uploads files to specified folders.

Unlike action-based agents, gdrive infers direction from the phase configuration: use sources to download/export, use target_entries to upload. There is no action field.

Sample Phase

- name: fetch-doc
  agent: gdrive
  sources:
      - name: requirements.md
        ref: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms"

Phase Configuration

Direction Inference

The gdrive agent has no action field. Direction is determined by which field you provide:

Field	Direction	Behavior
`sources`	Download/Export	Fetches files from Drive, writes to workspace
`target_entries`	Upload	Uploads workspace files to Drive

Phase YAML Fields

Field	Type	Required	Description
`name`	`string`	Yes	Unique phase name within the workflow
`type`	`string`	No	Defaults to `"standard"`
`agent`	`string`	Yes	Must be `"gdrive"`
`depends_on`	`string[]`	No	Upstream phases that must complete before this phase runs
`sources`	`SourceEntry[]`	Required unless `target_entries`	Files to download from Google Drive
`target_entries`	`TargetEntry[]`	Required unless `sources`	Files to upload to Google Drive

Source Entry Fields

Field	Type	Required	Description
`name`	`string`	Yes	Output filename (written to `.cliq/files/{phase}/{name}`)
`ref`	`string`	Yes	File ID for download, or `folder/{id}` for folder listing

Target Entry Fields

Field	Type	Required	Description
`name`	`string`	Yes	Identifier for the upload
`ref`	`string`	Yes	Folder ID to upload into
`file`	`string`	Yes	Local workspace file path to upload

Ref Formats

Pattern	Behavior
`1aBcDeFgHiJkLmNoPqRsT`	Download file by ID (auto-detects type for export)
`folder/3qRsTuVwXyZ`	List folder contents (source) or upload destination (target)

Google Docs are exported as plain text, Sheets as CSV, and other file types are downloaded as-is.

Settings

Google Drive credentials are configured under agents.gdrive in settings.json:

Key	Required	Default	Description
`agents.gdrive.credentials_file`	Yes	—	Path to service account JSON key file
`agents.gdrive.auth_mode`	No	`service_account`	Auth mode: `service_account` or `oauth`

Output

Handoff Structure

Source operations return file metadata; target operations return the uploaded file details.

Download sources

{
    "data": {
        "sources": {
            "spec": {
                "ref": "1aBcDeFgHiJkLmNoPqRsT",
                "file_id": "1aBcDeFgHiJkLmNoPqRsT",
                "title": "API Specification",
                "mime_type": "text/plain"
            },
            "data": {
                "ref": "2xYzAbCdEfGhIjKlMnOp",
                "file_id": "2xYzAbCdEfGhIjKlMnOp",
                "title": "Q4 Metrics",
                "mime_type": "text/csv"
            }
        },
        "targets": {}
    },
    "text": "## Google Drive Results\n\n✓ Fetched spec — API Specification (text/plain)\n✓ Fetched data — Q4 Metrics (text/csv)"
}

Folder listing

{
    "data": {
        "sources": {
            "assets": {
                "ref": "folder/3qRsTuVwXyZ",
                "file_id": "3qRsTuVwXyZ",
                "title": "Design Assets",
                "mime_type": "application/vnd.google-apps.folder"
            }
        },
        "targets": {}
    },
    "text": "## Google Drive Results\n\n✓ Listed assets — Design Assets (folder)"
}

Upload targets

{
    "data": {
        "sources": {},
        "targets": {
            "report": {
                "ref": "folder/3qRsTuVwXyZ",
                "file_id": "4nEwFiLeIdXyZ",
                "title": "report.md",
                "url": "https://drive.google.com/file/d/4nEwFiLeIdXyZ"
            }
        }
    },
    "text": "## Google Drive Results\n\n✓ Uploaded report → https://drive.google.com/file/d/4nEwFiLeIdXyZ"
}

Field Reference

Field	Location	Description
`ref`	`data.sources.`, `data.targets.`	Original ref from YAML (file ID or `folder/{id}`)
`file_id`	`data.sources.`, `data.targets.`	Google Drive file ID
`title`	`data.sources.`, `data.targets.`	File or folder name in Drive
`mime_type`	`data.sources.*`	MIME type of the exported/downloaded content
`url`	`data.targets.*`	Browsable Google Drive URL for the uploaded file

Files Written

Source operations write to .cliq/files/{phase}/{source.name}:

Google Docs — Exported as plain text
Google Sheets — Exported as CSV
Other files — Downloaded as-is (binary or text)
Folder listings — JSON array of { file_id, title, mime_type } entries

Downstream Access

Reference handoff data in downstream phases using template variables:

- name: analyze
  agent: cursor
  prompt: |
      Analyze the spreadsheet "$(handoff.fetch-data.sources.data.title)"
      and summarize the key findings.

Examples

Example: Export a Google Doc and implement from spec

Fetch a product spec from Google Docs and use it as input for implementation.

phases:
    - name: fetch-spec
      agent: gdrive
      sources:
          - name: spec
            ref: "1aBcDeFgHiJkLmNoPqRsT"

    - name: implement
      agent: cursor
      depends_on: [fetch-spec]
      prompt: |
          Implement the feature described in
          "$(handoff.fetch-spec.sources.spec.title)".

Example: Download a sheet and generate a report

Pull metrics from a Google Sheet and produce an analysis report.

phases:
    - name: fetch-metrics
      agent: gdrive
      sources:
          - name: metrics
            ref: "2xYzAbCdEfGhIjKlMnOp"

    - name: analyze
      agent: cursor
      depends_on: [fetch-metrics]
      prompt: |
          Analyze the CSV data from "$(handoff.fetch-metrics.sources.metrics.title)"
          and produce a summary report with key trends.

Example: List folder contents and process files

List a folder to discover available files, then selectively process them.

phases:
    - name: list-reports
      agent: gdrive
      sources:
          - name: listing
            ref: "folder/3qRsTuVwXyZ"

    - name: process
      agent: cursor
      depends_on: [list-reports]
      prompt: |
          Review the file listing from the
          "$(handoff.list-reports.sources.listing.title)" folder
          and identify which reports need updating.

Example: Upload a generated artifact

Generate a document and upload it to a shared Drive folder.

phases:
    - name: generate
      agent: cursor
      role: technical-writer
      prompt: |
          Generate a project status report and save it to status-report.md.

    - name: upload
      agent: gdrive
      depends_on: [generate]
      target_entries:
          - name: report
            ref: "folder/5AbCdEfGhIjK"
            file: status-report.md

Setup

Go to Google Cloud Console → Service Accounts
Create a service account (or use an existing one) and download the JSON key file
Enable the Google Drive API and Google Docs API for your project
Share target Drive folders and documents with the service account’s email address (found in the JSON key file as client_email)

cliq settings agents.gdrive.credentials_file "/path/to/service-account.json" --global
cliq doctor agent gdrive

For OAuth-based auth (user credentials instead of service account):

cliq settings agents.gdrive.auth_mode "oauth" --global
cliq settings agents.gdrive.credentials_file "/path/to/oauth-credentials.json" --global