A Step-by-Step Guide to a curl Upload File

Curl upload file allows you to send data to a remote server. The command-line tool supports web forms integral to every web system, including multipart form data and file input fields.

When you execute a curl file upload for any protocol (HTTP, FTP, SMTP, and others), you transfer data via URLs to and from a server. In this post, I’ll guide you through uploading file data using the HTTP protocol on curl successfully, including how to handle different file types like binary files and array files. But before we dive into the nitty-gritty…

Key takeaways

Before diving into the step-by-step details, here are the key takeaways from this guide on using curl for file uploads:

✅ Versatile File Transfers – curl supports multiple protocols, including HTTP, FTP, SFTP, SMTP, and more, making it a powerful tool for file uploads across different platforms.

✅ Multiple Upload Methods – Depending on the server and use case, you can upload files using HTTP POST, multipart form POST, PUT, FTP, S3 presigned URLs, and Artifactory API.

✅ Cross-Platform Compatibility – curl works seamlessly on Windows, macOS, and Linux, with easy installation and setup instructions for each OS.

✅ Secure Authentication Options – Whether uploading to FTP, Artifactory, or AWS S3, you can use basic authentication, API keys, or presigned URLs for secure file transfers.

✅ Automating File Uploads – curl can be integrated into scripts, CI/CD pipelines, and automation workflows, streamlining large-scale file transfers.

✅ Error Handling & Debugging – Use verbose mode (-v), headers (-H), and response codes (-I) to diagnose and resolve upload issues effectively.

By the end of this guide, you’ll be able to upload files to any server or cloud storage with curl, ensuring efficiency, security, and reliability.

What is curl?

Curl stands for client URL. It is a command-line tool built to send data from or to a remote server using various network protocols such as HTTP, FTP, FILE, IMAP, SBM, SMTP, and others. It is capable of handling various file extensions and making curl POST file requests.

Curl runs on Windows, Linux, and macOS platforms. It also has built-in support for HTTP cookies, SSL, user authentication, proxies, and certificate validation.

Since 1998, developers have used curl as a command-line tool and library for transferring data with URLs. It works as both a separate console application and as a dynamic library for other programs, capable of handling different file structures, including binary files, image files, and more.

You also can use curl to download or upload files, including array files, submit web forms, send a curl post file request to API endpoints, and simulate user actions without using a web browser.

How to install curl?

You can install and use curl on Windows, macOS, and Linux operating platforms.

Installing curl on Windows

To install and set up curl on Windows, follow these steps:

Step 1: Download curl

1. Visit the official curl website.
2. Download the Windows installer (64-bit recommended).

Step 2: Extract the Files

1. Locate the downloaded ZIP file (usually in your Downloads folder).
2. Right-click the file and select Extract All….
3. Choose a location for extraction, such as C:\Curl.

Step 3: Add curl to System PATH

To use curl from any command prompt window, add it to the system’s PATH variable:

1. Open File Explorer and navigate to C:\Curl\bin.
2. Copy the full path to the bin folder (e.g., C:\Curl\bin).
3. Open the Start Menu and search for Environment Variables, then select “Edit the system environment variables”.
4. In the System Properties window, click the “Environment Variables” button.
5. Under System Variables, scroll down and select Path, then click Edit.
6. Click New and paste the copied C:\Curl\bin path.
7. Click OK to save changes and exit all windows.

Step 4: Verify Installation

1. Open Command Prompt (Win + R, then type cmd and press Enter).
2. Type the following command and press Enter:
   curl –version
3. If installed correctly, you should see an output similar to this:

curl 8.9.1 (Windows) libcurl/8.9.1 Schannel zlib/1.3 WinIDN

Release-Date: 2024-07-31

Protocols: dict file ftp ftps http https imap imaps ipfs ipns mqtt pop3 pop3s smb smbs smtp smtps telnet tftp

Features: alt-svc AsynchDNS HSTS HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM SPNEGO SSL SSPI threadsafe Unicode UnixSockets

Now, curl is successfully installed and ready to use on Windows! 

Installing curl on macOS

For macOS, curl comes pre-installed on the operating system.

You can decide to update to the latest curl version by installing macOS Homebrew Software Package Manager.

After installing the Homebrew Package Manager, open a terminal and type:

brew install curl

If installed properly, you’ll get the response below when you type ‘curl –version’:

curl 7.31.0 (x86_64-apple-darwin12.4.0) libcurl/7.31.0 OpenSSL/0.9.8x zlib/1.2.5
Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp smtp smtps telnet tftp
Features: IPv6 Large File NTLM NTLM_WB SSL libz

Installing curl on Linux/Ubuntu

For Linux/Ubuntu, you need to enter the following command in a terminal.

sudo apt install curl

or

sudo apt-get install curl

And to verify if curl is correctly installed and working, run the ‘curl –version’ command in a terminal. If positive, you’ll get the response below:

curl --version

