Skip to main content

Building a Terminal curl Based API Workflow

How to run real API work from the shell without a GUI.

Updated 5 min readMarkdown

Quick answer: A terminal curl based workflow is reliable because curl is already on almost every machine, reads inputs from environment variables and config files, and chains into shell tools like jq. Treat the commands as scripts in Git rather than one-off lines, and you get repeatable calls you can run locally or in CI. The trade-off is that you own the organization, auth handling, and assertions yourself.

Why the curl workflow holds up

curl does one thing and does it everywhere. The same command that works on your laptop works on a build server and inside a container, with no account to sign into and no collection to sync. When an API call is plain text, it survives a reboot, shows up in a pull request diff, and can be copied into an incident ticket without exporting a file.

That plain-text nature also keeps the work honest. There is no hidden tab holding an old token or a saved environment you forgot about. Every header, body, and flag is visible in the command, which makes debugging a failing call a matter of reading the script rather than clicking through dialogs.

The pieces that make it repeatable

Loose curl lines typed from memory do not scale; a small set of conventions does. Store the base URL and tokens in environment variables so nothing sensitive is committed. Keep recurring headers in a curl config file loaded with the -K flag, and use a cookie jar with -c and -b when an API relies on browser-style sessions. For JSON APIs, pipe the response into jq to pull out a field and hand it to the next call.

When you need a check, lean on curl's own output rather than eyeballing the body. The --fail-with-body flag gives a non-zero exit code on an HTTP error while preserving the payload, and -w prints metrics such as the status code and total time. A shell script can use that exit code to stop a sequence early, which is the minimal version of an assertion.

A two-step worked example

This logs in, extracts the token with jq, and calls a protected endpoint. Credentials come from the environment, not the script.

BASE="https://api.example.com"
TOKEN=$(curl -s --fail-with-body "$BASE/login" \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"$EMAIL\",\"password\":\"$PASSWORD\"}" \
  | jq -r '.token')

curl -s --fail-with-body "$BASE/orders?status=open" \
  -H "Authorization: Bearer $TOKEN" \
  -w "\nHTTP %{http_code}\n"

If the login fails, the non-zero exit stops the script before the second call, so you never send an authenticated request with an empty token.

Flag reference

Flag What it does
-s Silent mode, drops the progress meter
--fail-with-body Non-zero exit on HTTP errors while keeping the body
-H Adds a request header
-d Sends a request body
-c and -b Writes and reads a cookie jar
-K Reads default options from a config file
-w Prints metrics such as status code after the body
-x Routes the call through a proxy

Where curl stops being enough

curl sends a call and prints the result; it does not manage a growing suite for you. Once a workflow spans many endpoints, shared variables across environments, and assertions at every step, the shell quoting and chained pipes get hard to read, and nothing in raw curl validates a response against a schema. A desktop app such as Powerduck addresses that gap by importing the API and running ordered scenario steps with per-step assertions and scoped variables while sending requests through the local main process, so browser CORS never blocks a call. For a wider view of the tools in this space, the Postman alternatives guide covers where each one fits.

Frequently asked questions

Is curl enough for API testing? It is enough for smoke checks and short chained flows, but multi-step suites with shared state and reporting are easier to maintain in a tool built for scenario testing.

How do I keep tokens out of my scripts? Read them from environment variables or your CI secret store, and add any local env files to .gitignore so they are never committed.

What replaces the saved collections a GUI gives me? A Git folder of shell scripts and a curl config file serves the same role, with the added benefit of a normal diff and review history.

Does jq have to be installed? Only for parsing JSON in the pipeline. Plain curl works without it, but extracting a field by hand is brittle, so jq is worth adding.

The bottom line

Use curl when you want calls that are portable, visible, and close to the metal, and back them with environment variables, a config file, and exit-code checks instead of memory. The moment a script turns into a long suite with assertions and shared environments, move that part into a tool made for scenarios rather than stacking more pipes. The shell is a strong default; it is not the only tool you should own.

No comments yet. Be the first to comment.