Simple Guide To cURL

Guide To cURL

I was working with the Facebook API the other day and came across a lot of documentation with curl statements.

I occassionally forget my curl, so I decided to write a blog post once and for all to help me when I have those Alzheimers moments (what’s this thing do again), and when I don’t want to read some long documentation on the web or worse, my terminal.

Note: I made a video for this tutorial as well at: How To Use cURL For Web Development on our YouTube channel. Please subscribe

The Basics:

From the terminal

curl <some url>


Allows you to make a REQUEST to any URL you provide. If the URL is configured to give back a RESPONSE, you will see something back.

For example, the JSONPlaceholder site is configured to give back a JSON response at the URL (or endpoint) I gave called /todos/. Here I’m saying I want to curl at the endpoint /todos/1 which I’d expect to give me back a JSON response for 1 todo.

  "userId": 1,
  "id": 1,
  "title": "delectus aut autem",
  "completed": false

Adding options

For me the usage of curl is pretty straightforward. Where I get lost are the options, often called flags. Let’s look at some of the most common ones:

curl -o <localfile> <url>

Here we are saying we want to connect to some url, and download it as a local file on our computer (in the folder we are currently in on our terminal).

For example:

curl -o google.html

This would download a copy of the Google webpage as a file called google.html on our computer.

The -o flag is used to download files especially raw JSON and txt to view more easily in a code editor rather than a terminal.

curl -O <url>

The big O, or -O flag helps us download images, pdfs, zip files. This is useful if you don’t want to go through a browser to download something. You can even wrap this command with a Python or Node.js script and make a multi-link downloader if you wish.

curl -v <url>

Use this flag -v, aka verbose, to get a more detailed picture of what curl is doing exactly every millisecond — from connecting to a remote server, to making a TLS handshake to checking for SSL, to getting your response, and receiving the headers and body. The -v flag is very useful for troubleshooting any errors between your server and the other.

curl -I <url>

-I Gets you back the headers with any response especially if you are trying to see what kind of headers are returning in a server response.

curl -d <your data as a string> <url>

curl -d "{"title":"foo","body":"bar","userId":1}"

Use -d along with some data in a string format to send to a URL in a POST request; used most often to CREATE or UPDATE a record on a server through an API. You can use JSON Placeholder as a demo API and try making a POST request with some fake JSON converted to a string and send it to an endpoint like /users/.

curl -H "MY-HEADER: Some Data" <url>

Use the -H flag to send some HEADERS information (possibly an AUTH token) with your request. Many APIs require you to be authenticated before you can make requests, including Facebook, Google, Twitter, etc. You may also need to request some kind of OAUTH Token after logging in to the API via the headers, and then use the auth token in subsequent requests to make API calls (and the auth token may expire after 90 minutes usually for security).

curl -L <url>
curl -L

Use the -L flag to follow a url with curl in the case it may redirect to some other url; often this is the case with a lot of links on the web. Without the -L flag you might get a response saying that the url you entered was permanently moved (301 error) to somewhere else and “hang up”. With -L it will keep following the redirects until it gets you the final true url and true response. Handy!

Need Even More Reference?

man curl

You can use this command to basically view all the information about curl, or you can also visit Curl Haxx SE to read all the documentation online, as well as download the tool if you need it for your computer. If you are on Windows, you can also download curl (if you don’t have it, by default it comes with Windows 10) at GitSCM. Mac users, rejoice, curl is built in with your terminal.

Happy coding!

Vijay JavaSciptLA, Lead Organizer