gdrive-ftp

gdrive-ftp

A tiny FTP-style client for Google Drive, written in Go. It gives you a familiar interactive shell — ls, cd, pwd, get (download), put (upload), mkdir, rm — that talks to your Drive over the official Drive v3 API.

[!WARNING] This requests full Drive access and can upload, overwrite (put replaces a same-named file's content), and trash files across My Drive and your Shared Drives. rm trashes (reversible); nothing is hard-deleted. Keep credentials.json / token.json private — they grant access to your Drive.

The shell opens at a virtual root that lists My Drive alongside every Shared Drive you can access; the drive name is the first component of every path.

$ gdrive-ftp
Connected to Google Drive. Type 'help' for commands, 'quit' to exit.
gdrive:/> ls
           -                    My Drive/
           -                    Engineering Team/
gdrive:/> cd "My Drive"
gdrive:/My Drive> ls
           -  2026-05-01 09:12  Photos/
           -  2026-04-22 18:30  Work/
       1.4MB  2026-06-10 11:02  budget.xlsx
        gdoc  2026-06-12 14:55  notes
gdrive:/My Drive> cd Work
gdrive:/My Drive/Work> put ./report.pdf
uploaded ./report.pdf -> report.pdf (820.4KB)
gdrive:/My Drive/Work> get budget.xlsx
downloaded budget.xlsx -> budget.xlsx (1.4MB)
gdrive:/My Drive/Work> cd "/Engineering Team/specs"
gdrive:/Engineering Team/specs> quit

Build

Requires Go 1.24+.

go build -o gdrive-ftp .

One-time Google setup

The app talks to Drive on your behalf, so it needs an OAuth client that you own.

1. Go to the Google Cloud Console and create (or pick) a project.
2. APIs & Services → Library → enable the Google Drive API.
3. APIs & Services → OAuth consent screen → configure it (User type External is fine for personal use) and add your Google account under Test users.
4. APIs & Services → Credentials → Create Credentials → OAuth client ID → choose application type Desktop app. Download the JSON.
5. Save that file as credentials.json next to the binary, or at ~/.config/gdrive-ftp/credentials.json, or pass it with -creds.

On first run the app walks you through OAuth consent over the terminal (works the same locally or over SSH — see Authorizing), then caches the resulting token at ~/.config/gdrive-ftp/token.json so you only authorize once. The token is refreshed automatically on later runs.

Keep credentials.json and token.json private — they grant access to your Drive. They are git-ignored by default.

Usage

gdrive-ftp [flags] [command args...]

With no command it starts the interactive shell. With a command it runs that single command and exits (handy for scripts):

gdrive-ftp ls /
gdrive-ftp get /Work/report.pdf ./report.pdf
gdrive-ftp put ./photo.jpg /Photos/photo.jpg

Flags

Flag	Default	Meaning
-creds	./credentials.json or config dir	OAuth client credentials.json
-token	~/.config/gdrive-ftp/token.json	Where to cache the auth token

Authorizing

The first run authorizes over the terminal — no local browser or callback server needed, so it works the same on your laptop or a headless/SSH host. The consent URL is printed; press c then Enter to copy it to your local clipboard (sent via the OSC 52 terminal escape, so it works through SSH if your terminal supports it), press o to try opening a browser on this host, or copy it manually. Open it in your browser, approve, and the browser is redirected to a http://127.0.0.1 URL that fails to load — paste that entire URL back at the prompt (pasting just the code= value also works). The state is verified to guard against CSRF.

Commands