<!--
  canonical-url: https://www.avonture.be/blog/hurl
  published:     2026-11-19
  This is a static plain-Markdown mirror generated at build time.
  Visit the canonical URL above for the fully rendered page, with images and interactive components.
-->

# Hurl — Chain Your HTTP Calls in a Recipe Anyone Can Read

> Hurl replaces the curl + jq + export dance with one plain-text .hurl file that logs in, keeps the token, calls the protected API and checks every answer with assertions. Readable by non-developers, runnable as a test suite by the API developer, and shippable to a customer who just wants the data in a database every night.

---
![Hurl — Chain Your HTTP Calls in a Recipe Anyone Can Read](/img/v2/hurl.webp)

**TL;DR**

Hurl is a free, open-source command-line tool that reads a plain-text `.hurl` file, sends the HTTP requests it describes from top to bottom, and checks every response against the assertions written under it. A token captured from the first answer feeds the second request, so "log in, then call the protected API" is one file instead of two `curl` calls glued with `jq`. The same file is a readable recipe for a non-developer, a test suite for the API developer, and a nightly data export for the customer.

Calling a protected API with `curl` always goes the same way: a first `curl` to get a token, `jq` to dig it out of the JSON, a shell variable to keep it, a second `curl` with `-H "Authorization: Bearer $TOKEN"`, and then... I look at the answer with my own eyes and decide it is fine. And when a colleague, or a customer, asks *"how do I call that API?"*, I send them a shell script they cannot read.

Hurl turns that into a small text file anyone can read, which chains the calls by itself and **checks** each answer before going on.

## What Hurl Does For You

