Curl POST Form Example — URL-Encoded and Multipart

Q: How do I submit a form with curl?

Send each field with -d "name=value" for a normal URL-encoded form, or with -F "name=value" if the form uses multipart/form-data.

Q: What is the difference between curl -d and -F?

-d sends application/x-www-form-urlencoded data in a single encoded string. -F sends multipart/form-data, with each field as its own part, which is required for file uploads.

Q: How do I URL-encode form data in curl?

Use --data-urlencode "name=value" instead of -d. Curl percent-encodes the value so characters such as spaces, ampersands and plus signs arrive intact.

The command

curl -d "email=ada@example.com" -d "plan=starter" https://httpbin.org/post

Opens the request console with this request filled in. It is sent from api-tester.com's server rather than from your machine, so it shows what the endpoint returns, not how your own network or curl build behaves.

What the flags do

Flag	What it does
`-d name=value`	One URL-encoded field. Repeat it; curl joins the pieces with `&`.
`--data-urlencode name=value`	Like `-d`, but curl percent-encodes the value for you.
`-F name=value`	One part of a `multipart/form-data` body.
`-F name=@path`	A file part, as a file input would send.

URL-encoded forms

A form with no enctype attribute posts application/x-www-form-urlencoded: name=value pairs joined with ampersands, with special characters percent-encoded. Plain -d does not encode anything, so a value containing &, =, + or a space is misread by the server. Use --data-urlencode for any value you did not write yourself.

curl https://httpbin.org/post \
  --data-urlencode "name=Ada Lovelace" \
  --data-urlencode "note=maths & engines" \
  --data-urlencode "email=ada+test@example.com"

Multipart forms

A form with enctype="multipart/form-data", which every form with a file input must have, sends each field as a separate part divided by a boundary string. That is -F. Curl generates the boundary and writes it into the Content-Type header, which is why you must never set that header by hand on a -F request: your version would lack the boundary and the server could not split the body.

curl https://httpbin.org/post \
  -F "name=Ada Lovelace" \
  -F "avatar=@photo.png" \
  -F "bio=<bio.txt"          # < sends the file's text as a normal field

Common mistakes

Mixing -d and -F is an error. A request has one body and one encoding.
Logging in to a website this way usually also needs cookies and a CSRF token taken from the page that served the form.
In -F, a value starting with @ or < is read as a file. Use --form-string to send such a value literally.

Related curl examples

Curl POST File Example

There are three different things people mean by "post a file", and they are three different requests.

Curl POST Example

Curl switches to POST the moment you give it a body.

Curl -d Flag Example

-d looks like "send this data", but it does three things at once and quietly edits file input.

Curl Send Cookies Example

Curl ignores cookies unless told otherwise.

Twilio Webhook Example

A form-encoded POST in the wild, signed over its URL and parameters.

Stripe API Tester

A real API that takes form-encoded bodies, with a console to try one.

All Curl Examples

49 worked examples, grouped by what you are trying to do.

More under Request bodies

References

curl man page: -F — Building a multipart/form-data body.
curl man page: --data-urlencode — URL-encoding a form value before sending it.

These links leave api-tester.com, which is independent of the projects they point to.

FAQ

How do I submit a form with curl?

Send each field with -d "name=value" for a normal URL-encoded form, or with -F "name=value" if the form uses multipart/form-data.

What is the difference between curl -d and -F?

-d sends application/x-www-form-urlencoded data in a single encoded string. -F sends multipart/form-data, with each field as its own part, which is required for file uploads.

How do I URL-encode form data in curl?

Use --data-urlencode "name=value" instead of -d. Curl percent-encodes the value so characters such as spaces, ampersands and plus signs arrive intact.