Boneyard Tools

Anatomy of a curl command

Break down a curl request into method, headers, body flags and the URL, and learn which flag to reach for in common API calls.

Open the curl Command Builder →

The parts of a curl command

A curl invocation reads left to right as a list of options followed by the target URL. The method comes from -X, each header rides on its own -H flag, the request body follows a data flag such as --data, and switches like -L or --compressed tune the transfer. Because the URL is the one positional argument, it is conventionally placed last, though curl accepts it anywhere. Reading a command in this order makes even a long one-liner easy to understand.

Choosing the right data flag

curl has several ways to send a body and they are not interchangeable. --data sends the string as is and is the natural choice for JSON, where you have already serialized the payload. --data-urlencode asks curl to percent-encode the value, which is what you want for classic HTML form fields that may contain spaces or symbols. There is also --data-binary for sending a file or bytes untouched. This builder uses --data for Raw and JSON and --data-urlencode for Form, matching the Content-Type it sets.

Why Content-Type matters

A body without a matching Content-Type header often confuses the server, which may try to guess the format or reject the request. That is why the builder adds application/json for a JSON body and application/x-www-form-urlencoded for a form body. If your API expects something unusual, such as text/csv or a vendor media type, add a Content-Type header yourself and the builder will respect it instead of overriding your choice.

Quoting keeps the shell out of your data

Shells treat spaces, quotes, dollar signs and other characters specially, so an unquoted body can be split into arguments or partly evaluated before curl ever sees it. Wrapping every value in single quotes stops that, because a POSIX shell passes single-quoted text through verbatim. The only tricky character is a single quote inside the value, which cannot appear literally between single quotes; the builder handles it by closing the quote, inserting an escaped quote, and reopening, so your data arrives exactly as typed.

Frequently asked questions

Will this command work in Windows PowerShell?

The quoting is tuned for POSIX shells like bash and zsh, which macOS and Linux use. PowerShell handles quotes differently and also aliases curl to Invoke-WebRequest, so run the command in a bash-compatible shell or call curl.exe directly.

How do I send a bearer token?

Add a header named Authorization with the value Bearer followed by your token, for example Bearer t0ken. The builder emits -H 'Authorization: Bearer t0ken', which is the standard way APIs read credentials.

Can I save the response to a file?

The builder focuses on the request itself, so it does not add output flags. After copying, append -o filename to write the body to a file, or -O to keep the remote filename.