
Running a cURL download file command is a standard way for developers to retrieve releases, build artifacts, and raw data across macOS, Linux, and Windows environments, including automated CI pipelines.
To ensure transfers are smooth, engineers rely on built-in parameters for handling HTTP redirects, resuming interrupted downloads, and specifying output targets.
All of these granular options are easy to configure via a lightweight command line utility. With the right flags in place, you ensure that every cURL download file operation remains reliable and fully repeatable.
Table of Contents
- cURL download file commands: key insights
- cURL download file basics: commands for macOS, Linux, and Windows
- How to download a file from a URL when the server redirects your request
- How to resume interrupted downloads and limit transfer speed
- How to safely use bearer tokens to authenticate private downloads
- How to route cURL downloads through a proxy provider for automated workflows
- How to automate repeatable file downloads in a shell script
- How to fix common cURL download errors without sacrificing security
- Frequently asked questions about cURL file downloads on desktop systems
cURL download file commands: key insights
- The uppercase
-Ouses the file’s original name from the URL when saving, while the lowercase-olets you assign a new name during the download. - The
-Largument follows redirects automatically, and adding-C -resumes incomplete transfers, as long as the server supports byte ranges. - You should export bearer tokens into system environment variables instead of hardcoding secrets into repo files where they might leak.
- Use the
--proxyflag or the standard proxy environment variables to route download traffic via your proxy server of choice.
cURL download file basics: commands for macOS, Linux, and Windows
On macOS or Linux, use the terminal to check the cURL version:
curl --version
The latest versions of Windows include cURL by default. In PowerShell 5.1, curl is an alias for the Invoke-WebRequest alias, so type curl.exe instead.
Whether you’re running your cURL download file task locally or in CI, this basic command will start you off:
curl -O https://example.com/archive.zipUppercase -O retrieves the name from the URL when saving the file to its new destination. Lowercase -o sets a new local name:
curl -o release.zip https://example.com/download?id=42Otherwise, both save the response to disk just the same.
How to download a file from a URL when the server redirects your request
By default, cURL does not follow redirects. Solve this by adding -L to your command:
curl -L -o package.tar.gz https://example.com/latest-L tells cURL to follow redirects. Common codes are 301, 302, 307 and 308. For cURL download file from URL workflows, use -L with release pages and temporary links. Also, here’s a handy command for inspecting headers and the final http status code:
curl -I -L https://example.com/latestIn scripts, add -f when you download file with cURL. That way, HTTP errors such as 404 or 500 fail the command instead of saving an error page.
How to resume interrupted downloads and limit transfer speed
Use -C - to continue the cURL download file task from the existing local file size, enabling a resume download when the server supports it:
curl -L -C - -o archive.zip https://example.com/archive.zip--limit-rate controls bandwidth. This example caps the transfer at 2 megabytes per second:
curl -L --limit-rate 2M -O https://example.com/large-file.isoPass multiple URLs in one invocation:
curl -O https://example.com/a.zip -O https://example.com/b.zipUse distinct filenames or -o destinations to prevent overwrites.
How to safely use bearer tokens to authenticate private downloads
Private artifact servers may be checking the Authorization header for a bearer token:
curl -L -H "Authorization: Bearer $API_TOKEN" -o build.zip https://example.com/private/build.zipNever use Git to store the secret. Put it instead in API_TOKEN or another environment variable. In CI, make sure all secrets are protected and review the logs to remove credentials from them.
How to route cURL downloads through a proxy provider for automated workflows
Many corporate networks may route outbound traffic through a proxy server. Developers can also connect a proxy from a reliable proxy provider to give automated downloads and CI jobs a stable, consistent route. Set it with --proxy:
curl --proxy http://proxy.example.net:8080 -L -O https://example.com/file.zipAlternatively, you can set http_proxy and https_proxy as environment variables:
export http_proxy="http://proxy.example.net:8080"
export https_proxy="http://proxy.example.net:8080"
curl -L -O https://example.com/file.zipAlways put http_proxy in lowercase, no exceptions. Other proxy variables can work in uppercase, too.
How to automate repeatable file downloads in a shell script
If you need to standardize downloads, shell script is your friend:
#!/usr/bin/env bash
set -euo pipefail
URL="https://example.com/releases/app.tar.gz"
DEST="app.tar.gz"
curl --fail --show-error --location --retry 3 --output "$DEST" "$URL"--fail interprets HTTP 4xx and 5xx responses as errors; --show-error displays diagnostics. Three retries can help with temporary failures, not denied access.
For each cURL download file CI step, verify the publisher’s file checksum.
How to fix common cURL download errors without sacrificing security
An invalid SSL certificate shows cURL cannot verify the server’s identity. This is the expected behavior that protects you from suspicious connections.
To fix this, supply your organization’s CA bundle: --cacert company-ca.pem. Resist the temptation to use -k as a shortcut in production, as it leaves you defenseless.

A 404 status code usually means the path is wrong. Meanwhile, a 403 status code indicates that access was refused. Here’s what you need to check upon running into it:
- permissions;
- token scope;
- required headers;
- whether the link has expired.
To recover interrupted transfers, use --retry with -C -; for diagnostics, use -v.
Frequently asked questions about cURL file downloads on desktop systems
Here are some common questions people learning their way around cURL downloads have.
Can the same cURL download file command work on all three operating systems?
For the command arguments? Yes. Flags like -O, -o, -L, and -C - won’t change between macOS, Linux, and Windows. The headache is everything surrounding the command.
First, PowerShell 5.1 on Windows ships with an alias where curl isn’t actually cURL, so always hardcode curl.exe if this script needs to touch Windows.
Second, SSL trust stores behave differently depending on the operating system’s native crypto backend.
Lastly, don’t mix shell syntax. Bash string interpolation and error bubbling are fundamentally different from PowerShell, so test your variable declarations thoroughly on every target OS.
What difference is there between -O and -o when saving a download?
Uppercase -O retrieves the filename from the URL while lowercase -o saves the response under any alias you chose. The former, therefore, is best used for direct links with meaningful names.
Whereas the latter is good for content that benefits from a predictable naming scheme, such as API endpoints, query strings, or automated jobs.
Why does a cURL download file command return a 403 error?
Encountering a 403 error during a cURL download file task is a sign of a refusal from the server itself. Perhaps the output file relies heavily on a specific session, token, header, or account permission.
It’s also possible the link has lapsed. Review the endpoint documentation and check if the token has the required scope. Make no attempts to bypass access controls yourself. Rather, request the service owner’s permission.
How safe is it to use the -k option to fix a cURL certificate error?
The -k / --insecure option disables certificate verification, so it has no place in production. When verification is disabled, there’s no solid guarantee that the HTTPS server is genuine.
The right solution is to fetch the appropriate CA certificate and supply it via --cacert. On managed systems, obtain the authorized certificate bundle from your administrator and configure cURL to trust that instead.
This guest post was written by Diane P. of Geonix.