Curl POST Request Command Line Syntax

The basic curl command-line syntax for a POST request is curl -X POST [options] URL, with -d "key=value" (or --data) sending form data in the body. For example, curl -d "name=John&age=30" https://example.com/api/users sends a standard URL-encoded POST. This article explains the full syntax, common variations, and practical examples you can adapt immediately.

How curl Handles POST Requests

When you run curl without any data options, it performs a GET request. Adding -d or --data automatically switches the method to POST and sets the Content-Type: application/x-www-form-urlencoded header. The -X POST flag is often redundant if you use -d, but it’s useful when you want to force POST with no body (e.g., curl -X POST https://api.example.com/start).

The general structure is:

curl [options] URL

Options can be combined, and the URL can be quoted if it contains special characters. The order of options and the URL doesn’t matter, but the URL must be the last argument if you’re using -d with a file (see below).

Common POST Data Formats

Depending on what the server expects, you’ll use different -d variants:

• URL-encoded form: curl -d "key1=value1&key2=value2" URL – the default, sends application/x-www-form-urlencoded.
• JSON: curl -d '{"key":"value"}' -H "Content-Type: application/json" URL – you must set the header manually, otherwise the server may reject it.
• Raw text: curl -d "plain text" URL – sends the text as-is, with the default form content type unless you override it.
• File contents: curl -d @file.txt URL – reads the file and sends its contents as the body. The @ prefix is critical.
• Multiple -d flags: curl -d "a=1" -d "b=2" URL – curl concatenates them with & automatically.

For JSON, it’s common to use -H "Content-Type: application/json". Without it, many APIs return an error like 415 Unsupported Media Type.

Key Options for POST Requests

Beyond -d, these options are frequently used:

• -X, --request – specify the HTTP method (e.g., -X POST, -X PUT).
• -H, --header – add or override a header. Use multiple times for multiple headers.
• -i, --include – include the HTTP response headers in the output.
• -v, --verbose – show detailed request/response info, useful for debugging.
• -u, --user – send Basic Auth credentials (user:password).
• -b, --cookie – send cookies from a file or string.
• -c, --cookie-jar – save cookies received from the server to a file.
• -o, --output – write the response to a file instead of stdout.
• -w, --write-out – print custom information after the transfer (e.g., -w "%{http_code}").

Practical Examples

Here are realistic scenarios:

1. Login form: curl -d "username=alice&password=secret" https://example.com/login
2. JSON API: curl -X POST -H "Content-Type: application/json" -d '{"title":"Hello"}' https://jsonplaceholder.typicode.com/posts
3. File upload: curl -F "file=@photo.jpg" https://example.com/upload – the -F flag sends a multipart form, which is different from -d.
4. With authentication: curl -u admin:password -d "action=delete" https://example.com/admin
5. Show only the HTTP status: curl -o /dev/null -w "%{http_code}" -d "" https://example.com/check

Notice the -F example: for file uploads, you must use -F (or --form) to send a multipart/form-data request. Using -d won’t work for files.

Common Pitfalls and Misconceptions

Several mistakes trip up beginners:

• Forgetting the @ for files: curl -d @file.txt reads the file; curl -d "file.txt" sends the literal string “file.txtâ€�.
• Not setting the Content-Type for JSON: Many APIs reject JSON without the correct header. Always include -H "Content-Type: application/json" when sending JSON.
• Using -X POST with -d unnecessarily: It’s not wrong, but it can override the method for redirects. When you use -d, curl already uses POST.
• Quoting issues: The shell interprets spaces and special characters. Always quote your data: curl -d "name=John Doe" works, but curl -d name=John Doe will break.
• Believing -d sends JSON by default: It doesn’t. It sends URL-encoded data unless you override the header.

Alternatives and Related Tools

If curl isn’t available or you need a GUI, consider:

• wget: Can send POST with --post-data="key=value" or --post-file=file, but it’s less flexible for headers and debugging.
• HTTPie: A modern CLI client with simpler syntax: http POST https://example.com name=John (it automatically sets JSON).
• Postman: A graphical tool for building and testing requests, great for exploration.
• Programming languages: Python’s requests library or JavaScript’s fetch are better for scripting complex logic.

For quick tests, curl is usually the fastest because it’s preinstalled on most systems (Linux, macOS, and Windows 10+).

Frequently Asked Questions

How do I send a POST request with a JSON body?

Use curl -X POST -H "Content-Type: application/json" -d '{"key":"value"}' URL. The single quotes around the JSON prevent the shell from interpreting the double quotes. If you’re on Windows Command Prompt, use double quotes and escape the inner ones: "{\"key\":\"value\"}".

What’s the difference between -d and -F?

-d sends data as application/x-www-form-urlencoded, which is simple key-value pairs. -F sends multipart/form-data, which is required for file uploads and can also include text fields. For example, curl -F "username=alice" -F "avatar=@photo.jpg" URL.

Why does my POST request return an error when I use -X POST without -d?

Some servers expect a body, even if empty. Use -d "" to send an empty body. Also, -X POST forces the method, but if the server expects a specific Content-Type, you may need to add -H "Content-Type: application/x-www-form-urlencoded" or another type.

How can I see the request that curl sends?

Use -v or --verbose. It prints the request headers, the request body (if small), and the response headers. For a cleaner output, use --trace-ascii - to see the full data flow.

Can I send a POST request with a file as the body without multipart?

Yes, use curl -d @file.txt URL to send the file’s contents as the raw body. The Content-Type will be application/x-www-form-urlencoded unless you override it with -H. For raw binary data, you might want --data-binary @file.bin.

How do I handle cookies in a POST request?

Use -b cookies.txt to send cookies from a file, and -c cookies.txt to save cookies received from the server. For example, first login with curl -c cookies.txt -d "user=alice&pass=secret" URL, then use curl -b cookies.txt URL for subsequent requests.

Related

• Convert Play FLAC in iTunes: Full Guide
• Soda Foundation Charter: What It Means
• Convert Table to Text in Word: Step-by-Step Guide