curl Command Builder

How to build a curl command

A curl command is the program name, the options, and the URL: curl -X POST -H 'Content-Type: application/json' --data-raw '{"name":"Ada"}' https://api.example.com/users sends a POST with a JSON body. The hard part is not the options but the quoting, because the shell reads the command before curl does, and bash, PowerShell and cmd each treat quotes, $, % and & differently.

This builder first works out the exact arguments curl must receive, then quotes them for the shell you choose, so a value containing an apostrophe, a dollar sign or a line break arrives unchanged. The bash, Windows PowerShell 5.1 and cmd output is tested by running it against a local server and checking that the method, headers, query and body arrive byte for byte.

The options it writes

Some choices avoid curl's own surprises. --data-raw is used instead of -d, because -d @file reads a file and a body that starts with @ would do the same. --form-string is used for text fields because -F treats @, < and ;type= in the value specially. A URL containing [ or { gets -g, since curl otherwise reads them as a range pattern.

Quoting in each shell

• bash and zsh: everything goes in single quotes, where nothing is special; a single quote inside is written '\''.
• PowerShell 7.3 and later: single quotes with '' for a quote. The program is curl.exe, because in Windows PowerShell curl is an alias for Invoke-WebRequest.
• Windows PowerShell 5.1: it passes quotes inside arguments to native programs without escaping them, so they are escaped for it: \", or "" inside a quoted value. Use the 7.3 tab in PowerShell 7.
• cmd: values go in double quotes; a value with " or % has every special character escaped with ^ so %PATH% is not expanded. cmd cannot pass a line break inside an argument, so a multi-line body is read from a file.

Worked examples

# JSON API call with a token, following redirects and failing on HTTP errors
curl -H 'Authorization: Bearer YOUR_TOKEN' -H 'Content-Type: application/json' \
  --data-raw '{"app":"storefront","branch":"main"}' -L --fail https://api.example.com/v1/deployments

# Upload a file with a description
curl --form-string 'description=Nightly build' -F 'file=@./build.log;type=text/plain' https://api.example.com/upload

# Check that a site answers, headers only
curl -I https://example.com

Common errors

• curl: (3) URL rejected: Bad hostname: an argument split at a space, so part of a header or body was read as a URL. The quoting was wrong for the shell; copy the command for the shell you are in.
• 415 Unsupported Media Type: the JSON body went without Content-Type: application/json; -d alone sends application/x-www-form-urlencoded.
• SSL certificate problem: fix the certificate rather than adding -k, which turns off the check for everything, including whoever is in the middle.
• In PowerShell, "A parameter cannot be found that matches parameter name 'X'": curl ran Invoke-WebRequest. Type curl.exe.

Checking a deploy with curl

Shipown checks the process and the port after each deploy, and says plainly that a running process is not proof the public URL works (build output and deployment status). curl -I https://your-domain from your own machine is that proof: the status line, the redirect to HTTPS and the security headers in one request.