Skill: ghchinoy/google-drive-cli (version 0.1.4)

--- name: google-drive-cli description: Interact with Google Drive, Docs, and Sheets using the drivectl CLI. Use this skill when asked to list Drive files, download files, read/update Sheets, or create/export Google Docs. metadata: discovery_doc_drive_v3: "https://www.googleapis.com/discovery/v1/apis/drive/v3/rest" --- # google-drive-cli This skill provides guidance on using the `drivectl` command-line tool to interact with Google Workspace (Drive, Docs, Sheets). ## Prerequisites & Authentication - Ensure `drivectl` is available in your PATH or in the current working directory (e.g., `./drivectl`). *If it is not installed, you can quickly download the latest prebuilt binary by running the bundled script: `scripts/install.sh`.* - **Crucial Rule:** Always append `-O json` to `drivectl` commands when you need to parse the output programmatically or return structured information. ### First-time Authentication The user must authenticate before using `drivectl`. It securely caches tokens locally so this only needs to happen once. If the user hasn't authenticated, guide them to do so: ```bash drivectl auth login --secret-file /path/to/your/client_secret.json ``` *(If operating on a headless system or inside an agent environment without a browser, append the `--no-browser-auth` flag to print a manual authorization URL that the user can click).* ## Available Modules The `drivectl` tool provides several subcommands organized by Workspace service. Pick the correct reference depending on the user's request. - **Google Drive (Files/Folders)**: See [references/drive.md](references/drive.md) for listing, querying, searching, and downloading files. - **Google Docs**: See [references/docs.md](references/docs.md) for creating docs from Markdown, reading docs, converting to Markdown, and exploring tab structures. - **Google Sheets**: See [references/sheets.md](references/sheets.md) for reading ranges, updating cells, and exporting sheets to CSV. ## Dynamic Discovery (Fallback) If the built-in commands (`list`, `docs`, `sheets`) do not cover the requirement, you can use the `call` subcommand to dynamically invoke *any* Google Workspace API endpoint using Google Discovery. See [references/discovery.md](references/discovery.md) for detailed instructions on how to formulate and execute these dynamic API calls.

path: references/discovery.md
content: # Dynamic API Discovery

If the standard subcommands do not cover the user's request (e.g., updating file permissions, managing comments directly, interacting with a completely different Google API like Calendar or Gmail), you can use the `drivectl call` subcommand.

This subcommand uses Google's API Discovery service to dynamically build and execute HTTP requests against almost any Google Workspace API endpoint.

## Syntax

```bash
drivectl call <api>.<version>.<resource>.<method> --payload '<json-string>' -O json
```

### Components

1.  **Method Signature:** The command takes a dot-separated string representing the API, version, resource(s), and method.
    *   Examples:
        *   `drive.v3.files.get`
        *   `docs.v1.documents.create`
        *   `drive.v3.permissions.create`
2.  **`--payload`**: This flag accepts a JSON string. This JSON object serves a dual purpose:
    *   It populates **URL path parameters** (e.g., `fileId`, `documentId`).
    *   It populates **URL query parameters** (e.g., `fields`, `pageSize`).
    *   It populates the **Request Body** for methods like `POST`, `PUT`, or `PATCH`.
    *   *Note: `drivectl` automatically maps the keys in your JSON payload to the correct locations (path, query, or body) based on the Discovery schema.*
3.  **`-O json`**: As always, append this to ensure the output is structured JSON.

## Examples

**Example 1: Fetching specific fields for a known file (Drive)**
```bash
drivectl call drive.v3.files.get --payload '{"fileId": "YOUR_FILE_ID", "fields": "name,mimeType,owners"}' -O json
```
*Here, `fileId` is mapped to the URL path, and `fields` is mapped to the query string.*

**Example 2: Creating a new Google Doc (Docs)**
```bash
drivectl call docs.v1.documents.create --payload '{"title": "My New Document"}' -O json
```
*Here, the JSON is mapped to the request body as the document representation.*

**Example 3: Adding a reader permission to a file (Drive)**
```bash
drivectl call drive.v3.permissions.create --payload '{"fileId": "YOUR_FILE_ID", "role": "reader", "type": "user", "emailAddress": "[REDACTED_SECRET]"}' -O json
```
*Here, `fileId` goes to the URL path, and `role`, `type`, and `emailAddress` go into the request body.*

## Finding the Right Method and Parameters

If you do not know the exact method signature or required parameters, you can:
1. Search the web or refer to standard Google API REST documentation (e.g., "Google Drive API REST reference"). The method signature maps directly to the REST resource structure (e.g., `drive.v3.files.update`).
2. Make an educated guess using the pattern: `<api>.<version>.<resource>.<action>`.
3. Consult the raw API Discovery documents. For example, the Drive v3 discovery document is located at: `https://www.googleapis.com/discovery/v1/apis/drive/v3/rest`

path: references/docs.md
content: # Google Docs Operations

Use `drivectl` to create, read, and manage Google Docs.

## Exporting Google Docs to Markdown

To extract the content of a Google Doc as Markdown (which accurately parses the document AST):
```bash
drivectl get <google-doc-id> --format md
```

