Quick Answer: gdirect is a Rust command-line client for Google Drive. It browses, downloads, uploads and mounts your Drive from a terminal, using multi-connection, resumable transfers. After a one-time OAuth setup with your own Desktop app client, run gdirect browse or gdirect download FILE_ID.

If you live in a terminal, most Google Drive tools feel wrong. They push you into a browser, hide transfer progress, or stall on large files. The Google Drive command line space is small, and gdirect is one of the more complete options. It's a single binary, and it works the way a power user expects: a keyboard-driven file list, a download queue, and a mount for when you want Drive as a folder.

Browsing Drive with keyboard shortcuts

Running gdirect with no arguments opens the same interface as gdirect browse. The screen splits into three panes: the parent folder, the current folder, and a preview of the selected item. The layout borrows from yazi, and if you already use it, the movement keys will feel familiar. j and k move through the list, l opens a folder, and h goes back up.

The part most people underuse is the marking system. Space marks an item, and marks survive when you move between folders. That lets you select files from three folders and queue them in one go. Ctrl-a marks everything visible, and / filters the current folder by name.

Here's the practical catch. Downloads run one at a time through a queue, not in parallel. Each file shows its state as ◦ queued, ↓ downloading, ✓ saved, or ✗ failed, and the Downloads panel shows overall progress. You can't speed up the queue by opening more tabs, so the connection count per file matters more.

Setting up your own Google OAuth client

gdirect doesn't ship a shared Google client. You create one in a Google Cloud project, download a Desktop app OAuth client JSON, and point gdirect at it once. The README estimates about 10 minutes for this step, and it's a one-time cost.

  1. Create or pick a Google Cloud project and enable the Drive API.
  2. Configure the OAuth consent screen, then create a client of type Desktop app.
  3. Download the client JSON to your machine.
  4. Run gdirect login --client-secret ~/Downloads/client_secret.json and approve in the browser.
  5. Delete the JSON if you like. gdirect stores credentials in its own SQLite file and doesn't need it again.

Why not ship a shared client? Because a shared client means shared quota and a shared trust boundary. Each user holding their own client keeps those separate. The trade-off is setup friction, and the README's troubleshooting section covers sign-in problems and a 7-day expiry that affects some setups. Plan for that if you're automating anything.

How gdirect routes traffic to Google

This is the section most readers skip, and it explains the most surprising behavior. For Drive API calls, downloads and uploads, gdirect doesn't always connect through your default DNS path. The first transfer command scans candidate Google IPs, probes each one, and keeps the fastest working route for 24 hours. Sign-in and token refresh still go through your normal system network to oauth2.googleapis.com.

Certificate checks are strict. According to the README, gdirect verifies certificates against Google's own GTS roots, which are embedded in the binary, and never against a system CA bundle. The reasoning is simple: if a third-party CA is compromised, it can't vouch for Google to gdirect. You can override this with --ca-cert FILE, but the default is the safer choice.

Here's where the common advice breaks. Most people assume a TUN-mode VPN or proxy helps any tool reach its destination. For gdirect, it can do the opposite. If the VPN captures the scanned IPs and sends them through fake-ip DNS, the scan finds nothing. The fix is to route those Google IPs DIRECT and turn off fake-ip for them. Run gdirect scan --list to see which IPs it's using.

That said, this is a network-level technique, and you need to check the rules where you live and Google's terms of service before relying on it. The README is open about the design, but it doesn't make it risk-free. Treat the routing as a tool for reaching a service you're entitled to use, not as a guarantee.

Downloads, resume and integrity checks

Downloads are where gdirect earns its keep. It uses multi-connection transfers, and -j N sets the connection count for one command. The saved default starts at 8 and can be changed from 1 to 16 with +/- inside browse. More connections help on high-latency links. They don't always help on a fast local link, so test your own network with -j 1 and then the default before you assume more is better.

Resume is simple. If a download or upload is interrupted, run the same command again. For a large file, that's the difference between finishing and starting over. gdirect also checks completed files against Drive's MD5 checksum, so a corrupted transfer gets flagged rather than silently saved.

Two behaviors catch people off guard. Files with the same name in one session get saved as name (2).ext, not overwritten. Uploads always create a new file and never overwrite one with the same name. That's safer, but it means repeated uploads create duplicates, so clean up after yourself.

