playbooks

home / skills / chachamaru127 / claude-code-harness / gogcli-ops

gogcli-ops skill

/skills/gogcli-ops

This skill helps you securely verify gogcli authentication, resolve Google file IDs from URLs, and perform safe read-only checks before any write actions.

npx playbooks add skill chachamaru127/claude-code-harness --skill gogcli-ops

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
3.9 KB
---
name: gogcli-ops
description: "gogcli でGoogle Workspace操作（Drive/Sheets/Docs/Slides）。ユーザーがGoogleファイルの確認・検索・エクスポート・読み取り・更新をgogcliで依頼する時に使用。Trigger when a user asks to check, list, search, export, read, or update Google files via gogcli; when a Google URL/ID needs parsing; when auth/account selection or safe read-only workflows are needed; or when troubleshooting gogcli access/errors."
description-en: Use gogcli for Google Workspace CLI operations (Drive/Sheets/Docs/Slides). Trigger when a user asks to check, list, search, export, read, or update Google files via gogcli; when a Google URL/ID needs parsing; when auth/account selection or safe read-only workflows are needed; or when troubleshooting gogcli access/errors.
description-ja: "gogcli でGoogle Workspace操作（Drive/Sheets/Docs/Slides）。ユーザーがGoogleファイルの確認・検索・エクスポート・読み取り・更新をgogcliで依頼する時に使用。Trigger when a user asks to check, list, search, export, read, or update Google files via gogcli; when a Google URL/ID needs parsing; when auth/account selection or safe read-only workflows are needed; or when troubleshooting gogcli access/errors."
---

# Gogcli Ops

## Overview
Standardize gogcli usage: verify auth, resolve IDs from URLs, default to read-only checks, then run the minimum command needed.

## Quick start
- Confirm gogcli is available: `gog --version`
- List accounts and pick one explicitly if more than one: `gog auth list`
- Resolve URL to ID with `python3 scripts/gog_parse_url.py "<url-or-id>"`
- Run a read-only metadata command first (Drive/Sheets/Docs/Slides)

## Workflow decision tree
1. Identify target type: `sheet | doc | slide | file | folder | id | unknown` via `scripts/gog_parse_url.py`.
2. Choose the smallest read-only command to confirm access:
   - Sheets: `gog sheets metadata <spreadsheetId>`
   - Docs: `gog docs info <docId>`
   - Slides: `gog slides info <presentationId>`
   - Drive file/folder: `gog drive get <fileId>` or `gog drive permissions <fileId>`
3. Only proceed to write operations (update/append/move/share/delete) after explicit user confirmation.

## Core tasks

### Auth and account selection
- Show stored accounts: `gog auth list`
- Show auth configuration: `gog auth status`
- Add/authorize account: `gog auth add <email>`
- Always use `--account <email>` when multiple accounts exist.

### Resolve IDs from URLs
- Parse a URL or ID:
  - `python3 scripts/gog_parse_url.py "<url-or-id>"`
- If output type is `unknown`, ask for a direct ID or a different URL.

### Drive (files/folders)
- List root or a folder: `gog drive ls`
- Search by query: `gog drive search "<query>"`
- Get metadata: `gog drive get <fileId>`
- Download/export: `gog drive download <fileId>`
- Permissions check: `gog drive permissions <fileId>`

### Sheets
- Metadata: `gog sheets metadata <spreadsheetId>`
- Read values: `gog sheets get <spreadsheetId> <range>`
- Export: `gog sheets export <spreadsheetId>`
- Write operations (update/append/clear/format): require explicit confirmation and exact range.

### Docs
- Metadata: `gog docs info <docId>`
- Read text: `gog docs cat <docId>`
- Export: `gog docs export <docId>`

### Slides
- Metadata: `gog slides info <presentationId>`
- Export: `gog slides export <presentationId>`

### Output modes
- Use `--plain` for stable TSV output.
- Use `--json` when a caller wants structured output.
- Use `--no-input` in non-interactive flows to avoid hanging.

## Error handling
- 403/404: verify account (`gog auth list`), check permissions (`gog drive permissions <fileId>`), and confirm the ID.
- If access fails, request the user to share the file with the selected account or provide the correct account.

## Resources
- See `references/gogcli-cheatsheet.md` for a compact command list.
- Use `scripts/gog_parse_url.py` to normalize URLs into IDs before running commands.

Overview

This skill standardizes gogcli operations for Google Workspace (Drive, Sheets, Docs, Slides). It helps verify authentication, resolve IDs from URLs, run safe read-only checks, and perform minimal commands needed to satisfy user requests. The default behavior favors non-destructive actions and requires explicit confirmation before any write operation.

How this skill works

It inspects the incoming request for Google file URLs or IDs, then normalizes them using the provided parsing script to determine type (sheet, doc, slide, file, folder). It verifies available gogcli accounts and runs a small read-only command to confirm access and metadata. If the user asks for changes, it prompts for explicit confirmation, picks the minimum write command required, and uses account scoping flags to avoid accidental cross-account actions.

When to use it

  • User asks to check, list, or search Google Drive or Workspace files via gogcli.
  • User provides a Google URL or ID that needs parsing to identify type and ID.
  • User requests export, read, or metadata inspection (safe, read-only workflows).
  • User requests updates/appends/moves/shares — only after explicit confirmation.
  • Troubleshooting gogcli auth, permissions errors (403/404) or account selection issues.

Best practices

  • Always run a read-only metadata command first to confirm target and permissions.
  • Resolve any URL to a canonical ID with the parsing script before running gogcli commands.
  • When multiple accounts exist, always pass --account <email> to avoid acting as the wrong user.
  • Default to --plain or --json output modes depending on downstream parsing needs; avoid interactive prompts with --no-input in automation.
  • Require an explicit confirmation step before performing any write/delete operation.

Example use cases

  • User sends a Google Sheets URL: parse the URL, run gog sheets metadata, then return summary or values on request.
  • User asks to list files in a folder: resolve the folder ID, run gog drive ls or search, return TSV or JSON results.
  • User requests export of a Docs/Slides file: confirm account access, run gog docs export or gog slides export, deliver exported file link.
  • User reports 403/404: check gog auth list, run gog drive permissions and suggest sharing steps with the selected account.

FAQ

What if the parser returns "unknown"?

Ask the user for a direct ID or an alternate URL; re-run the parser and only proceed after a valid type is identified.

How do I avoid interactive hangs in automation?

Use --no-input and choose --plain or --json output to keep commands non-interactive and machine-parseable.