cURL Command Guide for Beginners: GET, POST, Headers, Auth, and File Downloads

Overview

If you need a compact curl command guide that covers the commands you actually use in day-to-day work, start here. This article is designed as a beginner tutorial and a reusable reference. It focuses on the parts of cURL that developers, IT admins, and technical users revisit most often: request methods, headers, JSON payloads, authentication, redirects, and file downloads.

At a high level, cURL sends a request to a URL and shows you the response. That makes it useful for API testing, checking endpoints from a terminal, downloading files in scripts, and verifying whether a service is behaving the way you expect.

The basic syntax looks like this:

curl https://example.com

That simple command usually performs an HTTP GET request. In many cases, that is enough to fetch a page or test an API endpoint. But most real-world use quickly involves a few flags. Here are the building blocks worth memorizing:

• -X sets the request method such as GET, POST, PUT, PATCH, or DELETE.
• -H sends a header.
• -d sends request data, commonly for POST requests.
• -u sends basic authentication credentials.
• -o writes output to a file.
• -O saves using the remote file name.
• -L follows redirects.
• -I fetches headers only.
• -i includes response headers in the output.
• -v enables verbose mode for troubleshooting.
• -s runs silently, useful in scripts.

For many users, the best way to learn cURL is to keep a small set of known-good examples and adjust them as needed. The sections below are arranged that way.

GET request examples

The simplest GET request:

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

GET with query parameters can be written directly in the URL:

curl "https://api.example.com/users?page=2&limit=20"

If the URL contains special characters, wrapping it in quotes avoids shell parsing problems.

To view only response headers:

curl -I https://example.com

To include response headers and body together:

curl -i https://example.com

POST request examples

For form-style data:

curl -X POST https://api.example.com/login \
  -d "username=demo" \
  -d "password=secret"

For JSON payloads, set the content type explicitly:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Alex","email":"alex@example.com"}'

This is the pattern most people mean when searching for curl GET POST examples. It is also the point where quoting rules start to matter. If your shell is sensitive to quotes, test payloads carefully or store the JSON in a file.

Sending JSON from a file is often easier and cleaner:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d @payload.json

Headers and authentication

Custom headers are common for APIs:

curl https://api.example.com/data \
  -H "Accept: application/json" \
  -H "X-Request-ID: test-123"

Bearer token authentication:

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

Basic authentication:

curl -u username:password https://api.example.com/data

Some teams prefer keeping tokens out of shell history by storing them in environment variables:

curl https://api.example.com/data \
  -H "Authorization: Bearer $API_TOKEN"

That simple habit makes a curl headers auth tutorial much safer in practice.

File download commands

To save output with a chosen file name:

curl -o report.zip https://example.com/files/report.zip

To save using the remote file name:

curl -O https://example.com/files/report.zip

To follow redirects during downloads:

curl -L -O https://example.com/download/latest

This is the standard curl file download command pattern for endpoints that redirect to a generated or versioned file.

Maintenance cycle

This section explains how to keep your cURL commands current. cURL itself is stable, but the endpoints and authentication methods around it change regularly. A command that worked six months ago may fail today because of redirect behavior, token expiry, new header requirements, or payload format changes.

A practical maintenance cycle for cURL usage looks like this:

1. Keep a small personal command library. Save your most-used request patterns in a note, shell script, or internal wiki.
2. Review examples on a schedule. A quarterly review is usually enough for personal references. For production scripts, review whenever the service API changes.
3. Separate stable syntax from changing values. URLs, tokens, file names, and JSON fields change more often than cURL flags.
4. Retest auth flows. Authentication is often the first part of an old example to become outdated.
5. Check shell compatibility. A command copied from one environment may need adjustments in another.

One useful habit is to standardize your own examples by job type instead of product name. For example:

• Basic GET request
• GET with headers
• POST JSON body
• Bearer token request
• File download with redirect
• Verbose troubleshooting request

This turns your cURL notes into a durable user manual rather than a stack of one-off snippets.

It also helps to understand what tends to change and what does not. These parts are relatively stable:

• Core flags such as -H, -d, -o, -L, and -u
• The general structure of GET and POST requests
• Using headers for content type and authorization

These parts change more often:

• API versions in URLs
• Required headers
• Authentication scheme details
• JSON request and response fields
• Rate-limiting behavior and retry expectations

If you maintain onboarding docs for a team, use cURL examples that show the command clearly but avoid embedding secrets. Replace real tokens with placeholders and note where values should come from. If your wider workflow includes login hardening, see How to Set Up Two-Factor Authentication on Google, Microsoft, Apple, and GitHub for account protection practices that support safer API access habits.

For teams working with hosting, deployments, or site setup, cURL often appears alongside server checks and site launch tasks. In that context, WordPress Setup Manual: Install, Secure, and Launch a Site Step by Step is a useful companion for broader environment setup.

Signals that require updates

Not every cURL note needs constant rewriting, but some changes are clear signals that your examples should be refreshed. This is where many command references become stale: the syntax still looks right, yet the surrounding assumptions are no longer true.

Update your saved commands when you notice any of the following:

1. Authentication starts failing

If a request that used to work now returns unauthorized or forbidden responses, review these first:

• Expired tokens
• Changed auth scheme
• Missing scopes or permissions
• Header formatting errors
• Credentials exposed or rotated

For example, a saved request using basic auth may need to be replaced with a bearer token workflow. Even if the cURL structure remains similar, your documentation should reflect the safer or currently supported method.

2. The API version changes

Versioned endpoints often move from one path to another, such as from /v1/ to /v2/. When that happens, old examples may still connect but return different field names or validation errors. Review the URL, request body, and expected response format together.

3. Redirect behavior changes

