cURL by Example: Form Data
Submit HTML forms. This sample demonstrates how to send data using the `application/x-www-form-urlencoded` content type, which is the standard method for submitting simple web forms.
Code
# Standard POST (application/x-www-form-urlencoded)
curl -d "username=admin&password=secret" https://example.com/login
# Separate fields (cleaner syntax)
curl -d "username=admin" \
-d "password=secret" \
https://example.com/login
# Multipart form data (multipart/form-data)
# Used when forms include file uploads or binary data
curl -F "username=admin" \
-F "password=secret" \
https://example.com/loginExplanation
Form data submission comes in two primary formats, each with distinct use cases. The application/x-www-form-urlencoded content type is the default for simple HTML form submissions. When you use the -d flag, cURL automatically sets this Content-Type (unless you override it). Data is sent as a single block in the HTTP message body with key-value pairs separated by ampersands (&) and keys separated from values by equals signs (=), for example: param1=value1¶m2=value2. Non-alphanumeric characters are URL-encoded (spaces become + or %20, and other special characters are represented as %HH). You can pass the entire query string as one argument, or use multiple -d flags which cURL will automatically concatenate with ampersands. This format is suitable for sending short, simple text data, but becomes inefficient for large quantities of binary data or text with many non-ASCII characters because URL-encoding significantly increases payload size.
For more complex forms, especially those involving file uploads, binary data, or mixed content, you should use the -F flag (or --form), which switches the content type to multipart/form-data. This format was specifically designed for form submissions that include files. The data is broken down into separate "parts," each representing a form field, separated by a unique boundary string that cURL automatically generates. Each part can have its own headers including Content-Type and Content-Disposition, making it much more flexible than URL-encoded format. The multipart format is more efficient for binary data because it avoids the payload size increase associated with URL-encoding—binary content is sent directly rather than being encoded. Each -F flag represents a separate field in the multipart form.
Using -F for multipart encoding is essential when you need to upload files (which isn't directly supported by application/x-www-form-urlencoded without base64 encoding), send large or complex data with non-ASCII characters, or work with APIs that specifically require multipart/form-data format. The choice between -d and -F fundamentally changes how your data is structured and transmitted, so understanding when to use each is crucial for successful API interactions and form submissions.
Code Breakdown
-d sends data as x-www-form-urlencoded by default.-F sends data as multipart/form-data.