Here is the `curl` way of logging in on [DummyJSON](https://dummyjson.com) — a free fake REST API — then asking *"who am I?"* with the token received:

**login-curl.sh**

```bash
#!/usr/bin/env bash
set -euo pipefail

# Step 1. Log in, then dig the token out of the JSON answer with jq
TOKEN=$(curl --silent --fail \
    --header 'Content-Type: application/json' \
    --data "{\"username\": \"${API_USERNAME}\", \"password\": \"${API_PASSWORD}\"}" \
    https://dummyjson.com/auth/login | jq --raw-output '.accessToken')

# Step 2. Call the protected endpoint with that token
curl --silent --fail \
    --header "Authorization: Bearer ${TOKEN}" \
    https://dummyjson.com/auth/me | jq '{username, email}'

# ...and checking the answer is still up to you
```

```bash
$ API_USERNAME=emilys API_PASSWORD=emilyspass ./login-curl.sh
{
  "username": "emilys",
  "email": "emily.johnson@x.dummyjson.com"
}
```

And here is the same two-step conversation, written for Hurl:

**login.hurl**

```hurl
# Step 1. Log in and get an access token
POST https://dummyjson.com/auth/login
Content-Type: application/json
{
  "username": "{{username}}",
  "password": "{{password}}"
}
HTTP 200
[Captures]
token: jsonpath "$.accessToken"

# Step 2. Use the token to ask "who am I?"
GET https://dummyjson.com/auth/me
Authorization: Bearer {{token}}
HTTP 200
[Asserts]
jsonpath "$.username" == "{{username}}"
jsonpath "$.email" endsWith "@x.dummyjson.com"
```

No `jq`, no shell variable, no quoting puzzle around the JSON body: the token captured at step 1 is simply `{{token}}` at step 2. And the two lines under `[Asserts]` verify the answer — the `curl` script leaves that to you. Run it:

```bash
$ hurl --test --variable username=emilys --secret password=emilyspass login.hurl
Success login.hurl (2 request(s) in 3142 ms)
--------------------------------------------------------------------------------
Executed files:    1
Executed requests: 2 (0.6/s)
Succeeded files:   1 (100.0%)
Failed files:      0 (0.0%)
Duration:          3145 ms (0h:0m:3s:145ms)
```

Now with a wrong password:

```bash
$ hurl --test --variable username=emilys --secret password=oops login.hurl
error: Assert status code
  --> login.hurl:8:6
   |
   | POST https://dummyjson.com/auth/login
   | ...
 8 | HTTP 200
   |      ^^^ actual value is <400>
   |

Failure login.hurl (1 request(s) in 118 ms)
--------------------------------------------------------------------------------
Executed files:    1
Executed requests: 1 (8.2/s)
Succeeded files:   0 (0.0%)
Failed files:      1 (100.0%)
Duration:          122 ms (0h:0m:0s:122ms)
```

Hurl points at the exact line that failed, says what it got instead, never sends the second request, and exits with a non-zero code — which is all a script, a cron job or a CI pipeline needs to know.

## Why It Works

* **One file is the whole recipe.** Every step of the conversation sits in the same file, in the order it happens. What `[Captures]` keeps from an answer — a token, an id, a cookie — is a variable for every request below it.
* **A non-developer can read it.** An address, a few `Name: value` lines, the expected answer. No pipes, no escaped quotes, no `$(...)`. Someone who has never opened a terminal can still tell what the file does, and spot the URL that changed.
* **The checks travel with the requests.** The expected status and the `[Asserts]` checklist live right under the request they verify, so the file documents the API *and* its contract.
* **No secret in the file.** Only blanks like `{{password}}`, filled at run time; values passed with `--secret` are masked in every log Hurl prints.
* **It is curl underneath.** Hurl is built on libcurl: proxies, certificates and HTTP/2 behave exactly like the `curl` you already trust.
* **One binary, three systems.** Windows, Linux and macOS, free and open source (Apache 2.0), maintained by Orange.

## Installing Hurl

Hurl is packaged for every system; take the first line that matches yours.

```bash
$ brew install hurl            # macOS, Linux and WSL (Homebrew)
$ winget install Orange-OpenSource.Hurl   # Windows
```

**Debian / Ubuntu: the official .deb (Hurl is not in the Ubuntu archive)**

Ubuntu does not package Hurl, but every GitHub release ships a `.deb`, its checksum and a signed build-provenance attestation:

```bash
$ VERSION=8.1.0
$ curl -LO "https://github.com/Orange-OpenSource/hurl/releases/download/${VERSION}/hurl_${VERSION}_amd64.deb"
$ curl -LO "https://github.com/Orange-OpenSource/hurl/releases/download/${VERSION}/hurl_${VERSION}_amd64.deb.sha256"
$ sha256sum -c "hurl_${VERSION}_amd64.deb.sha256"
$ gh attestation verify "hurl_${VERSION}_amd64.deb" --repo Orange-OpenSource/hurl
$ sudo apt install "./hurl_${VERSION}_amd64.deb"
```

The checksum only proves the download was not truncated; the `gh attestation verify` line is the one proving the file was built by Hurl's own GitHub workflow.

**Nothing to install: the Docker image**

```bash
$ docker run --rm ghcr.io/orange-opensource/hurl:8.1.0 --version
```

Then, in every command of this article, replace `hurl` by `docker run --rm -v "$PWD":/work -w /work ghcr.io/orange-opensource/hurl:8.1.0`. To pass the `HURL_VARIABLE_...` and `HURL_SECRET_...` variables of the test-suite chapter, add `-e HURL_VARIABLE_username -e HURL_SECRET_password` right after `--rm`: a container does not inherit your shell's environment.

Check it is on your `PATH`:

```bash
$ hurl --version
hurl 8.1.0 (x86_64-alpine-linux-musl) libcurl/8.23.0 OpenSSL/3.5.9 zlib/1.3.2 brotli/brotli/1.2.1 zstd/zstd/1.5.7 c-ares/1.34.9 libidn2/2.3.8 nghttp2/1.70.0
```

## Anatomy of a `.hurl` File

A `.hurl` file is a list of **entries**, run from top to bottom. Each entry is a request followed, optionally, by the response it expects:

| Part           | Example                                         | Meaning                                                     |
| -------------- | ----------------------------------------------- | ----------------------------------------------------------- |
| Method and URL | `POST https://dummyjson.com/auth/login`         | the only mandatory line                                     |
| Headers        | `Authorization: Bearer {{token}}`               | one `Name: value` per line, right below                     |
| Sections       | `[Query]`, `[Form]`, `[BasicAuth]`, `[Options]` | query string, form fields, credentials, per-request options |
| Body           | a JSON object, an XML document or raw text      | sent as is, after the headers                               |
| Status         | `HTTP 200`                                      | the answer **must** have that code, or Hurl stops           |
| `[Captures]`   | `token: jsonpath "$.accessToken"`               | keep a value from the answer for later                      |
| `[Asserts]`    | `jsonpath "$.username" == "emilys"`             | the checklist on the answer                                 |

Lines starting with `#` are comments, for humans only.

### The `{{ }}` blanks

A name between double curly braces is filled in just before the request leaves:

| Blank          | Filled with                                                           |
| -------------- | --------------------------------------------------------------------- |
| `{{username}}` | a variable given on the command line, in a file or in the environment |
| `{{token}}`    | a value captured by a previous entry                                  |
| `{{newUuid}}`  | a fresh random UUID, generated at every run — handy for a trace id    |
| `{{newDate}}`  | the current date and time, ISO 8601                                   |

Because the file only holds blanks, it can be committed and shared: nobody can use it without the values.

## Filling the Blanks Without Leaking Secrets

Four ways to give Hurl its values, from the most explicit to the most automatic:

| Option             | Example                                                     | Note                                                          |
| ------------------ | ----------------------------------------------------------- | ------------------------------------------------------------- |
| `--variable`       | `--variable username=emilys`                                | printed as is in verbose logs                                 |
| `--secret`         | `--secret password=emilyspass`                              | replaced by `***` everywhere Hurl prints something            |
| `--variables-file` | `--variables-file vars.env`                                 | one `name=value` per line                                     |
| Environment        | `HURL_VARIABLE_username=emilys`, `HURL_SECRET_password=...` | perfect for CI, where secrets already live in the environment |

The usual pattern keeps credentials in a `.env` file — [loaded by the shell](/blog/bash-load-env) — that never gets committed, and the recipe in the `.hurl` file that does. Time to try it on your machine: the two files below are the `login.hurl` recipe from the beginning of this article and its `.env`.

**Project: hurl-demo**

> **Note:**
>
> Now, run the command below from inside the hurl-demo folder.

**login.hurl**

```hurl
# Step 1. Log in and get an access token
POST https://dummyjson.com/auth/login
Content-Type: application/json
{
  "username": "{{username}}",
  "password": "{{password}}"
}
HTTP 200
[Captures]
token: jsonpath "$.accessToken"

# Step 2. Use the token to ask "who am I?"
GET https://dummyjson.com/auth/me
Authorization: Bearer {{token}}
HTTP 200
[Asserts]
jsonpath "$.username" == "{{username}}"
jsonpath "$.email" endsWith "@x.dummyjson.com"
```

**.env**

```
API_USERNAME="emilys"
API_PASSWORD="emilyspass"
```

```bash
$ source .env && hurl --test --variable "username=${API_USERNAME}" --secret "password=${API_PASSWORD}" login.hurl
Success login.hurl (2 request(s) in 3132 ms)
--------------------------------------------------------------------------------
Executed files:    1
Executed requests: 2 (0.6/s)
Succeeded files:   1 (100.0%)
Failed files:      0 (0.0%)
Duration:          3135 ms (0h:0m:3s:135ms)
```

The masking of `--secret` is not limited to the command line. With `--very-verbose`, Hurl dumps the request it sends — as the equivalent `curl` command — **and** the response it receives, and the password is hidden in both, including in the user profile DummyJSON sends back:

```plaintext
* curl --header 'Content-Type: application/json' --data $'{\n  "username": "emilys",\n  "password": "***"\n}' 'https://dummyjson.com/auth/login'
...
* {"id":1,"firstName":"Emily","lastName":"Johnson",...,"username":"emilys","password":"***",...}
```

A verbose log can therefore be pasted in a ticket without a second thought.

## Assertions: the Checklist on Every Answer

`HTTP 200` says the server answered *"OK"*. It says nothing about **what** it answered: an empty list, a missing field and a half-written CSV all come back with a 200. That is the job of `[Asserts]`.

This file asks DummyJSON for all its users and checks the list is complete and well-formed:

**users.hurl**

```hurl
# Every user must have a first name, a last name and an email
GET https://dummyjson.com/users
[Query]
limit: 0
select: firstName,lastName,email
HTTP 200
[Asserts]
header "Content-Type" contains "application/json"
jsonpath "$.users" isCollection
jsonpath "$.users" count == 208
jsonpath "$.total" == 208
jsonpath "$.users[?!@.firstName]" not exists
jsonpath "$.users[?!@.lastName]" not exists
jsonpath "$.users[?!@.email]" not exists
jsonpath "$.users[0].email" matches /^[a-z.]+@x\.dummyjson\.com$/
duration < 5000
```

Line by line:

* `header "Content-Type" contains ...` — the server says it is sending JSON.
* `jsonpath "$.users" isCollection` then `count == 208` — `$.users` is a list, with exactly 208 entries.
* `jsonpath "$.users[?!@.firstName]" not exists` — *keep only the users with no first name*, and there must be none. Read the three lines together as *"every user has a first name, a last name and an email"*.
* `matches /.../` — a regular expression on a value.
* `duration < 5000` — the answer arrived in less than five seconds.

Run it — every check passes:

```bash
$ hurl --test users.hurl
Success users.hurl (1 request(s) in 3104 ms)
--------------------------------------------------------------------------------
Executed files:    1
Executed requests: 1 (0.3/s)
Succeeded files:   1 (100.0%)
Failed files:      0 (0.0%)
Duration:          3108 ms (0h:0m:3s:108ms)
```

Now break one check on purpose: on line 11, change `jsonpath "$.total" == 208` into `jsonpath "$.total" == 200`, then run the same command again. Hurl shows the expected value next to the actual one:

```bash
$ hurl --test users.hurl
error: Assert failure
  --> users.hurl:11:0
   |
   | GET https://dummyjson.com/users
   | ...
11 | jsonpath "$.total" == 200
   |   actual:   integer <208>
   |   expected: integer <200>
   |

Failure users.hurl (1 request(s) in 102 ms)
--------------------------------------------------------------------------------
Executed files:    1
Executed requests: 1 (9.5/s)
Succeeded files:   0 (0.0%)
Failed files:      1 (100.0%)
Duration:          105 ms (0h:0m:0s:105ms)
```

Put `208` back on line 11 before going on: the next chapters run this file again.

> **An empty filter is not an empty list:**
>
> A JSONPath filter that matches nothing returns **no value** in Hurl, not an empty array. So "nobody is missing a first name" is written `not exists`; `isEmpty` would fail with `actual: none`.

### The predicates you will use most

| Predicate                                            | Example                                       |
| ---------------------------------------------------- | --------------------------------------------- |
| `==`, `!=`, `>`, `>=`, `<`, `<=`                     | `jsonpath "$.total" >= 100`                   |
| `contains`, `startsWith`, `endsWith`                 | `body startsWith "Name,Code"`                 |
| `matches`                                            | `jsonpath "$.email" matches /@example\.com$/` |
| `exists`, `isEmpty`, `count`                         | `jsonpath "$.users" count > 0`                |
| `isCollection`, `isString`, `isInteger`, `isBoolean` | `jsonpath "$.users" isCollection`             |
| `isIsoDate`, `isUuid`                                | `jsonpath "$.createdAt" isIsoDate`            |

Any predicate can be negated with `not`, and the queries go well beyond JSON: `status`, `header`, `cookie`, `body`, `bytes`, `xpath`, `regex`, `sha256`, `duration`, `url`, `redirects`...

## Beyond JSON

[httpbin.org](https://httpbin.org) is a free service that echoes back what it receives — perfect to try the other kinds of requests. This single file sends a form (the shape of an OAuth2 `client_credentials` call), uses basic authentication, generates a trace id, expects a 404 **on purpose**, checks an HTML page with XPath and follows redirects:

**features.hurl**

```hurl
# A form, exactly like an OAuth2 client_credentials call
POST https://httpbin.org/post
[Form]
grant_type: client_credentials
client_id: my-app
HTTP 200
[Asserts]
jsonpath "$.form.grant_type" == "client_credentials"
jsonpath "$.headers['Content-Type']" == "application/x-www-form-urlencoded"

# Basic authentication
GET https://httpbin.org/basic-auth/bob/s3cr3t
[BasicAuth]
bob: s3cr3t
HTTP 200
[Asserts]
jsonpath "$.authenticated" == true

# A trace id, generated at every run
GET https://httpbin.org/headers
X-Trace-Id: blog-{{newUuid}}
HTTP 200
[Asserts]
jsonpath "$.headers['X-Trace-Id']" matches /^blog-[0-9a-f-]{36}$/

# Expect an error on purpose
GET https://httpbin.org/status/404
HTTP 404

# HTML, checked with XPath
GET https://httpbin.org/html
HTTP 200
[Asserts]
header "Content-Type" contains "text/html"
xpath "string(//h1)" == "Herman Melville - Moby-Dick"
body contains "Moby-Dick"

# Redirects: follow them, and check where we landed
GET https://httpbin.org/redirect/2
[Options]
location: true
HTTP 200
[Asserts]
url == "https://httpbin.org/get"
redirects count == 2
```

```bash
$ hurl --test features.hurl
Success features.hurl (8 request(s) in 3998 ms)
--------------------------------------------------------------------------------
Executed files:    1
Executed requests: 8 (2.0/s)
Succeeded files:   1 (100.0%)
Failed files:      0 (0.0%)
Duration:          4002 ms (0h:0m:4s:2ms)
```

Eight requests for six entries: following the two redirects of the last entry costs two more.

Three details worth noticing in it:

* `HTTP 404` is a perfectly valid expectation. Testing that a deleted resource is really gone, or that a wrong token is really refused, is as important as testing the happy path.
* A JSON key containing a dash is written with brackets: `$.headers['X-Trace-Id']`, not `$.headers.X-Trace-Id`.
* `[Options]` changes the behavior of one request only — here `location: true` follows redirects, and `redirects count == 2` checks how many hops were made.

### Downloading a file, and checking it first

`output:` writes the response body to a file instead of the terminal — a CSV list of countries from a public GitHub dataset, here:

**countries.hurl**

```hurl
# Download a CSV file, check it, keep it
GET https://raw.githubusercontent.com/datasets/country-list/main/data.csv
[Options]
output: countries.csv
HTTP 200
[Asserts]
header "Content-Type" contains "text/plain"
bytes count > 1000
body startsWith "Name,Code"
body contains "Belgium,BE"
body split "\n" count > 200
```

```bash
$ hurl --test countries.hurl
Success countries.hurl (1 request(s) in 3240 ms)
--------------------------------------------------------------------------------
Executed files:    1
Executed requests: 1 (0.3/s)
Succeeded files:   1 (100.0%)
Failed files:      0 (0.0%)
Duration:          3243 ms (0h:0m:3s:243ms)

$ head -4 countries.csv
Name,Code
Afghanistan,AF
Albania,AL
Algeria,DZ
```

`body startsWith` guarantees the column titles are there, in the right order; `body split "\n" count > 200` makes sure the file was not cut in the middle. And when one of those checks fails, Hurl **does not write the file at all**: a bad answer never lands on disk.

## For the API Developer: `.hurl` Files as Tests

Seen from the side of whoever builds the API, a folder of `.hurl` files is a test suite: each file is a scenario, each `[Asserts]` line a test. Give Hurl several files and `--test` runs them **in parallel**, then prints one summary; two more flags produce an HTML report for humans and a JUnit XML file for the CI:

```bash
$ HURL_VARIABLE_username=emilys HURL_SECRET_password=emilyspass hurl --test --report-html report/ --report-junit junit.xml *.hurl
Success countries.hurl (1 request(s) in 105 ms)
Success users.hurl (1 request(s) in 137 ms)
Success login.hurl (2 request(s) in 223 ms)
Success features.hurl (8 request(s) in 971 ms)
--------------------------------------------------------------------------------
Executed files:    4
Executed requests: 12 (12.2/s)
Succeeded files:   4 (100.0%)
Failed files:      0 (0.0%)
Duration:          986 ms (0h:0m:0s:986ms)
```

The two `HURL_...` variables are written in front of the command, so they only exist for that one run. An `export` would keep `HURL_SECRET_password` in your shell, and every later `--secret password=...` would then stop with `secret 'password' can't be reassigned`.

Twelve requests in the four files created so far, done in the time of the slowest one. The exit code tells the pipeline what happened: `0` everything passed, `2` a `.hurl` file could not be parsed, `3` a request could not be sent at all (DNS, TLS, timeout...), `4` an assertion failed.

To run the same scenarios against your laptop, the staging server and production, replace the host by a blank — on line 2 of `users.hurl`:

```plaintext title="users.hurl"
GET {{base_url}}/users
```

The host is now chosen on the command line. Here it is still DummyJSON; on your own API, it would be `http://localhost:8000` on your laptop and the staging address in the CI, with the very same files:

```bash
$ HURL_VARIABLE_username=emilys HURL_SECRET_password=emilyspass hurl --test --variable base_url=https://dummyjson.com *.hurl
Success countries.hurl (1 request(s) in 96 ms)
Success login.hurl (2 request(s) in 161 ms)
Success users.hurl (1 request(s) in 170 ms)
Success features.hurl (8 request(s) in 977 ms)
--------------------------------------------------------------------------------
Executed files:    4
Executed requests: 12 (12.1/s)
Succeeded files:   4 (100.0%)
Failed files:      0 (0.0%)
Duration:          991 ms (0h:0m:0s:991ms)
```

Unlike unit tests, these talk to the real, running API — routing, authentication, serialization and database included — exactly the way a client will.

## For the API Consumer: a Recipe You Can Hand Over

Now the other side. Your customer wants the product catalog in their own reporting database, refreshed every night. Instead of a documentation page and a "good luck", send them this file:

**products.hurl**

```hurl
# Daily export of the product catalog, for the reporting database

# Step 1. Log in
POST https://dummyjson.com/auth/login
Content-Type: application/json
{
  "username": "{{username}}",
  "password": "{{password}}"
}
HTTP 200
[Captures]
token: jsonpath "$.accessToken"

# Step 2. Download the catalog, check it, then save it
GET https://dummyjson.com/auth/products
Authorization: Bearer {{token}}
[Query]
limit: 0
select: title,category,price,stock
[Options]
output: products.json
HTTP 200
[Asserts]
jsonpath "$.products" count > 100
jsonpath "$.products[?!@.title]" not exists
jsonpath "$.products[?@.price <= 0]" not exists
```

They can read it — log in, download the catalog, check there are more than a hundred products, all with a title and a positive price, save it — and run it:

```bash
$ hurl --test --variable username=emilys --secret password=emilyspass products.hurl
Success products.hurl (2 request(s) in 134 ms)
--------------------------------------------------------------------------------
Executed files:    1
Executed requests: 2 (14.6/s)
Succeeded files:   1 (100.0%)
Failed files:      0 (0.0%)
Duration:          137 ms (0h:0m:0s:137ms)
```

`products.json` is now on disk, and [DuckDB](/blog/duckdb-json-csv) turns it into a table with one SQL statement — no import tool, no schema to declare. The command below uses the Docker-based `duckdb` function of that article, where `--write` allows writing `catalog.duckdb` in the current folder; with a native DuckDB, drop `--write`:

**load.sql**

```sql
CREATE OR REPLACE TABLE products AS
    SELECT unnest(products, recursive := true)
    FROM read_json_auto('products.json');

SELECT category, count(*) AS items, sum(stock) AS in_stock
FROM products
GROUP BY category
ORDER BY in_stock DESC
LIMIT 5;
```

```bash
$ duckdb --write catalog.duckdb < load.sql
┌─────────────────────┬───────┬──────────┐
│      category       │ items │ in_stock │
│       varchar       │ int64 │  int128  │
├─────────────────────┼───────┼──────────┤
│ kitchen-accessories │    30 │     1656 │
│ groceries           │    27 │     1417 │
│ sports-accessories  │    17 │      871 │
│ smartphones         │    16 │      695 │
│ mobile-accessories  │    14 │      531 │
└─────────────────────┴───────┴──────────┘
```

Put both steps in a script, and let cron run it every night. cron does not load your shell functions, so the script calls the `duckdb-cli` image built in the DuckDB article directly:

**refresh-catalog.sh**

```bash
#!/usr/bin/env bash
# Refresh catalog.duckdb with today's product catalog.
# Meant to run from cron; credentials come from the .env file next to it.
set -euo pipefail

cd "$(dirname "$0")"

# API_USERNAME and API_PASSWORD
# shellcheck source=/dev/null
source ./.env

# 1. Download and check. When an assertion fails, Hurl does not write
#    products.json and exits non-zero: set -e stops the script right here
#    and the database keeps yesterday's data.
hurl --test \
    --variable "username=${API_USERNAME}" \
    --secret "password=${API_PASSWORD}" \
    products.hurl

# 2. Load the checked file into DuckDB (duckdb-cli image, see the DuckDB article)
docker run --rm -i \
    -v "${PWD}:/workspace" \
    -w /workspace \
    -u "$(id -u):$(id -g)" \
    duckdb-cli catalog.duckdb < load.sql
```

```plaintext title="crontab -e"
0 2 * * * /home/me/catalog/refresh-catalog.sh >> /home/me/catalog/refresh.log 2>&1
```

This is where the assertions pay for themselves. The night the API answers 200 with an empty list, or a price at zero, Hurl refuses the answer, writes nothing, and `set -e` stops the script before DuckDB: the database keeps yesterday's data instead of being silently emptied, and `refresh.log` names the exact line that failed.

## Already Have a `curl` Command?

Hurl ships with `hurlfmt`, which converts a `curl` command line into a Hurl entry — the quickest way to move a shell history into a file:

````bash
$ echo "curl -X POST https://dummyjson.com/auth/login -H 'Content-Type: application/json' -d '{\"username\":\"emilys\",\"password\":\"emilyspass\"}'" | hurlfmt --in curl
POST https://dummyjson.com/auth/login
Content-Type: application/json
```
{"username":"emilys","password":"emilyspass"}
```
````

Add an `HTTP 200` and a couple of assertions below it, and the one-off command has become a reusable check.

## Hurl, curl and the GUI Clients

|                             | `curl`                                   | Hurl                      |
| --------------------------- | ---------------------------------------- | ------------------------- |
| Readable by a non-developer | 😕                                       | 🙂                        |
| Chain several calls         | shell variables + [`jq`](/blog/linux-jq) | `[Captures]`, in one file |
| Check each answer           | by eye                                   | `HTTP 200` + `[Asserts]`  |
| Hide secrets in logs        | ❌                                        | `--secret`                |
| Native on Windows           | 😕                                       | ✅                         |

If you prefer clicking to typing, [Postman](/blog/postman) and [Bruno](/blog/bruno) cover the same ground with a graphical interface. Hurl is the opposite choice: no UI at all, a text file that diffs nicely in a pull request and runs identically on a laptop, in CI and in a crontab.

## Conclusion

The token dance from the beginning of this article — `curl`, `jq`, a variable, `curl` again, then squint at the output — is now one readable file that logs in, keeps the token, calls the API and verifies the answer, field by field. The developer runs a folder of them as a test suite; the customer runs one every night to feed a database, protected by the very same assertions. Start with the request you type most often: run it through `hurlfmt`, add one `[Asserts]` line, and commit it next to the code that depends on that API.
