Goal
By the end you can ask a web service for information from the terminal, see whether it said yes or no, keep the answer in a file, and pick one field out of it. This guide is about the layer where your shell talks to another computer.
The idea in plain words
A web service is a program on another computer that answers questions sent over the internet. A question is called a request and the reply is a response. Both use a set of rules called HTTP.
A request has an address, called a URL, such as https://api.github.com/zen. The response has two parts that matter to you:
- A status code, a three-digit number that says how it went.
200means success.404means the thing you asked for was not found. Codes that start with4mean your request was wrong, and codes that start with5mean the service had a problem. - A body, the content you asked for. Web services often send it as JSON, a text format made of names and values in curly braces.
A program that lets you send a request from the command line is curl. It prints the body on standard output, so everything you learned about pipes and redirects applies to it.
A web service that is meant for programs, not people with a browser, is called an API. The GitHub API is a good one to practice on: it is public, it is well documented, and reading from it needs no account. Without signing in you get about 60 requests per hour, which is plenty here.
A picture
Read the picture from left to right. Your command goes out as a request, and the answer comes back with a status code and a body.
your shell the web service
---------- ---------------
curl URL -- request ------> reads the URL
works out an answer
status + body <-- response ----- sends it back
the body goes to stdout, so you can pipe it or save it:
curl URL | jq -r .name curl -o answer.json URL
Diagram: on the left is your shell and on the right is the web service. An arrow labelled request goes from the curl command to the service. An arrow labelled response comes back carrying a status code and a body. Below, two lines remind you that the body goes to standard output, so it can be piped into jq or saved into a file with curl dash o.
Another way to see it
Think of ordering at a counter. The URL is what you ask for. The status code is the first thing the person says: "here you go" (200), "we do not have that" (404) or "the kitchen is broken" (500). The body is the food itself.
The table lists the status codes you will meet most.
| Code | Meaning | What to do |
|---|---|---|
| 200 | It worked | Read the body |
| 404 | Not found | Check the address |
| 403 | Refused, often a limit | Wait, or sign in |
| 500 | Service problem | Try again later |
Walk through it
Here is what happens, step by step, when you run curl -s https://api.github.com/repos/octocat/Hello-World | jq -r .full_name.
curlopens a connection toapi.github.comand sends a request for the path/repos/octocat/Hello-World.- The
-soption means silent. Without it, curl prints a progress meter on standard error, which gets in the way when you read the answer. - The service finds the repository and sends back a status of
200and a body of JSON, about a hundred lines long. curlwrites the body on standard output. The pipe|hands it tojq.jq -r .full_namereads the JSON and prints only the fieldfull_name. The-roption prints it as plain text, without quotation marks. You seeoctocat/Hello-World.
If the repository did not exist, step 3 would send the status 404 and a short JSON body that says Not Found. Note that curl itself counts this as a success, because the conversation worked: the service answered. To see the status code, you have to ask for it, as the next section shows.
Try it
You should not need the internet to learn the habits, so these commands ask for a file on your own computer. A URL that starts with file:// tells curl to read a local file instead of calling a service. The rest is the same as for a web address. The block that follows uses $PWD, the folder you are in, to build the address.
Make a small file, then fetch it. The answer is the body, printed on standard output:
printf 'hello\n' > f.txt
curl -s "file://$PWD/f.txt"
You should see this:
hello
Save the answer into a file with -o, and print the number of bytes that arrived with -w. The -w option writes a message after the transfer, and %{size_download} stands for the size:
printf 'hello\n' > f.txt
curl -s -o saved.txt -w '%{size_download}\n' "file://$PWD/f.txt"
cat saved.txt
You should see this:
6
hello
Ask for something that is not there, and look at the exit status. Curl uses exit status 37 when it cannot read a local file. The -s option hides its error message, so the status is the only sign:
curl -s "file://$PWD/missing.txt"
echo "exit status $?"
You should see this:
exit status 37
On the real internet
The commands below call the public GitHub API. The tests for this guide never send them, because a network can be down and a limit can be reached, but they were run by hand on 2026-11-10. Each one only reads.
Ask for a short saying. The answer changes from one request to the next:
curl -s https://api.github.com/zen
Read one field out of a JSON answer:
curl -s https://api.github.com/repos/octocat/Hello-World | jq -r .full_name
You should see this:
octocat/Hello-World
Show only the status line of the response. -I asks for the headers, not the body. The exact words depend on the HTTP version, so it may say HTTP/1.1 200 OK instead:
curl -sI https://api.github.com/repos/octocat/Hello-World | head -n 1
You should see something like this:
HTTP/2 200
Ask for a repository that does not exist, throw the body away with -o /dev/null, and print only the status code:
curl -s -o /dev/null -w '%{http_code}\n' \
https://api.github.com/repos/octocat/nope
You should see this:
404
Look at the body of that same failed request. The service explains the problem in JSON:
curl -s https://api.github.com/repos/octocat/nope | jq -r .message
You should see this:
Not Found
Common confusions
- A finished curl means the request worked. Curl exits with status 0 whenever the service answers, even with
404. Print the status with-w '%{http_code}\n'when it matters. - The
-soption makes curl quiet about errors too. It hides the progress meter and the error messages. When a command fails and you cannot see why, run it again without-s. - A web address in a script is always safe to run. Reading is harmless, but a request can also send data or change something on the service. Run only requests whose purpose you understand, and never paste a command that contains someone else's secret key.
- An API key is just a password for programs. Treat it as one. Do not put it in a guide, a shared note or a command you share.
- The pipe waits for the answer.
curl ... | jq ...shows nothing until the whole answer has arrived. A slow network looks like a hang. - A limit is a bug. Public services allow only so many requests per hour. If you see a
403after many tries, wait before you try again.
Check yourself
- What are the two parts of a response that matter most? Answer: the status code and the body.
- What does the status code
404mean? Answer: the thing you asked for was not found. - Why does
curlexit with status 0 on a404? Answer: the conversation worked and the service answered, so curl counts it as a success. Ask for the status with-w '%{http_code}\n'. - How do you keep an answer in a file? Answer:
curl -s -o answer.json URL, or redirect with>.
Where next
This ends the goal-first guides: you can find a word, count and sort, tidy files, make a backup and ask a web service, and each one uses ideas from the earlier series.
For the details of each command, see explain curl, explain jq and explain cat.
References
Original explanations, with sources for further reading. Words you do not know are in the glossary.