curl 7.58.0 (x86_64-pc-linux-gnu) libcurl/7.58.0 OpenSSL/1.1.1 zlib/1.2.11 libidn2/2.0.4 libpsl/0.19.1 (+libidn2/2.0.4) nghttp2/1.30.0 librtmp 2.3
Release-Date: 2018-01-24
Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtmp rtsp smb smbs smtp smtps telnet tftp
Features: AsynchDNS IDN IPv6 Largefile GSS-API Kerberos SPNEGO NTLM NTLM_WB SSL libz TLS-SRP HTTP2 UnixSockets HTTPS-proxy PSL

Learn more about curl, its installation, and usage.

Guide to curl file upload

Uploading files using curl is pretty straightforward once you’ve installed it.

Several protocols allow curl file upload including: FILE, FTP, FTPS, HTTP, HTTPS, IMAP, IMAPS, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, and TFTP.

Each of these protocols works with curl differently for uploading data.

For HTTP (and HTTPS), it offers several ‘uploads’ methods to upload data to a server. Curl provides easy command-line options to do it in three common ways:

• POST
• Multipart form post
• PUT

Let’s take a look at the HTTP protocol and several ways you can execute curl upload data with it!

Uploading a file with curl using HTTP POST 

The POST method is an HTTP file upload method designed to send data to a receiving web application. Many HTML forms on the web rely on this method for functionality.

The POST method uses the -d or –data options to send a chunk of relatively small data to the remote server. 

When a form is submitted, the browser URL-encodes the data and sends it as serialized name=value pairs, separated by ampersand symbols (&).

Example of sending data with the -d option:

curl -d 'name=admin&shoesize=12' http://example.com/

Uploading a file with the -d Option

To upload a file using curl, use the -d (or –data) option and prefix the file path with the @ symbol. This tells curl to read the file’s contents and send it to the server.

curl -d @path/to/data.json https://reqbin.com/echo/post/json

Sending data with a custom content type

If you’re sending data with a custom content type (e.g., JSON, XML, or JavaScript), use the -H (or –header) option to specify the Content-Type.

Example:

curl -d @path/to/data.json -H "Content-Type: application/javascript" https://reqbin.com/echo/post/json

You can read more about the curl HTTP POST file upload method here.

Uploading files with curl using HTTP multipart form POST: a flexible solution for complex data

The HTTP multipart form POST method is widely used to upload files and form data on the web. You can achieve this using the -F (or –form) option in curl.

This method is a variation of the HTTP POST method but sends data in a multipart/form-data format. This format is designed to handle multiple parts of a request, such as text fields and file uploads, making it ideal for complex forms.

Key features of multipart form POST

• Multipart Data Format: The data is divided into multiple sections, each with its own content type and headers.
• Server Dependency: The choice to use multipart POST depends on what the server expects and is configured to handle.

How to use curl with multipart form POST

To send data using multipart form POST, use the -F option. Each -F flag corresponds to one part of the form, and you must add one -F for every input field in the form.

Example:

curl -F "person=anonymous" -F "secret=@file.txt" http://example.com/submit.cgi

• “person=anonymous”: A text field named “person” with the value “anonymous.”
• “secret=@file.txt”: A file field named “secret,” where @file.txt specifies the file to upload.

Notes:

Ensure the server is configured to accept multipart/form-data. The server will reject the request if it expects a different content type.

This method is commonly used for uploading files in HTML forms.

Read more about the HTTP multipart form POST method.

Using the HTTP PUT method for complete resource uploads with curl

PUT is the least used curl file upload HTTP method in HTML forms on the web, and a lot of servers don’t have PUT enabled.

It delivers complete resources meant to be sent as-is on the remote site. Or it could even replace an existing resource there.

To send files using the PUT method, you need to use the –T data option.

curl -T uploadthis http://example.com/

You can read more about the HTTP PUT method here.

Uploading files to an FTP server with curl

The FTP protocol is one of the most common methods used to upload files to remote servers. With curl, you can efficiently upload files to an FTP server using the -T (or –upload-file) option.

Basic command to upload a file

To upload a file to an FTP server, use the following command:

curl -T /path/to/file ftp://ftp.example.com/

• -T /path/to/file: Specifies the file you want to upload.
• ftp://ftp.example.com/: The URL of the FTP server.

Including authentication

If the FTP server requires authentication (username and password), you can include them in the command:

curl -u username:password -T /path/to/file ftp://ftp.example.com/

• -u username:password: Provides the login credentials for the FTP server.

Uploading to a Specific Directory

If you need to upload the file to a specific directory on the server, include the directory path in the URL:

curl -u username:password -T /path/to/file ftp://ftp.example.com/remote/directory/

Notes:

1. Secure FTP (FTPS/SFTP):
   • For FTPS (FTP Secure), use ftps:// instead of ftp://.
   • For SFTP (SSH File Transfer Protocol), use sftp:// instead of ftp://.
2. Verbose Output: Add the -v option for verbose output to see more details about the upload process:

curl -v -u username:password -T /path/to/file ftp://ftp.example.com/

1. Handling Errors: If the upload fails, ensure:
   • The FTP server is accessible.
   • The login credentials are correct.
   • You have write permissions to the target directory.

