porteden drive

Use porteden drive for Google Drive file and folder management. Use -jc flags for AI-optimized output.

If porteden is not installed: brew install porteden/tap/porteden (or go install github.com/porteden/cli/cmd/porteden@latest).

Setup (once)

• Browser login (recommended): porteden auth login — opens browser, credentials stored in system keyring
• Direct token: porteden auth login --token <key> — stored in system keyring
• Verify: porteden auth status
• If PE_API_KEY is set in the environment, the CLI uses it automatically (no login needed).
• Drive access requires a token with driveAccessEnabled: true and a connected Google account with Drive scopes.

Drive commands (porteden drive)

List & inspect

• List files: porteden drive files -jc
• Search by keyword: porteden drive files -q "budget report" -jc
• Filter by folder: porteden drive files --folder google:0B7_FOLDER_ID -jc
• Filter by MIME type: porteden drive files --mime-type application/pdf -jc
• Filter by name: porteden drive files --name "Q1" -jc
• Shared with me: porteden drive files --shared-with-me -jc
• Modified in range: porteden drive files --modified-after 2026-01-01 --modified-before 2026-02-01 -jc
• All files (auto-paginate): porteden drive files --all -jc
• Get file metadata: porteden drive file google:FILEID -jc
• Get view/download links: porteden drive download google:FILEID -jc
• List permissions: porteden drive permissions google:FILEID -jc

Read content

• Read text content of any file: porteden drive content google:FILEID
  • Google Docs export to text/plain inline
  • Text-like files (text/*, JSON, XML, YAML, CSV) return as-is
  • Binary files return a webViewLink — open in browser
  • Spreadsheets/presentations are steered to: porteden sheets content / porteden slides read

Working with spreadsheets

For anything beyond a quick text dump of a Google Sheet, use the dedicated porteden sheets commands (see the porteden-sheets skill) — drive content only reads:

• Read all tabs / specific ranges: porteden sheets content google:SHEETID -jc / --ranges "Summary!A1:C100"
• Read one tab in full: porteden sheets read-tab google:SHEETID --title "Q2 Forecast" -jc
• Write / append cells: porteden sheets write google:SHEETID --range "Sheet1!A1:B2" --values '[["Name","Score"]]' / porteden sheets append
• Batch write multiple ranges atomically: porteden sheets write google:SHEETID --updates '[{"range":"Summary!A1:B1","values":[["Metric","Value"]]}]'
• Manage tabs: porteden sheets add-tab / delete-tab / metadata via porteden sheets info google:SHEETID -jc
• Create a spreadsheet (optionally CSV-seeded): porteden sheets create --name "Q1 Budget" --csv-file ./sales.csv

Create & upload

• Create file with inline content: porteden drive create --name "Notes.md" --mime-type text/markdown --content "# Notes"
• Create from local text file: porteden drive create --name "Plan" --mime-type application/vnd.google-apps.document --content-file ./plan.md --content-mime-type text/markdown
• Create CSV file: porteden drive create --name "Data.csv" --mime-type text/csv --content-file ./data.csv
• Upload binary file: porteden drive upload --file ./report.pdf --name "Q1 Report.pdf"
• Upload to folder: porteden drive upload --file ./data.csv --name "Data.csv" --folder google:0B7_FOLDER
• Create folder: porteden drive mkdir --name "Project Files"
• Create folder in folder: porteden drive mkdir --name "Reports" --parent google:0B7_FOLDER

Manage

• Rename: porteden drive rename google:FILEID --name "New Name.pdf"
• Move: porteden drive move google:FILEID --destination google:0B7_DEST_FOLDER
• Copy (duplicate): porteden drive copy google:FILEID --name "Working copy"
• Copy into a folder: porteden drive copy google:FILEID --folder google:0B7_DEST_FOLDER
• Share with user: porteden drive share google:FILEID --type user --role reader --email user@example.com
• Share with domain: porteden drive share google:FILEID --type domain --role reader --domain example.com
• Share publicly: porteden drive share google:FILEID --type anyone --role reader
• Delete (trash): porteden drive delete google:FILEID (prompts) or porteden drive delete google:FILEID -y

Notes

• Credentials persist in the system keyring after login. No repeated auth needed.
• Set PE_PROFILE=work to avoid repeating --profile.
• -jc is shorthand for --json --compact: strips noise, limits fields, reduces tokens for AI agents.
• File IDs are always provider-prefixed (e.g., google:1BxiMVs0XRA5...). Pass them as-is.
• porteden drive files --all auto-paginates (safety cap: 50 pages). Check hasMore in JSON output.
• porteden drive content is the universal text reader — use it instead of download when you need the textual content of a file. For Google Workspace types (Sheets, Slides) it steers to the dedicated commands (porteden sheets content, porteden slides read) via stderr hints.
• porteden drive create uses inline JSON (UTF-8 text only, ≤ 10 MB). For binary content use porteden drive upload. For Workspace target MIME types (application/vnd.google-apps.{document,spreadsheet,presentation}) Drive auto-imports the content; otherwise the file is stored as-is.
• porteden drive copy duplicates any Drive file — including Google Docs/Sheets/Slides (per-type wrappers docs copy / sheets copy / slides copy exist too). Both --name and --folder are optional (defaults: Google's "Copy of …" name, source's folder). Copy is not idempotent — calling twice creates two copies. Folders cannot be copied (returns PROVIDER_ERROR); SharePoint files aren't supported yet (NOT_SUPPORTED). Requires the copy_file permission on the token.
• accessInfo in responses describes active token restrictions. Always check it to understand what data may be limited.
• authWarnings in list responses indicate provider connection issues.
• delete moves to trash (reversible). Files can be restored from Google Drive trash.
• Confirm before sharing or deleting files.
• Environment variables: PE_API_KEY, PE_PROFILE, PE_FORMAT, PE_COLOR, PE_VERBOSE.