File download links and some login flows rely on redirects. If a command suddenly saves HTML instead of the file you expected, try adding -L and inspect the response headers:

curl -L -O https://example.com/download/latest

If you are troubleshooting browser-related caching or stale responses during testing, How to Clear Cache on Chrome, Safari, Firefox, and Edge can help separate browser cache issues from command-line behavior.

4. Payload validation errors appear

JSON-based APIs evolve. Fields may become required, deprecated, or renamed. If a POST command begins returning bad request errors, compare your saved payload against the current expected structure. A command template that posts from a file often makes these changes easier to manage than editing large inline JSON strings.

5. Shell quoting breaks after copy and paste

This is especially common when commands move between documentation systems, terminals, chat tools, and operating systems. If a command seems correct but fails immediately, inspect quotation marks, line continuation characters, and variable expansion. Keep your stored examples plain and minimal.

6. Network and DNS behavior changes

Sometimes the cURL command is fine, but the environment is not. If requests fail intermittently, time out, or resolve to the wrong place, review the network path before rewriting the command. Broader connectivity issues can mimic API problems. If that sounds familiar, Wi-Fi Keeps Disconnecting? A Troubleshooting Guide for Phones, Laptops, and Routers may help isolate the underlying connection problem.

Common issues

This section works as a lightweight troubleshooting guide for cURL commands that do not behave as expected. When a request fails, resist the urge to change everything at once. Check the basics in a repeatable order.

Problem: The response is empty or not what you expected

Try these checks:

• Add -i to include response headers.
• Add -v to see connection details.
• Confirm the URL and query parameters.
• Check whether the endpoint redirects and needs -L.

curl -v -i https://api.example.com/data

Problem: The server says unsupported media type or bad request

This often means the server expected a different content type or payload structure.

Use:

curl -X POST https://api.example.com/items \
  -H "Content-Type: application/json" \
  -d @payload.json

Then verify that payload.json contains valid JSON and matches the expected fields.

Problem: Authentication fails

Work through these checks in order:

1. Confirm the token or credentials are current.
2. Check spelling and spacing in the header.
3. Verify whether the endpoint expects bearer auth, basic auth, or another method.
4. Use verbose mode to inspect the request.

curl -v https://api.example.com/data \
  -H "Authorization: Bearer $API_TOKEN"

Problem: The command works in one environment but not another

This usually points to shell differences, environment variables, proxy behavior, certificate handling, or local DNS resolution. Keep one known-good minimal command and test from there instead of starting with a large copied snippet.

Problem: File downloads save the wrong content

If a supposed zip or binary file is actually an HTML page, check for these causes:

• You downloaded an error page.
• The endpoint redirected and you did not use -L.
• You needed authentication headers.
• The download URL expired.

A safer command is often:

curl -L -H "Authorization: Bearer $API_TOKEN" \
  -o archive.zip https://example.com/files/archive

Problem: Output is hard to read

By default, cURL prints raw output. For JSON APIs, many users pipe results to a formatter if one is available in their environment. If you prefer to keep things portable, save the output first and inspect it separately:

curl -s https://api.example.com/data -o response.json

For general machine cleanup while testing local development tools, How to Fix a Slow Computer: Step-by-Step Checks for Windows and Mac may be helpful if terminal work is being affected by broader system sluggishness.

A simple checklist before you blame cURL

• Is the URL correct?
• Is the method correct?
• Are the headers complete?
• Is the auth method current?
• Is the payload valid?
• Are redirects being followed?
• Is the network path healthy?

That checklist solves a surprising number of “cURL is broken” reports.

When to revisit

The most useful cURL reference is not the one with the most commands. It is the one you revisit at the right moments. This final section gives you a practical refresh plan so your examples remain accurate and safe to reuse.

Revisit your cURL command notes on a scheduled review cycle and whenever search intent or usage patterns shift. In practice, that means reviewing your reference in these situations:

• Quarterly: Check whether your most-used commands still reflect current auth and endpoint patterns.
• After an API version change: Update URLs, payloads, and expected headers.
• When onboarding new team members: Simplify examples and remove local assumptions.
• After a failed automation run: Compare the saved cURL command against the live service behavior.
• When docs become too long: Reduce them to a small quick start guide with proven examples.

A practical maintenance workflow looks like this:

1. Create a short cURL reference file with six to ten commands you actually use.
2. Replace secrets with placeholders or environment variables.
3. Add one comment line above each example describing when to use it.
4. Retest every example during your next review cycle.
5. Remove patterns you no longer use, especially outdated auth methods.

Here is a strong starter set for a personal cURL manual:

# Basic GET
curl https://api.example.com/health

# GET with headers
curl https://api.example.com/data \
  -H "Accept: application/json"

# POST JSON
curl -X POST https://api.example.com/items \
  -H "Content-Type: application/json" \
  -d @payload.json

# Bearer auth
curl https://api.example.com/private \
  -H "Authorization: Bearer $API_TOKEN"

# Download with redirect
curl -L -O https://example.com/download/latest

# Verbose troubleshooting
curl -v -i https://api.example.com/debug

If you keep those examples updated, you will cover most daily use cases without needing a bulky manual PDF alternative or a full API client for every quick test.

As your work expands into related tooling, it can help to keep adjacent step-by-step references nearby. For example, if you document developer workflows or knowledge bases, How to Use Obsidian: Vault Setup, Sync Options, Plugins, and Markdown Basics is useful for organizing technical notes. The main goal is the same: make routine tasks easy to repeat correctly.

In short, revisit this topic when your commands stop being trustworthy, when authentication patterns shift, or when you notice that your examples answer old questions better than current ones. A small, maintained cURL reference is more valuable than a large archive of stale snippets. Keep it lean, test it periodically, and update it when your tools or endpoints change.