Skip to main content
Hashnodei_codefullstack

Command Palette

Search for a command to run...

Beginner's Guide to Using Curl

Updated
•6 min read
A
arnab samanta

What is Curl ?

cURL, which stands for client URL, is a command line tool that developers use to transfer data to and from a server. At the most fundamental, cURL lets you talk to a server by specifying the location (in the form of a URL) and the data you want to send. cURL supports several different protocols, including HTTP and HTTPS, and runs on almost every platform. This makes cURL ideal for testing communication from almost any device (as long as it has a command line and network connectivity) from a local server to most edge devices.

The most basic command in curl is curl http://example.com. The curl command is followed by the URL, from which we would like to retrieve some kind of data. In this case, it would return the html source for example.com.

Underlying the curl command is the libcurl development library, which has bindings for almost any codebase.

cURL is also the name of the software project, which encompasses both the curl command-line tool and the libcurl development library.

Why Programmer need CURL?

  • It is highly portable. It is compatible with almost every operating system and connected device.

  • It is useful for testing endpoints, to check if they are working.

  • It can be verbose, providing details of exactly what has been sent/received, which is helpful for debugging.

  • It has good error logging.

  • It can be rate limited.

Making your first request using CURL

Let’s start with the simplest possible request.

curl https://example.com

What happens?

  • curl sends a GET request

  • The server responds with HTML content

  • The response is printed directly in the terminal

Understanding What Just Happened

Behind the scenes, this is equivalent to:

GET / HTTP/1.1
Host: example.com

Browsers do the same thing — curl just lets you see it raw.

Viewing Response Headers

Headers contain important metadata like:

  • Status code

  • Content-Type

  • Server info

To view only headers:

curl -I https://example.com

Sample output:

HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 1256

Viewing Headers + Body Together

curl -i https://example.com

  • -i → include headers

  • Body comes after headers

This is extremely useful for debugging APIs.

Making a GET Request to an API

Let’s hit a real API that returns JSON.

curl https://api.github.com

You’ll notice:

  • Response is JSON

  • Much easier to read than HTML

Raw JSON can be messy. If you have jq installed:

curl https://api.github.com | jq

Sending Query Parameters

Many APIs accept query parameters.

Example:

curl "https://httpbin.org/get?name=arnab&role=developer"

Response will show:

{
  "args": {
    "name": "arnab",
    "role": "developer"
  }
}

Making a POST Request

POST requests are used to send data to the server.

curl -X POST https://httpbin.org/post

With data:

curl -X POST https://httpbin.org/post \
  -d "username=arnab" \
  -d "age=20"

Sending JSON Data (Very Common for APIs)

curl -X POST https://httpbin.org/post \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Arnab",
    "skill": "Web Development"
  }'

Explanation:

  • -H → adds HTTP headers

  • -d → request body

  • JSON is sent to the server

Checking HTTP Status Codes

To see only the status code:

curl -o /dev/null -s -w "%{http_code}\n" https://example.com

Useful for:

  • Health checks

  • Monitoring scripts

  • CI/CD pipelines

Saving Output to a File

curl https://example.com -o response.html

Now open the file:

cat response.html

Common curl Flags You Should Remember

FlagMeaning
-XHTTP method (GET, POST, PUT, DELETE)
-HAdd headers
-dSend data
-iInclude headers
-IHeaders only
-oOutput to file
-vVerbose (debug mode)

Here’s a blog-style article you can publish directly. It focuses on real mistakes beginners make with curl, explains why they happen, and gives terminal-ready examples you can run and take screenshots of.

Common Mistakes Beginners Make with cURL (and How to Fix Them)

curl looks simple at first, but many beginners struggle with it because small mistakes can lead to confusing errors.
If you’re new to APIs, backend development, or debugging HTTP requests, this guide will save you hours of frustration.

Let’s go through the most common curl mistakes, with examples you can try in your terminal.

1. Forgetting the URL Scheme (http:// or https://)

❌ Wrong

curl example.com

Correct

curl https://example.com

Why this happens

Beginners assume curl behaves like a browser.
It doesn’t — curl requires a full URL.

2. Using POST Data Without -X POST

Many beginners think -d automatically means POST (it does, but this causes confusion later).

Confusing

curl https://httpbin.org/post -d "name=arnab"

Clear and correct

curl -X POST https://httpbin.org/post -d "name=arnab"

Why this matters

  • Being explicit avoids mistakes

  • Helps when switching to PUT, PATCH, DELETE

Rule: Always specify the HTTP method when learning.

3. Sending JSON Without Setting Content-Type

Wrong (very common)

curl -X POST https://httpbin.org/post \
  -d '{"name":"Arnab"}'

Correct

curl -X POST https://httpbin.org/post \
  -H "Content-Type: application/json" \
  -d '{"name":"Arnab"}'

Why this fails

Servers don’t magically know your data is JSON.
Without Content-Type: application/json, APIs may:

  • Reject the request

  • Parse data incorrectly

  • Return 400 errors

4. Mixing Single Quotes and Double Quotes Incorrectly

This is especially common on Linux/macOS terminals.

❌ Broken command

curl -X POST https://httpbin.org/post -d "{"name":"Arnab"}"

Correct

curl -X POST https://httpbin.org/post -d '{"name":"Arnab"}'

Why this happens

The shell interprets quotes before curl sees them.

Tip:

  • Use single quotes for JSON

  • Use double quotes for headers

5. Forgetting to Escape URLs with Query Parameters

Risky

curl https://httpbin.org/get?name=arnab&role=dev

Safe

curl "https://httpbin.org/get?name=arnab&role=dev"

Why this matters

The shell treats & as a background operator.

6. Not Checking the HTTP Status Code

Beginners often assume:

“I got a response, so it worked.”

That’s not always true.

❌ Blind request

curl https://example.com/notfound

Check status code

curl -i https://example.com/notfound

or

curl -o /dev/null -s -w "%{http_code}\n" https://example.com/notfound

Important codes to know

  • 200 → OK

  • 400 → Bad request

  • 401 → Unauthorized

  • 403 → Forbidden

  • 404 → Not found

  • 500 → Server error

7. Forgetting Authentication Headers

APIs often require tokens.

❌ Missing auth

curl https://api.example.com/user

Correct

curl https://api.example.com/user \
  -H "Authorization: Bearer YOUR_TOKEN"

Why beginners miss this

Browsers store cookies automatically — curl does not.

8. Not Using Verbose Mode When Debugging

❌ Guessing what went wrong

curl https://example.com

Debug properly

curl -v https://example.com

Verbose mode shows:

  • DNS resolution

  • TLS handshake

  • Request headers

  • Response headers

9. Assuming curl Is Only for GET Requests

Many beginners think:

“curl is just for fetching pages.”

❌ Limited usage

curl https://example.com

Real-world usage

curl -X PUT https://httpbin.org/put -d "update=true"
curl -X DELETE https://httpbin.org/delete

curl is a full API testing tool, not just a downloader.

10. Forgetting to Save Output When Needed

❌ Copy-pasting from terminal

curl https://example.com

Save to file

curl https://example.com -o response.html

This is useful for:

  • Debugging

  • Logs

  • Sharing responses

#curl#api

More from this blog

i_codefullstack

44 posts