curl Form Builder

curl forms in depth: urlencoded, multipart, JSON, and the flags around them

curl ("Client URL") was released in 1996 by the Swedish developer Daniel Stenberg, and has grown into the Swiss Army knife of network clients. It speaks HTTP/1.1, HTTP/2, HTTP/3-over-QUIC, plus FTP, SFTP, SMTP, IMAP, POP3, LDAP, MQTT, WebSocket, and a long tail of niche protocols. Its libcurl backbone powers everything from Git to video games to satellites. This generator builds the most common HTTP-form invocations; the sections below cover the encodings, the most useful flags, and the traps when you copy a command from Postman into a shell.

When you submit an HTML form, the browser chooses one of three content types based on <form enctype="...">. curl mirrors that choice with three different flags — get this wrong and the server either rejects the request or silently parses nothing.

The three form encodings

• application/x-www-form-urlencoded — the HTML default. Sent with -d 'name=John&age=30'. Values are percent-encoded; & separates pairs. Good for small text-only payloads.
• multipart/form-data — sent with -F 'caption=foo' -F '[email protected]'. Each field is its own MIME part, so you can mix text fields with file uploads. The @ tells curl to read from disk; type= sets the part's content-type (-F '[email protected];type=text/csv').
• application/json — not a form encoding per se, but the modern API default. Use -H 'Content-Type: application/json' -d '{"name":"John"}', or the convenience flag --json '{"name":"John"}' (curl 7.82+) which also sets Accept.

# urlencoded POST
curl -X POST -d 'name=John&age=30' https://api.example.com/users

# multipart with one file and one text field
curl -F 'caption=Holiday' -F '[email protected]' https://api.example.com/photos

# JSON body, modern shortcut
curl --json '{"name":"John","age":30}' https://api.example.com/users

The flags you reach for most

• -X METHOD — override the request method. POST is implicit when you pass -d or -F; for PUT, PATCH, DELETE you need it explicitly.
• -H 'Header: value' — add a header. Pass multiple -H flags to add more. To remove a default header, use -H 'Header:' (empty value).
• -d 'k=v' — request body, sets Content-Type to urlencoded by default. --data-urlencode 'msg=hello world' percent-encodes the value for you.
• -G — promote --data values into the URL query string and turn the request into a GET.
• -u user:pass — Basic authentication. For Bearer tokens use -H "Authorization: Bearer $TOKEN" instead.
• -b cookies.txt / -c cookies.txt — read / write the cookie jar. Combine them across calls to keep a session.
• -L — follow redirects (off by default; required for OAuth dances).
• -k / --insecure — skip TLS verification. Useful in dev with self-signed certs, dangerous in prod.
• -o file / -O — save body to file (named or remote-named); -w '%{http_code}\n' prints templated info; -s silences progress; -i prints headers; -I sends HEAD.
• -v, --trace-ascii out.txt — verbose / full trace for debugging.
• --http2, --http3 — force protocol version.

Uploads, auth, and binary data

For raw uploads (S3 pre-signed PUTs, WebDAV) use -T file, which sends a PUT. To pipe stdin as the body, --upload-file - or --data-binary @-. The difference between -d @file and --data-binary @file is subtle but critical: -d strips carriage returns and newlines (the urlencoded convention), --data-binary keeps the file byte-exact. For JSON or binary payloads, always use --data-binary or --json.

# Bearer token call
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/me

# Pre-signed S3 PUT
curl -T big.zip "https://bucket.s3.amazonaws.com/big.zip?X-Amz-Signature=..."

# JSON from a file, byte-exact
curl -X POST -H 'Content-Type: application/json' \
     --data-binary @payload.json https://api.example.com/ingest

Shell quoting and copy-from-Postman traps

• Single vs double quotes. Single quotes are literal: use them around JSON bodies. Double quotes expand variables ($TOKEN) — handy, but the dollar sign and backticks must be escaped if you want them literal.
• Ampersands in urlencoded data. Bare & on the command line means "run in background". Quote the whole value: -d 'name=John&age=30'.
• Newlines in JSON. Use $'...' ANSI-C quoting if you need literal newlines, or feed the body via --data-binary @file.
• Multi-line readability. End each line with a backslash to break a long command across lines. Keep flags grouped logically — verb, headers, body, URL.
• Generated commands. Postman, Insomnia, Bruno, and even Chrome DevTools ("Copy as cURL") emit ready-to-paste curl commands. They tend to include redundant headers — strip User-Agent and Accept-Encoding if they get in the way.

FAQ

How do I debug a 4xx response? Start with -v to see request and response headers. For wire-level detail use --trace-ascii trace.txt. Add -w '\n%{http_code} %{time_total}s\n' to print status and timing without parsing verbose output.

Does curl support WebSockets? Yes, since curl 7.86 (2022). Use --upgrade Upgrade machinery or the dedicated ws:// / wss:// URLs. For full-duplex interactive sessions websocat is still friendlier.

Can curl record traffic as HAR? Not natively. Use --trace-ascii for a text trace, or run requests through a proxy like mitmproxy or Charles which produce real HAR files with timing breakdowns.

How do I send a binary file as the entire body? Use --data-binary @file.bin for POST or -T file.bin for PUT. Avoid -d @file.bin — it strips CR/LF bytes.

How do I keep a session across calls? Use the cookie jar: curl -c cookies.txt -d 'user=x&pass=y' .../login, then curl -b cookies.txt .../profile. For token-based APIs, store the token in a variable and pass it with -H "Authorization: Bearer $TOKEN" on each call.