cURL Command Guide: Basic and Advanced Options with Examples

cURL lets you send requests from your terminal to test APIs, inspect responses, and transfer data. A simple request takes one line. Add query parameters, a JSON body, custom headers, and an apostrophe in your data, however, and assembling that line can become the hardest part of the job.

Our free cURL command line builder gives you fields for the request details and generates the command as you type. It is especially useful when you know what you want to send but do not want to spend your debugging time untangling shell quotes.

This guide covers where cURL is available, practical commands, advanced options, and how the builder helps with everyday API requests.

What can you do with cURL?

The curl command transfers data using URLs. Common uses include checking HTTP headers, calling an API, sending forms, downloading files, and investigating connection problems. Its capabilities extend beyond HTTP to protocols such as FTP, SMTP, and SFTP, depending on the installed build. See the official cURL manual  for supported options and protocols.

Think of a request as four parts: the URL, the method, the headers, and an optional body. The URL identifies the destination; the other parts describe the action and data you want to send. The server decides how to handle them.

Is cURL available on Windows, macOS, and Linux?

Yes. Start by opening a terminal and checking your installation:

curl --version

• Windows: cURL ships with current Windows 10 and Windows 11 installations. Use curl.exe --version in PowerShell to avoid a possible curl alias that invokes a different command. The bundled build can have different capabilities from other distributions. See cURL on Windows .
• macOS: the operating system includes cURL. Its version may differ from an installation managed by another package manager. See the macOS installation notes .
• Linux: install your distribution’s cURL package if it is missing. The official download directory  lists platform packages and other builds.

The examples below use Bash/Zsh-compatible quoting, including in WSL or Git Bash. PowerShell and Windows Command Prompt have different quoting and line-continuation rules; having cURL installed does not make every shell example interchangeable.

Example API paths and filenames are illustrative. Replace them with an endpoint you control or are authorized to use; the sample paths on example.com are not working demo APIs.

Basic cURL options to know

These flags are documented in the cURL option reference . Long names are easier to read; short names save typing. Some options, including --data-raw, have no equivalent short form.

Send a GET request or inspect headers

For a normal HTTP URL, a simple request uses GET:

curl 'https://example.com/'

To request headers without the response body:

curl --head 'https://example.com/'

HEAD is a separate request method, so a server may handle it differently from GET. Use the appropriate endpoint when checking API behavior.

Send a POST request with a JSON body

Here is the kind of command you can generate with the builder:

curl \
  --request 'POST' \
  --url 'https://example.com/api/items' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{"name":"Demo item","quantity":2}'

Content-Type describes the body you send. Accept expresses the response format you want; it does not force the server to return it. The builder keeps the body literal and does not check whether it is valid JSON.

For manual commands, cURL also has a --json shortcut starting in version 7.82.0. It supplies JSON headers and sends the data, but still does not validate the JSON. The builder currently uses explicit headers and --data-raw. See sending JSON with cURL .

Why building a cURL URL and command gets tricky

There are several different formats to get right at once. A URL follows URL syntax, JSON follows JSON syntax, and the terminal shell interprets the command before cURL receives its arguments.

For example, these are different jobs:

1. URL encoding: a space inside a query value may need %20; an ampersand that belongs inside that value needs encoding rather than acting as a parameter separator.
2. Shell quoting: the URL must reach cURL as one argument. An unquoted & has a special meaning in Bash, even when you intended it to be part of the URL.
3. Body quoting: JSON double quotes must survive the shell, and an apostrophe inside a value complicates single-quoted shell text.

The cURL project’s guides explain URL encoding  and quoting option arguments . Quoting a URL does not URL-encode it.

This already-encoded URL is easy to read when quoted:

curl 'https://example.com/search?q=red%20shoes&sort=price'

Now imagine sending this JSON body:

{"name":"O'Reilly","note":"Keep $5 as literal text"}

Wrapping it in ordinary shell single quotes is no longer enough because the name contains an apostrophe. Switching casually to double quotes can introduce a different problem: the shell may interpret dollar signs. The builder handles the required shell escaping for you while preserving the literal input.

That is where a command builder can be a lifesaver: change the method, paste your body, add a header, and copy the assembled command without rebuilding the quoting by hand. You can spend your time checking the API response instead of counting quote characters.