To save the exported Markdown directly to a file:
```bash
drivectl get <google-doc-id> --format md -o output.md
```

## Creating Google Docs from Markdown

To convert a local Markdown file into a richly formatted Google Doc:
```bash
drivectl docs create "Document Title" path/to/document.md -O json
```
This will output JSON containing the new Document ID and a link to the created document.

## Exploring Document Structure

To view the structural hierarchy of tabs within a Google Doc:
```bash
drivectl docs tabs <document-id> -O json
```


path: references/drive.md
content: # Google Drive Operations

Use `drivectl` to interact with files in Google Drive. Always use `-O json` for programmatic parsing.

## Listing Files

To list files, use `drivectl list`. It supports querying with Google Drive search syntax.

**Basic list (default 100 items):**
```bash
drivectl list -O json
```

**List with limit:**
```bash
drivectl list --limit 5 -O json
```

**Search by name:**
```bash
drivectl list -q "name contains 'Project'" -O json
```

**Search for Google Docs specifically:**
```bash
drivectl list -q "mimeType='application/vnd.google-apps.document'" -O json
```

## Downloading / Getting File Content

To download a file or its raw content to stdout:
```bash
drivectl get <file-id>
```

*(Note: For Google Workspace documents, you often want to convert them during export. For example, to convert Google Docs to Markdown, see docs.md).*

## Revisions and Comments

**View the revision history:**
```bash
drivectl revisions <file-id> -O json
```

**View threaded comments:**
```bash
drivectl comments <file-id> -O json
```


path: references/sheets.md
content: # Google Sheets Operations

Use `drivectl` to read and update data in Google Sheets. Always use `-O json` for programmatic parsing where applicable.

## Reading Data

**Export a full sheet as CSV:**
```bash
drivectl sheets get <spreadsheet-id> --sheet "Sheet1"
```
*(This outputs raw CSV data to stdout. Do not use `-O json` here if you just want the CSV).*

**Read a specific cell range (A1 notation):**
```bash
drivectl sheets get-range <spreadsheet-id> --sheet "Sheet1" --range "A1:C5" -O json
```
*(Outputs a JSON array of arrays containing the cell values).*

## Updating Data

**Update a specific cell or range:**
```bash
drivectl sheets update-range <spreadsheet-id> "New Value" --sheet "Sheet1" --range "B2" -O json
```

If you are updating a range, the "New Value" is typically applied starting at the top-left of the range.


path: scripts/install.sh
content: #!/usr/bin/env bash
set -euo pipefail

# This script downloads the latest release of drivectl from GitHub,
# verifies its checksum, and extracts it to the current directory.

# Detect OS
OS_UNAME="$(uname -s)"
case "$OS_UNAME" in
  Linux) OS="Linux" ;;
  Darwin) OS="Darwin" ;;
  *) echo "Unsupported OS: $OS_UNAME"; exit 1 ;;
esac

# Detect Architecture
ARCH_UNAME="$(uname -m)"
case "$ARCH_UNAME" in
  x86_64|amd64) ARCH="x86_64" ;;
  aarch64|arm64) ARCH="arm64" ;;
  *) echo "Unsupported Architecture: $ARCH_UNAME"; exit 1 ;;
esac

REPO="ghchinoy/drivectl"

# Resolve latest release version tag
LATEST_URL=$(curl -sLI -o /dev/null -w '%{url_effective}' "https://github.com/${REPO}/releases/latest")
TAG="${LATEST_URL##*/}"
VERSION="${TAG#v}"

FILENAME="drivectl_${OS}_${ARCH}.tar.gz"
URL="https://github.com/${REPO}/releases/download/${TAG}/${FILENAME}"
CHECKSUMS_FILENAME="drivectl_${VERSION}_checksums.txt"
CHECKSUMS_URL="https://github.com/${REPO}/releases/download/${TAG}/${CHECKSUMS_FILENAME}"

TMP_DIR=$(mktemp -d)
trap 'rm -rf "$TMP_DIR"' EXIT

echo "Downloading drivectl from: ${URL}"
curl -sL "$URL" -o "${TMP_DIR}/${FILENAME}"

echo "Downloading checksums..."
curl -sL "$CHECKSUMS_URL" -o "${TMP_DIR}/checksums.txt"

echo "Verifying checksum..."
cd "$TMP_DIR"
# Find the line corresponding to our filename
if ! grep "${FILENAME}" checksums.txt > expected_checksum.txt; then
  echo "Error: Could not find checksum for ${FILENAME} in checksums.txt"
  exit 1
fi

if command -v sha256sum >/dev/null 2>&1; then
  sha256sum -c expected_checksum.txt
elif command -v shasum >/dev/null 2>&1; then
  shasum -a 256 -c expected_checksum.txt
else
  echo "Warning: No sha256sum or shasum command found. Skipping checksum validation."
fi
cd - > /dev/null

echo "Extracting..."
tar -xzf "${TMP_DIR}/${FILENAME}" drivectl

chmod +x drivectl
echo "Success! drivectl is now installed in the current directory."


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)