Google Docs, Sheets and Slides don't download as normal files. Use --export application/pdf to export a Doc as a PDF, and gdirect download FOLDER_ID saves a folder with its subfolders into <output>/<folder name>/.

Browse versus mount: choosing the right mode

browse and mount solve different problems. browse is for picking files and moving data deliberately. mount makes Drive look like a local folder through rclone, which suits tools that expect a filesystem. The trade-offs are real, and the table below sums them up.

ModeNetwork routeExtra dependenciesPlatforms
browse, download, uploadScanned Google IP, with automatic fallback to a forged identityNone beyond the gdirect binarymacOS 15+, Linux x86_64 (glibc 2.35+), Windows x86_64
login and token refreshYour normal system networkNoneAll supported platforms
mountYour normal system networkrclone 1.75.2+; FUSE3 on Linux, WinFsp on WindowsmacOS (built-in NFS client, no FUSE), Linux, Windows

Mounting has its own sharp edges. Writes go to a local cache first and upload in the background. The cache aims to stay under 5 GiB, but open or unsent files can exceed that. The README says uploads are done when the mount log shows to upload 0, uploading 0, so check that line before you unmount.

Here's the failure mode to plan for. If you unmount while files are still pending, unmount keeps them, and the next mount uploads them. That's safe, but only if you actually remember to remount. On Windows, mount runs in the foreground and stops on Ctrl-C, so it won't survive closing the terminal.

Install requirements and build options

Prebuilt binaries cover macOS 15+ on Apple Silicon and Intel, Linux x86_64 with glibc 2.35 or newer, and Windows x86_64. The install script puts gdirect in ~/.local/bin, and on Windows it goes to %LOCALAPPDATA%\gdirect\bin. Pass --with-mount (or -WithMount in PowerShell) if you need mount support.

Alpine, musl, older glibc and Linux ARM64 need a source build. Here's what that requires:

  • Rust 1.91 or newer
  • A C++ compiler, make, curl and OpenSSL 3
  • The ./scripts/build-libaria2.sh step, which builds the pinned libaria2 engine

Some people get stuck on the libaria2 build because it compiles a pinned transfer engine rather than linking a system copy. Budget extra time for that, and install the listed build tools before you start.

Your data stays in one private SQLite file, stored at ~/Library/Application Support/gdirect/state.sqlite3 on macOS, ~/.local/share/gdirect/state.sqlite3 on Linux, and %LOCALAPPDATA%\gdirect\state.sqlite3 on Windows. Use --db PATH to choose another location. gdirect logout removes credentials but keeps scanned IPs. To switch accounts, use gdirect login --reauth.

Frequently Asked Questions

What is a Google Drive command line tool?

A Google Drive command line tool is a program that lets you list, download, upload and manage Drive files from a terminal instead of a browser. gdirect is one example, and it adds a keyboard-driven browser, a download queue, resumable multi-connection transfers, and an optional rclone-based mount. It suits scripting and large transfers, but it still needs a one-time Google OAuth setup.

How do I download a Google Drive file from the command line?

Run gdirect download FILE_ID_OR_URL to save the file to ./downloads/. Add -o file.zip to choose the name. Use -j N to set the number of connections for that command. If the download is interrupted, run the same command again to resume.

Why does gdirect scan Google IPs before downloading?

gdirect scans candidate Google IPs to find a route that connects reliably from your network, then keeps the fastest working one for 24 hours. This matters when a default path is slow or blocked. If you use a TUN-mode VPN, you must route the scanned IPs DIRECT, or the scan finds nothing.

Can I use gdirect without creating a Google Cloud project?

No. gdirect doesn't ship a shared OAuth client, so you need your own Desktop app client JSON from a Google Cloud project. Setup takes about 10 minutes and happens once. After login, you can delete the JSON file.

Does gdirect overwrite files when I upload them?

No. Uploads always create a new file, even when a file with the same name exists. Repeated uploads therefore create duplicates, so check the destination folder before you rerun a command.

Start with a folder you already know well. Run gdirect download FOLDER_ID once with -j 1 and again with the default of 8, then compare the times on your own network. Pass this to anyone wrestling with slow Drive transfers from a terminal, and the result will tell you more than any benchmark.