The builder leaves the URL unchanged. It does not validate it, encode query values, or test whether the destination exists. You still supply the correct URL and data for your API.

Build a cURL command without memorizing the syntax

Open the online cURL command builder and follow these steps:

1. Select GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS and enter your URL.
2. Choose a Content-Type if needed. Enable Accept JSON responses when appropriate.
3. Add custom headers as Name: value, one per line. Each name should appear only once, including presets.
4. Paste a body for a method that supports it in the builder. GET and HEAD omit the body while retaining your draft if you switch back.
5. Enable Verbose output when troubleshooting. Use Accept self-signed certificates only for a trusted test environment.
6. Optionally select Short options or Single-line output. Both start off. Copy the result into the appropriate terminal.

The default multiline output targets POSIX shells, including Bash and Zsh. Single-line output requires Bash or Zsh and escapes body line breaks while preserving the body content. It does not silently remove those line breaks.

The tool supports up to 10 custom headers, 8,192 characters of custom-header text, and 65,536 characters of body text, measured in JavaScript string units. It is free to use without an account.

Your request details and generated command stay in your browser. The builder does not send the request or save your input. Running the copied command in your terminal contacts the destination. To inspect the website’s own activity, see our guide to checking website network requests in browser developer tools.

Advanced cURL options for larger tasks

These are capabilities of cURL itself. The current builder does not provide dedicated controls for the advanced examples below; use them when editing commands manually.

Encode query parameters automatically

Use --get with --data-urlencode to build a query from separate values:

curl --get \
  --url 'https://example.com/search' \
  --data-urlencode 'q=red shoes' \
  --data-urlencode 'category=books & magazines'

Here, cURL encodes the values and places them in the URL query. This is different from pasting an already assembled URL into the builder. See converting form data to a GET query .

Follow redirects and handle HTTP failures

--location follows redirects. --fail-with-body makes HTTP error responses produce a failing exit status while keeping their body, which helps scripts detect a failed download or API call:

curl --location --fail-with-body \
  --output 'report.json' \
  'https://example.com/api/report'

Choose a new output filename if you need to preserve an existing file. Check redirect behavior carefully when adapting a POST command: the redirect status and method options affect the next request. See redirect handling  and HTTP responses and failures .

Set timeouts and retry temporary failures

curl --connect-timeout 5 --max-time 20 --retry 2 \
  'https://example.com/api/status'

The connection timeout limits connection setup; the maximum time limits each transfer attempt. Retries can make the whole command take longer than 20 seconds. Not every error is retried, and repeating a request that changes data may repeat an operation. See the guides to timeouts  and retries .

Upload a file with multipart form data

curl --form 'description=Quarterly report' \
  --form 'file=@report.pdf' \
  'https://example.com/api/uploads'

In this form argument, @report.pdf tells cURL to read a local file when the command runs. This differs from the builder’s literal --data-raw body. Let cURL construct the multipart Content-Type and boundary. See multipart form uploads .

Authenticate and configure certificate trust

For HTTP Basic authentication, curl --user 'demo' 'https://example.com/private' prompts for the password instead of putting it in the command. Other APIs use tokens in headers; follow the API’s documentation. The builder already accepts a custom Authorization header, but does not manage credentials. See HTTP authentication .

For a development certificate, --cacert can specify a trusted CA certificate file. The builder’s Accept self-signed certificates option instead adds --insecure, which disables certificate and hostname verification. It is not a certificate installation or a general fix for HTTPS problems. See cURL certificate verification .

Frequently asked questions

Why does my cURL command work in one terminal but not another?

Check both the installed cURL version and the shell. Bash, Zsh, PowerShell, and Command Prompt do not interpret every quote or line break the same way. Use the shell format identified by the builder and inspect curl --version when an option is unavailable.

Does the builder send my API request?

No. It generates command text locally. You decide when and where to run it. A command containing credentials can still be saved in terminal history or exposed when shared, and verbose output can include sensitive headers. Review both before posting them in a ticket.

Can I use the builder for advanced cURL commands?

Use it to assemble the supported method, URL, headers, and body, then adapt the copied command for additional cURL capabilities. Dedicated controls for imports, file uploads, retries, and saved request projects are not currently available.

Ready to put the examples into practice? Build your cURL command and keep the method, headers, body, and shell quoting in one place.