DocsCLIco gdrive

co gdrive

List, search, download, and upload Google Drive files from the terminal — the same Drive access your agents get from the GDrive tool, as a command.

Download

Drive was added to the requested OAuth scopes after Gmail and Calendar. If you connected Google before that, run co auth google once more — a token refresh cannot widen scopes.

Quick Start

code
bash
# Connect your Google account (one-time)
co auth google

# See what changed recently (the zero-arg default)
co gdrive

# Download file #3 from the listing
co gdrive get 3

# Upload something
co gdrive put report.pdf

That's the whole surface. Everything below is detail.

Setup

Terminalbash

$co auth google

co gdrive needs a connected Google account carrying the drive scope. Because that scope shipped later than Gmail and Calendar, an older token has everything except Drive — and since a refresh cannot widen scopes, the only fix is to re-consent. The command tells you exactly that if it happens.

Commands

co gdrive — Recent files

Terminalbash

$co gdrive

$co gdrive list --last 50

With no subcommand you get your 20 most recently modified files — same as co gdrive list. --last, -n changes the count. Trashed files are excluded.

Files are numbered, and numbers mean your last listing — co gdrive get 3 downloads the third row of the table you just saw. Running co gdrive again renumbers.

co gdrive search <query> — Find by name

Terminalbash

$co gdrive search report

$co gdrive search "Q3 budget" -n 5

One caveat worth knowing: Drive matches word prefixes, not any substring. On a file named HelloWorld, searching Hello matches and World does not. That's the API's behavior, not ours.

co gdrive get <#> — Download

code
bash
co gdrive get 3                       # into the current directory
co gdrive get 3 --to ~/Downloads      # into a directory
co gdrive get 3 --to notes.md         # to an exact path
co gdrive get 1A2b3C4d5E6f7G8h        # by full file id

Google Docs, Sheets, and Slides have no file bytes of their own, so they are exported on the way down and get the matching extension:

In Drive	Downloads as
Google Doc	Markdown (.md)
Google Sheet	CSV (.csv, first sheet only)
Google Slides	PDF (.pdf)
Google Drawing	PDF (.pdf)

Everything else downloads byte-for-byte. Folders and Forms have no export format at all — the command says so rather than writing a broken file. Shortcuts resolve to whatever they point at.

co gdrive put <path> — Upload

Terminalbash

$co gdrive put report.pdf

$co gdrive put ./out/report.pdf --name "Q3 Report.pdf"

Uploads to the root of your Drive and prints the link. --name sets the name in Drive; without it the local filename is used.

co gdrive rm <#> — Trash

Terminalbash

$co gdrive rm 3

Moves the file to the Drive trash. It is not permanently deleted — restore it from drive.google.com if that was a mistake.

Piping

In a terminal you get a Rich table with truncated columns. When output is piped, each file is one tab-separated row of name, type, size, and the full file id, so scripts never receive a truncated value.

code
bash
co gdrive list -n 100 | cut -f4      # just the ids
co gdrive search report | cut -f1    # just the names

Same Functions, in Your Agent

The CLI wraps the GDrive tool, so hand it to any agent and it gets the same reach:

main.py
python
from connectonion import Agent, GDrive

agent = Agent("assistant", tools=[GDrive()])
agent.input("What did I change in Drive this week?")

Or call the methods directly:

main.py
python
drive = GDrive()
drive.list_files(last=20)
drive.search_files("report")
drive.download("1A2b3C4d5E6f7G8h", dest="~/Downloads")
drive.upload("report.pdf", name="Q3 Report.pdf")
drive.delete("1A2b3C4d5E6f7G8h")

Troubleshooting

• "Google account not connected" → run co auth google.
• "Google Drive permission missing" → your token predates Drive support; run co auth google again to re-consent.
• "No file #N in your last listing" → the number is out of range or the listing changed; run co gdrive to refresh the numbering.
• A search finds nothing you can see in Drive → Drive matches word prefixes, not substrings. Try the beginning of a word in the name.

co gdrive

Quick Start

Setup

Commands

co gdrive — Recent files

co gdrive search <query> — Find by name

co gdrive get <#> — Download

co gdrive put <path> — Upload

co gdrive rm <#> — Trash

Piping

Same Functions, in Your Agent

Troubleshooting

See Also

Star us on GitHub