---
name: hurl
description: Run and test HTTP requests with Hurl. Use when working with HTTP APIs, testing web services, or creating HTTP-based test scenarios. Hurl allows you to define HTTP requests in plain text files and validate responses with asserts and captures.
title: hurl
canonical_url: https://skilld.dev/gh/jyasuu/cheat-sheet/hurl
last_updated: 2026-10-06T17:16:37.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [asserting-response.md](https://skilld.dev/api/skills-raw/jyasuu/cheat-sheet/hurl/asserting-response.md), [capturing-response.md](https://skilld.dev/api/skills-raw/jyasuu/cheat-sheet/hurl/capturing-response.md), [filters.md](https://skilld.dev/api/skills-raw/jyasuu/cheat-sheet/hurl/filters.md), [hurl-file.md](https://skilld.dev/api/skills-raw/jyasuu/cheat-sheet/hurl/hurl-file.md), [request.md](https://skilld.dev/api/skills-raw/jyasuu/cheat-sheet/hurl/request.md), [response.md](https://skilld.dev/api/skills-raw/jyasuu/cheat-sheet/hurl/response.md), [running-tests.md](https://skilld.dev/api/skills-raw/jyasuu/cheat-sheet/hurl/running-tests.md), [templates.md](https://skilld.dev/api/skills-raw/jyasuu/cheat-sheet/hurl/templates.md).
>
> If the user asked to install this Skill, run `npx skilld install jyasuu/cheat-sheet/hurl`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/hurl`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jyasuu/cheat-sheet/hurl) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/hurl`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/hurl --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/hurl --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Hurl

## Quick Start

Hurl is a command line tool that runs HTTP requests defined in a simple plain text format. It can chain requests, capture values, and evaluate queries on headers and body responses.

```shell
$ hurl session.hurl
$ hurl --test *.hurl
```

## Hurl File Format

Hurl files use `.hurl` extension and consist of one or more HTTP entries. Each entry has a mandatory request and an optional response section.

```hurl
GET https://example.org/api
HTTP 200
Content-Type: application/json
[Asserts]
jsonpath "$.status" == "success"
```

### Comments

Comments begin with `#` and continue until the end of line:

```hurl
# Check that the API returns the expected response
GET https://example.org/health
HTTP 200
```

## Requests

### Basic Request

```hurl
GET https://example.org/endpoint
```

### HTTP Methods

```hurl
GET https://example.org/resource
POST https://example.org/resource
PUT https://example.org/resource
PATCH https://example.org/resource
DELETE https://example.org/resource
HEAD https://example.org/resource
OPTIONS https://example.org/resource
```

### Headers

```hurl
GET https://example.org/api
User-Agent: MyApp/1.0
Accept: application/json
Content-Type: application/json
```

### Query Parameters

```hurl
GET https://example.org/search
[Query]
term: hurl
page: 1
limit: 10
```

### Form Data

```hurl
POST https://example.org/login
[Form]
username: user@example.com
password: secret123
```

### Multipart Form Data

```hurl
POST https://example.org/upload
[Multipart]
field1: value1
field2: file,data.txt;
field3: file,image.png; image/png
```

### JSON Body

```hurl
POST https://example.org/api/users
{
    "name": "John Doe",
    "email": "john@example.com",
    "age": 30
}
```

### XML Body

```hurl
POST https://example.org/soap-service
Content-Type: application/soap+xml
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Body>
    <GetStatus>
      <id>12345</id>
    </GetStatus>
  </soap:Body>
</soap:Envelope>
```

### GraphQL

```hurl
POST https://example.org/graphql
```graphql
query {
  user(id: "123") {
    name
    email
  }
}
```
```

### Basic Authentication

```hurl
GET https://example.org/protected
[BasicAuth]
admin: secretpassword
```

### Cookies

```hurl
GET https://example.org/page
[Cookies]
session: abc123
preference: dark-mode
```

### Variables in Requests

```hurl
GET https://example.org/api/users/{{user_id}}
[Query]
expand: true

POST https://example.org/api/users
{
    "name": "{{user_name}}",
    "email": "{{user_email}}"
}
```

Define variables via command line:

```shell
$ hurl --variable user_id=123 --variable user_name="John" test.hurl
```

Or use a variables file:

```shell
$ hurl --variables-file config.json test.hurl
```

## Responses

Response sections describe expected HTTP responses and can include assertions and captures.

```hurl
GET https://example.org/api
HTTP 200
Content-Type: application/json
[Asserts]
status == 200
```

### Status Code

```hurl
GET https://example.org/resource
HTTP 200
```

Wildcard for any status:

```hurl
GET https://example.org/resource
HTTP *
[Asserts]
status < 300
```

### Headers

```hurl
GET https://example.org/resource
HTTP 200
Content-Type: application/json
Cache-Control: max-age=3600
```

## Captures

Captures extract values from HTTP responses into variables for use in subsequent requests.

```hurl
GET https://example.org/login
HTTP 200
[Captures]
csrf_token: xpath "normalize-space(//meta[@name='csrf-token']/@content)"

POST https://example.org/login
[Form]
csrf_token: {{csrf_token}}
username: user
password: pass
HTTP 302
```

### Capture Types

```hurl
GET https://example.org/api/user
HTTP 200
[Captures]
user_id: jsonpath "$.id"
user_name: jsonpath "$.name"
email: jsonpath "$.email"
redirect_url: header "Location"
status: status
body_text: body
response_bytes: bytes
sha_hash: sha256
```

### XPath Capture

```hurl
GET https://example.org/page
HTTP 200
[Captures]
title: xpath "string(//head/title)"
first_heading: xpath "string(//h1)"
csrf_token: xpath "normalize-space(//meta[@name='csrf_token']/@content)"
```

### JSONPath Capture

```hurl
GET https://example.org/api/data
HTTP 200
[Captures]
user_id: jsonpath "$.user.id"
items_count: jsonpath "$.items.length()"
first_item: jsonpath "$.items[0]"
```

### Regex Capture

```hurl
GET https://example.org/page
HTTP 200
[Captures]
id: regex "user-(\d+)"
version: regex /version\/(\d+\.\d+\.\d+)/
```

### Duration Capture

```hurl
GET https://example.org/api
HTTP 200
[Captures]
response_time: duration
```

Filters can be applied to captures. See [Filters Reference](https://skilld.dev/api/skills-raw/jyasuu/cheat-sheet/hurl/filters.md) for available filters.

### Certificate Capture

```hurl
GET https://example.org
HTTP 200
[Captures]
cert_subject: certificate "Subject"
cert_issuer: certificate "Issuer"
cert_expiry: certificate "Expire-Date"
```

## Assertions

Assertions validate HTTP responses. They can be implicit (status, headers) or explicit in an `[Asserts]` section.

Filters can be applied to assertions to transform values before comparison. See [Filters Reference](https://skilld.dev/api/skills-raw/jyasuu/cheat-sheet/hurl/filters.md) for available filters.

```hurl
GET https://example.org/api
HTTP 200
Content-Type: application/json
[Asserts]
jsonpath "$.status" == "success"
jsonpath "$.data.length()" == 10
header "X-Rate-Limit" exists
```

### Status Assertions

```hurl
GET https://example.org/resource
HTTP 200
[Asserts]
status == 200
status >= 200
status < 300
```

### Header Assertions

```hurl
GET https://example.org/resource
HTTP 200
[Asserts]
header "Content-Type" contains "application/json"
header "X-Request-Id" matches /^[a-f0-9]+$/
header "Cache-Control" == "max-age=3600"
header "Set-Cookie" count == 2
```

### Body Assertions

```hurl
GET https://example.org/api
HTTP 200
[Asserts]
body contains "success"
body startsWith "{"
body endsWith "}"
```

### JSONPath Assertions

```hurl
GET https://example.org/api/users
HTTP 200
[Asserts]
jsonpath "$.users[0].name" == "Alice"
jsonpath "$.users[*].active" contains true
jsonpath "$.count" != 0
jsonpath "$.users" count == 25
jsonpath "$.price" > 9.99
jsonpath "$.data" exists
jsonpath "$.items" isEmpty not
jsonpath "$.id" isInteger
jsonpath "$.price" isFloat
```

### XPath Assertions

```hurl
GET https://example.org/page
HTTP 200
[Asserts]
xpath "string(//head/title)" == "Home Page"
xpath "count(//div)" == 5
xpath "//h1" exists
xpath "//error" not exists
xpath "boolean(count(//warning))" == false
```

### Regex Assertions

```hurl
GET https://example.org/page
HTTP 200
[Asserts]
regex "user:(\d+)" == "user:123"
regex /version:(\d+\.\d+)/ == "version:1.0"
```

### Bytes Assertions

```hurl
GET https://example.org/file.zip
HTTP 200
[Asserts]
bytes count == 1024000
sha256 == hex,abc123...
```

### Duration Assertions

```hurl
GET https://example.org/api
HTTP 200
[Asserts]
duration < 1000
```

### Certificate Assertions

```hurl
GET https://example.org
HTTP 200
[Asserts]
certificate "Subject" == "CN=example.org"
certificate "Issuer" == "C=US, O=Let's Encrypt"
certificate "Expire-Date" daysAfterNow > 30
```

### Predicates

Available predicates: `==`, `!=`, `>`, `>=`, `<`, `<=`, `startsWith`, `endsWith`, `contains`, `matches`, `exists`, `isBoolean`, `isEmpty`, `isFloat`, `isInteger`, `isIpv4`, `isIpv6`, `isIsoDate`, `isList`, `isNumber`, `isObject`, `isString`, `isUuid`

All predicates can be negated with `not`:

```hurl
[Asserts]
header "Authorization" not exists
jsonpath "$.error" not contains "failed"
```

## Chaining Requests

Requests can be chained to create multi-step scenarios:

```hurl
# Get CSRF token
GET https://example.org/login
HTTP 200
[Captures]
csrf_token: xpath "normalize-space(//input[@name='csrf']/@value)"

# Login with captured token
POST https://example.org/login
[Form]
csrf: {{csrf_token}}
username: user
password: pass
HTTP 302

# Follow redirect to dashboard
GET https://example.org/dashboard
HTTP 200
[Asserts]
body contains "Welcome, user"
```

## Control Flow

### Retry

```hurl
POST https://example.org/jobs
HTTP 201
[Captures]
job_id: jsonpath "$.id"

GET https://example.org/jobs/{{job_id}}
[Options]
retry: 10
retry-interval: 500ms
HTTP 200
[Asserts]
jsonpath "$.status" == "COMPLETED"
```

### Skip

```hurl
GET https://example.org/optional
[Options]
skip: true
HTTP 200
```

### Repeat

```hurl
GET https://example.org/health
[Options]
repeat: 10
HTTP 200
```

### Delay

```hurl
GET https://example.org/api
[Options]
delay: 2s
HTTP 200
```

## Redirection Handling

### Manual Redirection Testing

```hurl
GET https://example.org
HTTP 301
Location: https://www.example.org

GET https://www.example.org
HTTP 200
```

### Automatic Redirection

```hurl
GET https://example.org
[Options]
location: true
HTTP 200
[Asserts]
url == "https://www.example.org"
redirects count == 1
redirects nth 0 location == "https://www.example.org"
```

## Secrets and Redaction

Hide sensitive values from logs:

```shell
$ hurl --secret api_key=abc123 test.hurl
```

Or make captures redacted:

```hurl
POST https://example.org/login
HTTP 200
[Captures]
token: header "X-Auth-Token" redact
```

## Command Line Options

### Testing

```shell
$ hurl --test *.hurl              # Test mode
$ hurl --test --jobs 4 *.hurl     # Parallel test execution
$ hurl --test --repeat 100 *.hurl # Stress test
```

### Output Control

```shell
$ hurl -o output.json test.hurl   # Write output to file
$ hurl --no-output test.hurl      # Suppress output
$ hurl --include test.hurl        # Include headers in output
$ hurl --color test.hurl          # Colorize output
```

### Reports

```shell
$ hurl --report-html results/ test.hurl    # HTML report
$ hurl --report-json results/ test.hurl    # JSON report
$ hurl --report-junit results.xml test.hurl # JUnit XML
$ hurl --report-tap results.tap test.hurl  # TAP format
```

### Debugging

```shell
$ hurl --verbose test.hurl           # Verbose output
$ hurl --very-verbose test.hurl      # Very verbose (includes headers)
$ hurl --test --error-format long *.hurl # Detailed error output
```

### Request Options

```shell
$ hurl --location test.hurl          # Follow redirects
$ hurl --compressed test.hurl        # Request compressed response
$ hurl -u user:pass test.hurl        # Basic auth
$ hurl -H "Header: value" test.hurl  # Custom header
$ hurl -x proxy:8080 test.hurl       # Use proxy
$ hurl --insecure test.hurl          # Skip SSL verification
$ hurl --max-time 30 test.hurl       # Timeout
$ hurl --retry 3 test.hurl           # Retry on failure
```

### Variables

```shell
$ hurl --variable name=value test.hurl
$ hurl --variables-file vars.json test.hurl
$ HURL_VARIABLE_NAME=value hurl test.hurl
```

### Files and Paths

```shell
$ hurl --file-root /path/to/files test.hurl
$ hurl --glob "tests/**/*.hurl"       # Find files by pattern
$ hurl dir/                           # Run all .hurl files in directory
```

## Testing Best Practices

### Use Test Mode

```shell
$ hurl --test test/api/*.hurl
```

### Generate Reports for CI/CD

```shell
$ hurl --test --report-junit results.xml --report-html reports/ tests/
```

### Organize Tests

```shell
tests/
  api/
    users.hurl
    auth.hurl
    products.hurl
  integration/
    checkout.hurl
    search.hurl
  smoke/
    health.hurl
```

### Test Performance

```hurl
GET https://example.org/api
HTTP 200
[Asserts]
duration < 500
```

### Debug Failing Tests

```shell
$ hurl --test --very-verbose --error-format long failing_test.hurl
```

## Common Patterns

### API Health Check

```hurl
GET https://api.example.org/health
HTTP 200
[Asserts]
jsonpath "$.status" == "healthy"
jsonpath "$.version" exists
```

### REST API CRUD

```hurl
# Create
POST https://api.example.org/users
Content-Type: application/json
{
    "name": "Test User",
    "email": "test@example.com"
}
HTTP 201
[Captures]
user_id: jsonpath "$.id"

# Read
GET https://api.example.org/users/{{user_id}}
HTTP 200
[Asserts]
jsonpath "$.name" == "Test User"

# Update
PUT https://api.example.org/users/{{user_id}}
Content-Type: application/json
{
    "name": "Updated User"
}
HTTP 200

# Delete
DELETE https://api.example.org/users/{{user_id}}
HTTP 204
```

### Form-based Login

```hurl
GET https://example.org/login
HTTP 200
[Captures]
csrf: xpath "normalize-space(//input[@name='_csrf']/@value)"

POST https://example.org/login
[Form]
_csrf: {{csrf}}
username: myuser
password: mypass
HTTP 302
Location: /dashboard
[Asserts]
status == 302
```

### GraphQL Query

```hurl
POST https://api.example.org/graphql
```graphql
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
    posts {
      title
    }
  }
}
```
variables: {"id": "{{user_id}}"}
HTTP 200
[Asserts]
jsonpath "$.data.user.name" exists
jsonpath "$.errors" not exists
```

### SOAP Request

```hurl
POST https://example.org/soap-service
Content-Type: application/soap+xml; charset=utf-8
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Body>
    <GetProductInfo>
      <productId>12345</productId>
    </GetProductInfo>
  </soap:Body>
</soap:Envelope>
HTTP 200
[Asserts]
xpath "boolean(//product/available)" == true
```

## File Reference

### Local Resources

- [Filters Reference](https://skilld.dev/api/skills-raw/jyasuu/cheat-sheet/hurl/filters.md) - Available filters for transforming captured values and assertions
- [Variables & Templates](https://skilld.dev/api/skills-raw/jyasuu/cheat-sheet/hurl/templates.md) - Variables, templating, and secrets documentation
- [Hurl File Format](https://skilld.dev/api/skills-raw/jyasuu/cheat-sheet/hurl/hurl-file.md) - File structure, comments, and special characters
- [Request Format](https://skilld.dev/api/skills-raw/jyasuu/cheat-sheet/hurl/request.md) - HTTP method, URL, headers, body, auth, forms
- [Response Format](https://skilld.dev/api/skills-raw/jyasuu/cheat-sheet/hurl/response.md) - Expected response, version, status, headers
- [Captures](https://skilld.dev/api/skills-raw/jyasuu/cheat-sheet/hurl/capturing-response.md) - Extracting values from responses
- [Assertions](https://skilld.dev/api/skills-raw/jyasuu/cheat-sheet/hurl/asserting-response.md) - Validating responses with asserts and predicates
- [Running Tests](https://skilld.dev/api/skills-raw/jyasuu/cheat-sheet/hurl/running-tests.md) - Test mode, reports, CI/CD integration
