terrylica/cc-skills

gdrive-access

Access Google Drive via CLI with 1Password OAuth: list files, download, and sync folders.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/terrylica/cc-skills --skill gdrive-access

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

Google Drive Access

List, download, and sync files from Google Drive programmatically via Claude Code.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

MANDATORY PREFLIGHT (Execute Before Any Drive Operation)

CRITICAL: You MUST complete this preflight checklist before running any gdrive commands. Do NOT skip steps.

Step 1: Check CLI Binary Exists

bash
ls -la "$HOME/.claude/plugins/marketplaces/cc-skills/plugins/productivity-tools/skills/gdrive-access/scripts/gdrive" 2>/dev/null || echo "BINARY_NOT_FOUND"

If BINARY_NOT_FOUND: Build it first:

bash
cd ~/.claude/plugins/marketplaces/cc-skills/plugins/productivity-tools/skills/gdrive-access/scripts && bun install && bun run build

Step 2: Check GDRIVEOPUUID Environment Variable

bash
echo "GDRIVE_OP_UUID: ${GDRIVE_OP_UUID:-NOT_SET}"

If NOT_SET: You MUST run the Setup Flow below. Do NOT proceed to gdrive commands.

Step 3: Verify 1Password Authentication

bash
op account list 2>&1 | head -3

If error or not signed in: Inform user to run op signin first.


Setup Flow (When GDRIVEOPUUID is NOT_SET)

Follow these steps IN ORDER. Use AskUserQuestion at decision points.

Setup Step 1: Check 1Password CLI

bash
command -v op && echo "OP_CLI_INSTALLED" || echo "OP_CLI_MISSING"

If OP_CLI_MISSING: Stop and inform user:

1Password CLI is required. Install with: brew install 1password-cli

Setup Step 2: Discover Drive OAuth Items in 1Password

bash
unset HTTPS_PROXY HTTP_PROXY   # the OAuth proxy 502s api.1password.com
op vault list                  # FIRST: see which vaults this credential can actually reach
op item list --vault "<vault-from-above>" --format json 2>/dev/null | jq -r '.[] | select(.title | test("drive|oauth|google"; "i")) | "\(.id)\t\(.title)"'

⚠ Do not hardcode `Employee`. When op runs under a service-account token it sees only the vaults granted to that token, and --vault Employee fails with "Employee" isn't a vault in this account — which surfaces confusingly as a jq: parse error if you pipe it blind. Always run op vault list first and set GDRIVE_OP_VAULT accordingly. A service account also requires --vault on every op item get; without it you get a vault query must be provided.

Parse the output and proceed based on results:

Setup Step 3: User Selects OAuth Credentials

If items found, use AskUserQuestion with discovered items:

AskUserQuestion({
  questions: [{
    question: "Which 1Password item contains your Google Drive OAuth credentials?",
    header: "Drive OAuth",
    options: [
      // POPULATE FROM op item list RESULTS - example:
      { label: "Google Drive API (56peh...)", description: "OAuth client in Employee vault" },
      { label: "Gmail API - project-f (abc12...)", description: "Can also access Drive" },
    ],
    multiSelect: false
  }]
})

If NO items found, use AskUserQuestion to guide setup:

AskUserQuestion({
  questions: [{
    question: "No Google Drive OAuth credentials found in 1Password. How would you like to proceed?",
    header: "Setup",
    options: [
      { label: "Create new OAuth credentials (Recommended)", description: "I'll guide you through Google Cloud Console setup" },
      { label: "I have credentials elsewhere", description: "Help me add them to 1Password" },
      { label: "Skip for now", description: "I'll set this up later" }
    ],
    multiSelect: false
  }]
})
  • If "Create new OAuth credentials": Read and present references/gdrive-api-setup.md
  • If "I have credentials elsewhere": Guide user to add to 1Password with required fields
  • If "Skip for now": Inform user the skill won't work until configured

Setup Step 4: Confirm Environment Configuration

The CLI reads GDRIVE_OP_UUID (and optionally GDRIVE_OP_VAULT) from the process environment and nothing else. After user selects an item (with UUID), use AskUserQuestion:

AskUserQuestion({
  questions: [{
    question: "Export GDRIVE_OP_UUID from your shell profile (~/.zshrc)?",
    header: "Configure",
    options: [
      { label: "Yes, add to ~/.zshrc (Recommended)", description: "Appends an export line; applies to every new shell" },
      { label: "Show me the line only", description: "I'll add it manually, or pass it inline per call" }
    ],
    multiSelect: false
  }]
})

