Difference Between curl -d and -F Flags

When using curl to send POST requests, the choice between the -d (--data) and -F (--form) flags determines how your data is formatted and transmitted. This article provides a clear comparison of these two flags, explaining their default Content-Type headers, syntax differences, and specific use cases for web development and API testing.

The -d Flag (application/x-www-form-urlencoded)

The -d or --data flag is used to send standard, URL-encoded data to a server. This is the default method for submitting simple HTML text forms.

Content-Type: Sends data as application/x-www-form-urlencoded.
Data Formatting: Keys and values are joined by equals signs (=) and separated by ampersands (&). Spaces and special characters must be URL-encoded (e.g., spaces become %20 or +).
Primary Use Case: Sending simple text-based key-value pairs, JSON payloads, or standard API query parameters in a POST request.

Example:

curl -d "username=john_doe&status=active" https://api.example.com/users

The -F Flag (multipart/form-data)

The -F or --form flag is used to simulate a form submission where binary files, large data sets, or mixed data types are sent.

Content-Type: Sends data as multipart/form-data.
Data Formatting: Each key-value pair is sent as a distinct “part” of the request separated by a unique boundary. This allows different parts to have their own Content-Type (e.g., text/plain alongside image/png).
Primary Use Case: Uploading files, submitting forms with file attachments, or sending large chunks of unencoded binary data.

Example (Uploading a file):

To upload a file, prefix the file path with the @ symbol:

curl -F "username=john_doe" -F "profile_pic=@/path/to/avatar.png" https://api.example.com/upload

Key Differences Summary

Feature	`-d` (`--data`)	`-F` (`--form`)
Default Content-Type	`application/x-www-form-urlencoded`	`multipart/form-data`
Primary Purpose	Sending simple text-based data and API payloads	Uploading files and mixed/binary data
File Handling	Reads file content as a single text string	Uploads file as a binary stream with metadata
Syntax for multiple inputs	Combined in a single string: `key1=val1&key2=val2`	Repeated flags: `-F key1=val1 -F key2=val2`

By default, both flags automatically instruct curl to make an HTTP POST request. Choose -d for standard API requests and login forms, and choose -F whenever file uploads are required.