Uploading files to an S3 bucket using a presigned URL with curl

Amazon S3 (Simple Storage Service) allows users to upload files securely using presigned URLs. A presigned URL is a temporary, time-limited URL that grants permission to upload a file to a specific S3 bucket without requiring AWS credentials.

This method is useful when you need to allow users or applications to upload files directly to S3 without exposing your access keys.

Step 1: Generate a presigned URL

To get a presigned URL, you can use the AWS CLI or an SDK like Boto3 (Python).

Example using AWS CLI:

aws s3 presign s3://your-bucket-name/your-file-name --expires-in 3600

• your-bucket-name: The S3 bucket where you want to upload the file.
• your-file-name: The name of the file to be uploaded.
• –expires-in 3600: The URL will be valid for 1 hour (3600 seconds).

This will return a presigned URL that you can use to upload the file.

Step 2: Upload the File Using curl

Once you have the presigned URL, use curl to upload the file:

curl -X PUT -T /path/to/your-file -H "Content-Type: application/octet-stream" "<presigned_url>"

Explanation:

-X PUT: Specifies the HTTP PUT method for the upload.

-T /path/to/your-file: Specifies the file you want to upload.

-H “Content-Type: application/octet-stream”: Sets the content type. You can change it based on the file type.

<presigned_url>: Replace this with the actual presigned URL.

Step 3: Verify the Upload

After uploading, verify the file in the S3 bucket via the AWS Console or using the AWS CLI:

aws s3 ls s3://your-bucket-name/

Key benefits of using a presigned URL

✅ Secure – No need to expose AWS credentials.

✅ Time-limited – Access expires automatically after the set duration.

✅ Direct Uploads – Clients can upload files without routing them through your backend.

By using curl with a presigned URL, you can efficiently upload files to S3 while ensuring security and ease of use. 

Uploading a file to Artifactory with curl

Artifactory is a universal artifact repository manager used for storing, managing, and distributing software packages, building artifacts, and binaries. Developers often use Artifactory to store project dependencies and CI/CD pipeline artifacts securely.

With curl, you can easily upload files to Artifactory using its REST API.

To upload a file to Artifactory, use the following command format:

curl -u <username>:<password> -T "<local_file_path>" "<artifactory_url>/artifactory/<repository>/<target_path>/<filename>"

Explanation of the Command:

-u <username>:<password> : Provides Artifactory authentication credentials.

-T “<local_file_path>” : Specifies the file path of the local file to upload.

“<artifactory_url>/artifactory/<repository>/<target_path>/<filename>” : Specifies the Artifactory instance, target repository, and path where the file should be stored.

Example Upload Command

Assume:

Artifactory URL: https://artifactory.example.com

Repository: myrepo

Target Directory: myfolder

Local File: myartifact.jar

Username: myuser

Password: mypassword

The command would be:

curl -u myuser:mypassword -T myartifact.jar "https://artifactory.example.com/artifactory/myrepo/myfolder/myartifact.jar"

Uploading with an API Key Instead of a Password

Instead of using a password, you can use an API key for security reasons:

curl -H "X-JFrog-Art-Api:<your_api_key>" -T myartifact.jar "https://artifactory.example.com/artifactory/myrepo/myfolder/myartifact.jar"

Verifying the Upload

Once the upload is complete, you can verify it:

1. Check Artifactory’s web UI and navigate to the target repository.
2. Use the curl HEAD request to check if the file exists:

curl -I -u myuser:mypassword "https://artifactory.example.com/artifactory/myrepo/myfolder/myartifact.jar"

Is curl the right choice for your file upload needs?

If you need a versatile and efficient way to upload files to a remote server, curl is a powerful option. As a command-line tool and library, curl supports multiple protocols, making it ideal for tasks such as:

• Uploading files to APIs, servers, and cloud storage
• Automating file transfers in scripts and CI/CD pipelines
• Handling authentication securely with API keys or credentials
• Working with web forms and multipart file uploads

Whether you’re managing small-scale file uploads or large-scale automated workflows, curl provides flexibility, reliability, and control over your data transfers. However, if you’re looking for a more user-friendly and scalable solution for handling file uploads without extensive coding, there’s an alternative worth considering.

Simplifying file uploads with Filestack

For developers and businesses that need a hassle-free, scalable, and secure file upload solution, Filestack offers a powerful alternative to manual curl commands.

With Filestack, you get:
✅ A simple API for direct uploads – No need to write complex scripts or manage multiple upload methods.
✅ Automatic handling of file storage & security – Filestack takes care of cloud storage, security, and compliance.
✅ Optimized performance – Support for URL ingestion, CDN acceleration, and mobile device integration.
✅ Advanced file transformations – Resize, compress, and enhance images, videos, and documents on the fly.

If you want a developer-friendly, low-maintenance approach to file uploads that integrates seamlessly into web and mobile applications, Filestack is worth a try.

Get started with Filestack today and experience effortless file uploads!

Read More →