If "Yes, add to ~/.zshrc": check that no GDRIVE_OP_UUID export already exists, then append:

bash
export GDRIVE_OP_UUID="<selected-uuid>"
export GDRIVE_OP_VAULT="<vault-from-step-2>"   # only if not Employee

If "Show me the line only": Output the export lines for the user to add manually. Passing the variable inline per call (GDRIVE_OP_UUID=<uuid> gdrive ..., as Step 6 does) also works.

Setup Step 5: Reload and Verify

bash
source ~/.zshrc && echo "GDRIVE_OP_UUID after reload: ${GDRIVE_OP_UUID:-NOT_SET}"

If still NOT_SET: Inform user to restart their shell.

Setup Step 6: Test Connection

bash
GDRIVE_OP_UUID="${GDRIVE_OP_UUID}" $HOME/.claude/plugins/marketplaces/cc-skills/plugins/productivity-tools/skills/gdrive-access/scripts/gdrive list 1wqqqvBmeUFYuwOOEQhzoChC7KzAk-mAS

If OAuth prompt appears: This is expected on first run. Browser will open for Google consent.


Drive Commands (Only After Preflight Passes)

bash
GDRIVE_CLI="$HOME/.claude/plugins/marketplaces/cc-skills/plugins/productivity-tools/skills/gdrive-access/scripts/gdrive"

# List files in a folder
$GDRIVE_CLI list <folder_id>

# List with details (size, modified date)
$GDRIVE_CLI list <folder_id> --verbose

# Search for files
$GDRIVE_CLI search "name contains 'training'"

# Get file info
$GDRIVE_CLI info <file_id>

# Download a single file
$GDRIVE_CLI download <file_id> -o ./output.pdf

# Sync entire folder to local directory
$GDRIVE_CLI sync <folder_id> -o ./output_dir

# Sync with subfolders
$GDRIVE_CLI sync <folder_id> -o ./output_dir -r

# JSON output (for parsing)
$GDRIVE_CLI list <folder_id> --json

Creating a native Google Doc (write)

create-doc uploads a local HTML (or .docx) source and has Drive convert it into a native Google Doc (application/vnd.google-apps.document) — the team can open + comment on it directly, no "convert" step. This is the recommended Drive pattern: files.create with the target mimeType in the metadata and the source bytes as media, sent as a multipart upload (a simple upload silently skips conversion).

bash
# Markdown is the usual author format → HTML (highest-fidelity import) → native Google Doc
pandoc notes.md -o /tmp/notes.html --standalone
$GDRIVE_CLI create-doc /tmp/notes.html --name "Meeting Notes" --parent <folder_id>
# → prints the new Doc's id, mimeType (application/vnd.google-apps.document), and docs.google.com link

# Overwrite an existing Doc's contents in place (keeps the same id / link / comments):
$GDRIVE_CLI create-doc /tmp/notes.html --update <doc_id>

Why not rclone / `.docx`? rclone's --drive-import-formats is unreliable for this (name-collision and sync-confusion gotchas), and a plain .docx in Drive opens in Docs but isn't a native Doc. The Drive API conversion above is the robust FOSS path.

Write scope (one-time re-auth). create-doc needs the drive.file scope (create/manage files this app makes — least-privilege, NOT full-drive). It was added alongside the original drive.readonly, so the first write re-prompts for consent. If it doesn't, force it: rm ~/.claude/tools/gdrive-tokens/$GDRIVE_OP_UUID.json then re-run. --update only works on Docs this app created (drive.file limitation); to overwrite externally-created Docs, broaden the scope to auth/drive.

Rate limits & retries (built in)

Drive returns HTTP 403 `rateLimitExceeded` / `userRateLimitExceeded` (and sometimes 429) when a project bursts too many queries — we hit this doing several writes back-to-back. The CLI now wraps every Drive call in exponential backoff with jitter (withBackoff in lib/drive.ts): wait min(2^n·1000 + random_ms, 64s), finite retries, per Google's official guidance. Non-rate-limit errors still fail loud. To stay under the limit proactively: batch / space out bulk operations, avoid redundant metadata calls, and don't refresh the token on every call.

When the saved token is dead: Error: invalid_grant

Token expired, refreshing... followed by `Error: invalid_grant` means the stored refresh token is revoked or expired — not the access token. Refreshing cannot recover it. Causes: the OAuth client is still in Google Cloud "Testing" publishing status (refresh tokens then expire after 7 days), the user revoked app access, or the password changed. The only fix through this CLI is a full re-consent, which needs an interactive browser:

bash
rm ~/.claude/tools/gdrive-tokens/$GDRIVE_OP_UUID.json   # then re-run any gdrive command

Fallback that needs no browser: `rclone`. If rclone listremotes shows a type = drive remote for the same Google account, it carries its own independent token and usually still works. Verified 2026-09-02 when invalid_grant blocked the CLI entirely. Access an arbitrary folder by ID — including one under "Shared with me", which has no My Drive path:

bash
rclone lsjson --recursive --max-depth 2 --drive-root-folder-id <folder_id> <remote>:
rclone lsjson --metadata --drive-root-folder-id <folder_id> <remote>:<subfolder>   # adds owner + btime (created)
rclone copy --drive-root-folder-id <folder_id> "<remote>:<subfolder>/<file>" ./dest/

--metadata is the only way to get owner and created time (`btime`); plain lsjson returns neither. Always report which path you used — the rclone remote may be a different Google identity than GDRIVE_OP_UUID.

Extracting Folder ID from URL

Google Drive folder URL:

https://drive.google.com/drive/folders/1wqqqvBmeUFYuwOOEQhzoChC7KzAk-mAS
                                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                       This is the folder ID

Drive Search Syntax

QueryDescription
name contains 'keyword'Name contains keyword
name = 'exact name'Exact name match
mimeType = 'application/pdf'By file type
modifiedTime > '2026-01-01'Modified after date
trashed = falseNot in trash
'<folderId>' in parentsIn specific folder

Reference: <https://developers.google.com/drive/api/guides/search-files>

Environment Variables

VariableRequiredDescription
GDRIVE_OP_UUIDYes1Password item UUID for OAuth credentials
GDRIVE_OP_VAULTUsually1Password vault. Code default is Employee, which a service-account token generally CANNOT see — run op vault list and set this explicitly

Token Storage

OAuth tokens stored at: ~/.claude/tools/gdrive-tokens/<uuid>.json

  • Central location (not in plugin, not in project)
  • Organized by 1Password UUID (supports multi-account)
  • Created with chmod 600

Google Docs Export

Google Docs (Docs, Sheets, Slides) are automatically exported:

Google TypeExport Format
Document.docx
Spreadsheet.xlsx
Presentation.pptx
Drawing.png

References

Post-Change Checklist

  • [ ] YAML frontmatter valid (no colons in description)
  • [ ] Trigger keywords current
  • [ ] Path patterns use $HOME not hardcoded paths
  • [ ] References exist and are linked

Post-Execution Reflection

After this skill completes, reflect before closing the task:

  1. Locate yourself. — Find this SKILL.md's canonical path before editing.
  2. What failed? — Fix the instruction that caused it.
  3. What worked better than expected? — Promote to recommended practice.
  4. What drifted? — Fix any script, reference, or dependency that no longer matches reality.
  5. Log it. — Evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.

같은 저장소의 Skills

더 많은 Skills

모든 Skills
terrylica
커뮤니티

academic-pdf-to-gfm

Convert academic PDF papers to GitHub-renderable GFM markdown with math equations. TRIGGERS - PDF, GitHub markdown, math

1시간 설치 수
1
GitHub Stars
2
업데이트
11월 5일
terrylica
커뮤니티

adr-code-traceability

Add ADR references to code for traceability. TRIGGERS - ADR traceability, code reference, document decision in code.

1시간 설치 수
1
GitHub Stars
2
업데이트
11월 5일
terrylica
커뮤니티

arxiv-source-first-paper-ingest

Read an arXiv paper faithfully by fetching the authors' own LaTeX source instead of OCR-ing the PDF. Extracts every display equation with its label, environment and enclosing proposition, renders each to MathML, and proves usability by compiling each formula with a real TeX engine. Use when you need a paper's formulas exactly — to replicate a method, implement a loss function or custom objective, verify a quoted number, or check a claim against what the authors actually wrote. TRIGGERS - read th

1시간 설치 수
1
GitHub Stars
2
업데이트
11월 5일
terrylica
커뮤니티

azure-provision

Bootstrap Azure automation when interactive az login is blocked by a Conditional Access policy (error 530035, "Device state: Unregistered"). Mints a service principal through the Azure Portal session ONCE — using Microsoft Graph over a captured token, not DOM clicking — then provisions resource groups, Cognitive Services / AI Language / Speech resources and their keys entirely via az/REST, writing key AND endpoint together into the SCS vault. Use when az login fails but the portal works, when mo

1시간 설치 수
1
GitHub Stars
2
업데이트
11월 5일