curl and HTTP starters, one request per page
Twenty-five requests for developers and sysadmins who paste curl flags off Stack Overflow and want the grammar: the request as an envelope, methods as verbs, headers as instructions, -d switching to POST, JSON vs form bodies, auth tickets, cookies, the status ladder, redirects with -L, -v as the x-ray, timeouts as fuses, and idempotency, one request per page.
A diagram, the classic trap, and one command to go try this week. That's a page.
curl and HTTP starters, one request per page
Twenty-five requests for developers and sysadmins who paste curl flags off Stack Overflow and want the grammar: the request as an envelope, methods as verbs, headers as instructions, -d switching to POST, JSON vs form bodies, auth tickets, cookies, the status ladder, redirects with -L, -v as the x-ray, timeouts as fuses, and idempotency, one request per page.
Set in Space Grotesk, Inter and JetBrains Mono (SIL Open Font License).
curl behaviour checked against the curl man page (curl.se/docs/manpage.html); HTTP method and status semantics against RFC 9110; the PATCH method against RFC 5789; the OAuth 2.0 bearer token format against RFC 6750. The one practice claim, spaced practice beats cramming, is Cepeda et al. 2006, Psychological Bulletin, a meta-analysis of 317 experiments (PubMed 16719566). Teaching conventions (one rep a day, read the status before the body) are named as conventions. curl is a registered trademark of Daniel Stenberg; this book is an independent guide and is not affiliated with or endorsed by the curl project.
General information only, for practice and reference. Not legal, security, or professional advice; verify commands against your own systems and the current curl documentation before relying on them.
Your purchase is for personal use only. You do not have redistribution rights: please do not share, resell, or republish this book or its pages.
© 2026 Steve Hodgkiss. All rights reserved. Personal use only; no redistribution rights.
Edition 1.0 · stevehodgkiss.net
Contents
The grammar
What a request actually is, the sentence shape of every curl command, and the verbs that carry intent.
- 01The request is an envelope
- 02URL plus flags
- 03Methods are verbs
An HTTP request drawn as an envelope: the request line is the address on the front, headers are the instructions written above it, and the body is what you put inside. Structure per RFC 9110 sections 2 and 3.
The request is an envelope
Let's say you paste curl -L -d name=Sam https://api.example.com off Stack Overflow, it works, and you can't say why. Those flags each write on the same envelope.
Three parts: the request line, GET /users HTTP/1.1, is the address. The headers are the instructions. The body is what's inside. Flags pasted without knowing which zone they write on is how bodies get sent with GET.
Every flag writes on the envelope. Learn the zones first.
Take any curl command you pasted this month and label each flag: request line, header, or body. That's the rep.
The grammar of a curl invocation: the URL names the resource, and options change parts of the envelope. Per the curl man page, options and URLs can be mixed in any order.
URL plus flags
Let's say you think curl has hundreds of commands to memorise. It doesn't. It has one sentence shape and a pile of adverbs.
The URL is the thing. The options edit the envelope around it: -H adds a header, -d adds cargo. Reading the flags without the URL as the anchor makes them noise.
URL first. The flags just edit the envelope.
Write one command today as URL first, then flags. Read it back that way.
HTTP methods as verbs: GET reads, POST submits, PUT replaces, PATCH edits, DELETE removes, HEAD reads only the instructions. Semantics from RFC 9110 section 9.3; PATCH from RFC 5789.
Methods are verbs
Let's say a ticket says the endpoint is POSTed and POST is just the one with -d to you. The verb is the whole intent.
GET reads. POST submits. PUT replaces the whole thing. PATCH sends edits, a patch document per RFC 5789. DELETE removes. HEAD is GET with no body, exactly what -I sends. RFC 9110 section 9.3 defines each. POST for everything, by habit hides what a request does.
GET reads it, PUT replaces it, PATCH edits it.
Read five endpoints of any API as verb sentences: GET what, POST what.
The -d option sends data with the POST method and Content-Type application/x-www-form-urlencoded, exactly like a submitted HTML form, per the curl man page for --data.
-d switches it to POST
Let's say curl -d name=Sam sends POST and you never asked for that. You did.
-d is a body flag and it switches the method to POST, the man page's words, sent like a submitted form, Content-Type x-www-form-urlencoded. Repeat -d and the pieces merge with an ampersand. -X GET on top, which changes the word but keeps the body, page nine's trap.
Body on board means POST. That's the default working.
Send any -d request with -v and confirm the request line flipped to POST on its own.
Reading the answer
The status ladder, a clean code in scripts, what a redirect actually is, following it with -L, and -I versus -i.
- 01The status ladder
- 02-v is the x-ray
Status code families: 1xx informational, 2xx success, 3xx further action needed, 4xx client error, 5xx server error, per RFC 9110 section 15.1.1.
The status ladder
Let's say you check a curl call by whether text came out. The server already answered, in one digit.
First digit is the family: 2xx accepted. 3xx, further action needed. 4xx, you erred. 5xx, the server failed, the classes of RFC 9110 section 15.1.1. 401, show credentials. 403, no. 404, nothing at this address. Bodies before status codes parses an error page as data.
Read the first digit. It's the story in one number.
Make one call fail on purpose today and say the family out loud before reading anything else.
-v as the x-ray: verbose output prefixes lines with markers, right angle bracket for headers sent, left angle bracket for headers received, and star for curl's own notes, per the curl man page.
-v is the x-ray
Let's say a request fails and you're guessing between auth, headers, the URL. Stop guessing, take the x-ray.
-v prints the whole exchange with markers: right bracket, what you sent. Left bracket, what came back. Star, curl's own notes, the man page's legend. Request line, headers, handshake, all visible. Debugging from the body alone picks the symptom over the evidence.
Right bracket, you said. Left bracket, they said.
Run your flakiest request with -v and read it line by line, marker by marker.
The whole grammar in one command: every part of the book assembled into a single curl invocation, each flag annotated with the page that taught it.
The whole book in one command
Let's say you want the one command pinned above your desk. Here it is, and you built every piece.
curl -v -L --max-time 30 -H "Accept: application/json" --oauth2-bearer $TOKEN --json @payload.json https://api.example.com. The x-ray, the chain, the fuse, the ask, the ticket, the cargo. Pasting this without naming each flag's zone is where you started.
One sentence. You can read every word of it.
Write this command from memory once this week. Check it against the book, flag by flag.