goodls downloads shared Google Drive folders in parallel, with or without an API key

Two different download paths, with different requirements

goodls is described as a high-performance Command Line Interface tool designed to effortlessly download shared files and entire folder structures from Google Drive, and the README frames it with three situations: pulling a single shared document without authentication, performing a resumable download of a massive dataset, or concurrently extracting thousands of files from a shared folder using an API key.

That distinction between the single-file and folder paths runs through the whole design, and it is the first thing to understand.

The single file path needs nothing. Download shared files directly via their URL without any authorization or OAuth2 setup, and no API key or login is required. The README lists the supported URL shapes: Google Docs, Sheets and Slides share links, standard Drive file links, the web content link form with export=download and an id parameter, and, new in v3.4.0, Google Colab notebook links.

The folder path needs a key. To download an entire folder you must provide a Google Cloud API Key, and the README calls that a simple API key with a note on the concurrency feature. There is also a beginner tutorial section on retrieving an API key, which walks through creating a new project in the Google Cloud Console and opening APIs and Services in the sidebar.

The claim about the anonymous path is worth reading carefully rather than skimming. Large files, which normally require multi-step cookie and code verification in the browser, are handled automatically behind the scenes using a highly resilient, multi-strategy bypass scraper.

That is the honest description: the single-file path does not use the API, it scrapes the browser download flow, and it tries several strategies because Google changes that flow. The API key path is the one that talks to the documented interface, and it is the one that scales to thousands of files.

The tool is written in Go, MIT licensed, with the default branch master and the last push on 2026-09-02. The recent releases are v3.4.0 from 2026-06-01, v3.3.1 from the same day and v3.3.0 from 2026-05-31.

Concurrency, the worker pool, and the five-file default

The concurrency model is where the Go implementation shows, and the README is specific about both the mechanism and the default.

By default, goodls will strictly limit concurrent downloads to 5 files at the same time to balance speed and stability, and you can increase the limit to saturate your network bandwidth using the -c or --concurrency flag. The folder example shows it in use:

$ goodls -u [Folder_URL] -key [API_Key] -c 10

The feature is described as powered by Go's advanced Goroutine worker pools and strictly enforced channel semaphores, and goodls downloads multiple files in parallel, drastically reducing extraction time without overwhelming your network.

A channel semaphore is the specific mechanism, and it is the right one for this problem. A worker pool alone bounds the number of goroutines doing work, but a semaphore acquired before the network request bounds the number of simultaneous transfers, which is what actually protects your network and your Drive quota. With both, the tool can have many goroutines in flight, queued on the semaphore, while only the configured number hold a connection.

The default of five is worth reading as a deliberate choice rather than a timid one. The README says it balances speed and stability, and for a tool pointed at a consumer file-sharing service, five parallel transfers is the point where you are unlikely to be rate limited or flagged.

The dependencies support that reading. golang.org/x/sync is in the require block, which is the standard home of the semaphore and errgroup primitives, and the progress UI comes from github.com/vbauerster/mpb/v8, a multi-progress bar library whose whole reason for existing is drawing several synchronised bars in a terminal.

The other two direct dependencies tell you what else the tool does. github.com/PuerkitoBio/goquery is an HTML parser, which is the scraper half of the anonymous download path, and github.com/tanaikech/go-getfilelist is the author's own module for listing files. The CLI itself is built on urfave/cli/v2, and the Drive access is through google.golang.org/api.

Conflict resolution, the resume flag, and what happens to files that already exist

The folder download options are where the tool stops being a downloader and starts being something you can run in a pipeline.

The conflict resolution strategy when a file already exists is set with --conflict or -cf, and the accepted values are prompt, skip, overwrite, newer and rename. The default is prompt in a terminal, which is the right default for an interactive tool and exactly the wrong default for a script, because a prompt in a non-interactive run either hangs or fails. The README notes separately that as of v3.4.0, piping operations and direct -u executions behave in non-interactive CI and CD scripts without hanging, which is a fix to exactly this class of problem.

The mime type filter is -m, and it accepts a comma-separated list. The example given is -m "application/pdf,image/png", which downloads only PDFs and PNGs from the folder. On a folder with thousands of files, that is the option that turns a slow enumeration into a targeted pull.

The --notcreatetopdirectory or -ntd option dumps the folder's contents directly into your current working directory without wrapping them in the top-level folder name, which is what you want when the folder is a set of assets that belong at the top of your project rather than inside a directory named after the share.

And --skiperror or -se means that if one file fails, goodls ignores it and continues downloading the rest of the folder. For a bulk extraction that is the difference between a partial result and a failed job.

