Curl Command Builder

What is cURL and Why Build Commands Visually?

cURL (Client URL) is the most widely used command-line tool for transferring data with URLs. It supports dozens of protocols including HTTP, HTTPS, FTP, and SMTP, but its primary use in modern development is constructing and testing HTTP requests against APIs. The curl command ships pre-installed on macOS, most Linux distributions, and Windows 10+, making it a universal tool for developers, DevOps engineers, and system administrators who need to interact with web services directly from the terminal.

While curl is powerful, its flag syntax can be verbose and error-prone — especially when combining multiple headers, authentication tokens, request bodies, and query parameters into a single command. A visual curl builder eliminates syntax mistakes by generating correct commands from structured form inputs, letting you focus on the request logic rather than remembering whether the header flag is -H or --header, or whether the data flag needs quotes around JSON payloads.

HTTP Methods and the -X Flag

Every HTTP request has a method (also called a verb) that indicates the intended action. curl defaults to GET when no method is specified. To use a different method, pass the -X (or --request) flag followed by the method name in uppercase:

• -X GET — Retrieve a resource (default, the flag can be omitted)
• -X POST — Create a new resource or submit data
• -X PUT — Replace an existing resource entirely
• -X PATCH — Apply partial modifications to a resource
• -X DELETE — Remove a resource
• -X HEAD — Retrieve headers only, no response body
• -X OPTIONS — Query supported methods for a resource (used in CORS preflight)

Note that when you include a -d (data) flag, curl automatically switches to POST without needing an explicit -X POST. However, specifying the method explicitly is considered best practice for readability, especially when sharing commands with teammates or storing them in documentation.

Header Construction with -H

HTTP headers carry metadata about the request — content type, authorization credentials, caching directives, and custom application-specific values. In curl, each header is passed using the -H (or --header) flag followed by the header in "Name: Value" format. Multiple headers require multiple -H flags:

Common headers you will set in most API requests include:

• -H "Content-Type: application/json" — Tells the server the body is JSON
• -H "Authorization: Bearer <token>" — Passes an OAuth2 or JWT access token
• -H "Accept: application/json" — Requests JSON response format
• -H "X-Request-ID: abc123" — Sends a custom correlation ID for tracing
• -H "Cache-Control: no-cache" — Bypasses cached responses

To remove a header that curl adds by default (such as the User-Agent header), pass an empty value: -H "User-Agent:". This technique is useful when testing how servers respond to requests missing certain headers.

Sending Request Bodies with -d and --data-raw

For POST, PUT, and PATCH requests, you typically need to send a request body. curl provides several data flags depending on how the payload should be processed:

• -d '{"key":"value"}' — Sends data as the request body (URL-encodes by default for form data)
• --data-raw '{"key":"value"}' — Sends data without any processing (preserves special characters like @)
• --data-binary @file.bin — Sends a binary file as the body
• -F "file=@photo.png" — Sends multipart form data (file uploads)

When sending JSON payloads, always pair the data flag with a Content-Type header: -H "Content-Type: application/json" -d '{"name":"Alice","role":"admin"}'. Without the Content-Type header, many servers will reject the request or interpret the body as URL-encoded form data, leading to subtle parsing bugs that are difficult to diagnose.

For large payloads, reference a file instead of inlining the JSON: -d @payload.json. The @ prefix tells curl to read the file content and use it as the request body, keeping your command concise and your JSON properly formatted in a separate file that your editor can validate.

Authentication Options

curl supports multiple authentication schemes out of the box. The most common in modern API development are:

• -H "Authorization: Bearer <token>" — Token-based auth (OAuth2, JWT)
• -u username:password — HTTP Basic Authentication (base64-encoded credentials)
• --oauth2-bearer <token> — Shorthand for Bearer token (curl 7.73+)
• -H "X-API-Key: <key>" — API key authentication via custom header

The -u flag is convenient for quick testing but sends credentials in base64 — always use HTTPS to prevent interception. For production scripts, prefer environment variables: -H "Authorization: Bearer $API_TOKEN" so secrets are never hardcoded in commands stored in shell history or shared documentation.

Useful Flags for Debugging and Development

Beyond the core request flags, curl offers several options that make debugging API interactions significantly easier:

• -v (verbose) — Shows the full request/response exchange including TLS handshake and headers
• -s (silent) — Suppresses the progress meter, useful in scripts
• -o file.json — Writes response body to a file instead of stdout
• -w "%{http_code}" — Prints specific response metadata (status code, timing)
• -L — Follows HTTP redirects automatically (3xx responses)
• -k — Skips TLS certificate verification (development only, never in production)
• --connect-timeout 5 — Fails if connection is not established within 5 seconds
• --max-time 30 — Limits total request time to 30 seconds

Combining these flags lets you build robust API testing scripts. For example, a health check script might use curl -s -o /dev/null -w "%{http_code}" --max-time 5 to silently check whether an endpoint returns a 200 status within the timeout period.

Code Examples

Complete POST request with JSON body and authentication

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Accept: application/json" \
  -d '{
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "role": "developer"
  }'

Output:

{
  "id": "usr_abc123",
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "role": "developer",
  "created_at": "2024-01-15T10:30:00Z"
}

GET request with query parameters and verbose output

curl -X GET "https://api.example.com/users?page=2&limit=10" \
  -H "Accept: application/json" \
  -H "X-Request-ID: req-$(date +%s)" \
  -v

File upload with multipart form data

curl -X POST https://api.example.com/upload \
  -H "Authorization: Bearer $API_TOKEN" \
  -F "document=@report.pdf" \
  -F "description=Monthly report" \
  -F "tags=finance,quarterly"