What is the curl command?

curl is one of those programs that feels like its always been there for you in a pinch, like when you're trying to debug what your API is doing, and yet we never take the time to actually learn how to use it (I only ever used it via "copy as curl" from my browser's devtools).

It's insanely powerful too, run curl --help all to see what I mean.

In this article, we're going to take the time to learn what we can do with a tiny subset of curl's options, so we don't have to look them up every time.

Table of contents

• What is curl?
• curl examples
  • How to make a curl request
  • Make a POST request with curl
  • How to POST custom headers with curl
  • How to POST JSON data with curl

What is curl?

curl is an open-source program that lets you transfer data to, or from a server, using URLs. If you've used it before, chances are you were just checking if an API was responding with the data you expected it to - but it supports a lot more than just HTTP.

Excerpt from man curl:

curl is a tool for transferring data from or to a server using URLs. It supports these protocols: DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, POP3, POP3S, RTMP, RTMPS, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS.

That being said, in this article we're just going to learn how to use curl with HTTP, because that's already a challenge.

curl examples

Here are some examples of how to make requests with curl.

We'll be using https://echo.onlineornot.com - an API that returns your request data back to you (useful for verifying your curl command does what you expect).

How to make a curl request

At its simplest, you can give curl any URL, and it will show you what's at that URL via a GET request:

curl https://echo.onlineornot.com

and you get a response:

{
  "method": "GET",
  "pathname": "/",
  "searchParams": {},
  "headers": {
    "accept": "*/*",
    "accept-encoding": "gzip, br",
    "connection": "Keep-Alive",
    "host": "echo.onlineornot.com",
    "user-agent": "curl/8.7.1"
  },
  "body": "",
  "powered-by": "https://onlineornot.com"
}

As I mentioned earlier, if you don't specify the HTTP method you want to use, by default curl will send a GET request. If you want to send a POST request, you'll need to provide an additional flag, as shown below.

Make a POST request with curl

You can specify the HTTP method using the -X flag, like so:

curl -X POST https://echo.onlineornot.com

Which gives us:

{
  "method": "POST",
  "pathname": "/",
  "searchParams": {},
  "headers": {
    "accept": "*/*",
    "accept-encoding": "gzip, br",
    "connection": "Keep-Alive",
    "host": "echo.onlineornot.com",
    "user-agent": "curl/8.7.1"
  },
  "body": "",
  "powered-by": "https://onlineornot.com"
}

POST requests are cool and all, but they're not much use to the APIs you're using if you can't authenticate, or tell the API which format the data you're sending it is in.

How to POST custom headers with curl

You can provide headers to the curl command using the -H or --header flag, like so:

# we've used the backslash (\) below to split
# the command across multiple lines
curl -H 'Content-Type: application/json' \
      -X POST https://echo.onlineornot.com

Which returns:

{
  "method": "POST",
  "pathname": "/",
  "searchParams": {},
  "headers": {
    "accept": "*/*",
    "accept-encoding": "gzip, br",
    "connection": "Keep-Alive",
    "content-type": "application/json",
    "host": "echo.onlineornot.com",
    "user-agent": "curl/8.7.1"
  },
  "body": "",
  "powered-by": "https://onlineornot.com"
}

To add multiple headers, you'll need to add additional -H flags, like so:

curl -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer asdfasdf' \
      -X POST https://echo.onlineornot.com

Now that we've provided an Authorization header and a Content-Type header, we can send data to most APIs (that support JSON data, anyway).

How to POST JSON data with curl

In case you're wondering:

but when would I send data TO an API?

You would typically send data to an API when creating or updating records.

You can send data with your request using the -d or --data flag, like so:

curl -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer asdfasdf' \
      -d '{"name": "My website", "url": "https://onlineornot.com"}' \
      -X POST https://echo.onlineornot.com

which returns:

{
  "method": "POST",
  "pathname": "/",
  "searchParams": {},
  "headers": {
    "accept": "*/*",
    "accept-encoding": "gzip, br",
    "authorization": "Bearer asdfasdf",
    "connection": "Keep-Alive",
    "content-length": "56",
    "content-type": "application/json",
    "host": "echo.onlineornot.com",
    "user-agent": "curl/8.7.1"
  },
  "body": "{\"name\": \"My website\", \"url\": \"https://onlineornot.com\"}",
  "powered-by": "https://onlineornot.com"
}