The resumable download is a separate mechanism. You can run resumable downloads for massive files by specifying exact byte chunks, for example -r 100m, to safely append data. The topic list names resumable-downloads, and the v3.4.0 release added the proxy and retry support around it: custom proxy configurations with --proxy and automated exponential backoff retries with --retry for all network requests.

The single file options fill out the picture. -e converts Google Docs to a specific format, for example -e pdf or -e ms, which is how you get a spreadsheet as a file rather than a link. -f gives the downloaded file a custom name. -j suppresses the progress bars and outputs the final result as a structured JSON array, and -v writes deep diagnostic HTTP logs to stderr, with the note that the version flag is -V rather than -v.

The MCP server mode, and why it is in a download tool

The seventh core feature is Native MCP Server Integration, described as fully compliant with the Model Context Protocol via standard stdio JSON-RPC.

The README says it automatically manages headless conflict resolutions, automatic directory creations, exponential retries and non-blocking asynchronous execution constraints when invoked by autonomous AI agents like Claude Desktop or Cursor.

Read the list carefully, because every item on it exists to solve a specific failure mode of a tool being driven by an agent. Headless conflict resolutions means the tool will not stop to ask a question that nobody is there to answer. Automatic directory creations handles the case where the agent asked for a path that does not exist. Exponential retries handle transient network failures without the agent having to notice. And the non-blocking asynchronous execution constraints are what stop the stdio JSON-RPC channel from deadlocking when the agent's request takes longer than the agent's patience.

That last point is the one that separates a proper MCP server from a script with an MCP wrapper. The stdio transport is a synchronous request and response channel, and a download tool that blocks it for minutes while transferring a large file will break the protocol rather than merely being slow.

The JSON output mode and the non-interactive guarantees from the previous section are the same design idea seen from the CI angle. If a tool is going to be driven by a program rather than a person, then every place it might stop and ask a question has to become a flag, a default or an error. goodls has both the --json flag and the MCP mode, and the README describes them in the same language of non-hanging behaviour.

The dependency list does not show an MCP library, which suggests the protocol handling is implemented directly against stdio JSON-RPC rather than through a framework, which is what a small tool with one server mode would reasonably do.

Where goodls is the wrong tool

Three limits, and the first is about the dependency on Google's own interfaces.

The first is that both download paths depend on Google Drive continuing to behave the way the tool expects. The folder path depends on the documented API and its quota behaviour, and the anonymous path depends on a bypass scraper that has to keep up with a flow Google changes. Neither is a guarantee, and the tool is explicitly built to work around a moving target, which is honest but is not the same as being stable.

The second is that the anonymous path is a scraping path, and that has consequences beyond fragility. It handles large files that normally require the browser's cookie and code verification, which is exactly the flow that exists to make bulk automated downloads harder. A tool whose feature list calls that a bypass is describing behaviour that may be tightened at any time, and the multi-strategy description is a hint that it has been tightened before. For a one-off document download that is a reasonable trade; for a pipeline you depend on, it is a risk with no published mitigation.

The third is the credential handling. The API key is passed on the command line with -key, and the README claims strict API key masking and source tracking ensure your credentials never accidentally leak into terminal logs or CI and CD pipelines, while still giving you precise feedback on exactly which key is driving the process. A command line argument is visible in the process table to other users on the machine and is captured by shell history, so masking the output does not cover those two exposure paths. If the key can come from the environment instead, that is the safer arrangement for shared machines and for CI logs.

The alternative approach for the folder case is the Google Drive API directly, using a service account or the official client libraries, with a script that lists and downloads what you need. The difference in approach is that a direct API integration gives you a documented contract, service account support for unattended access, and your own control over the concurrency and quota behaviour, while goodls gives you a working binary with a progress UI, a conflict policy and a resumable download in one command. For someone pulling a shared folder of documents once, goodls is much less work. For a nightly job over thousands of files with a service account, the API path is the one that will still work next year.

Editorial conclusion

Adopt goodls if you routinely pull shared Google Drive content into scripts or CI, because it handles anonymous single-file downloads, whole-folder extraction with structure preserved, and bounded parallel transfers in one binary. Do not adopt it if your workflow depends on files that are not shared, because the tool is built around shared links and the folder path needs an API key, and do not assume the anonymous path scales, since it relies on a multi-strategy bypass of the browser download flow rather than the API. Verify first that you have a Google Cloud API key before attempting a folder download, that your concurrency limit is set for your network and your Drive rate limits, since the default of five is deliberately conservative, that the conflict policy you choose is what you want in a non-interactive run, since the default is to prompt in a terminal, and that the proxy setting works for the environment you run in.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. tanaikech/goodls on GitHub