req

req is a command-line tool for managing and executing HTTP requests using configuration files.

Why req?

Have you ever needed to:

• Test API endpoints repeatedly during development?
• Share API request configurations with your team?
• Manage different environments (dev, staging, prod) for the same API?
• Document API usage in a simple, executable format?

req solves these problems by letting you define HTTP requests in a TOML file and execute them with a simple command.

Quick Start

Installation

cargo install req

Your First Request

Create a file named req.toml:

[tasks.hello]
GET = 'https://httpbin.org/get'
description = "My first request"

Run it:

$ req hello
# Sends GET request to https://httpbin.org/get

That's it! You've just sent your first HTTP request with req.

Common Use Cases

1. Testing REST APIs

Create a set of tasks for your API endpoints:

[tasks.list-users]
GET = 'https://api.example.com/users'
description = "Get all users"

[tasks.get-user]
GET = 'https://api.example.com/users/123'
description = "Get specific user"

[tasks.create-user]
POST = 'https://api.example.com/users'
description = "Create new user"

[tasks.create-user.body.json]
name = "John Doe"
email = "[email protected]"

List all available tasks:

$ req
list-users    Get all users
get-user      Get specific user
create-user   Create new user

Execute any task:

$ req list-users
$ req create-user

2. Working with Authentication

Bearer Token Authentication:

Most modern APIs use Bearer token authentication. Use variables to manage tokens securely:

[variables]
TOKEN = "your-api-token-here"

[tasks.authenticated]
GET = 'https://api.example.com/protected'

[tasks.authenticated.auth]
bearer = "${TOKEN}"

Override tokens from command line:

$ req authenticated -v TOKEN=different-token

Basic Authentication:

For APIs requiring username and password:

[variables]
USERNAME = "admin"
PASSWORD = "secret"

[tasks.basic-auth]
GET = 'https://api.example.com/admin'

[tasks.basic-auth.auth.basic]
username = "${USERNAME}"
password = "${PASSWORD}"

Override credentials from command line:

$ req basic-auth -v USERNAME=user -v PASSWORD=pass

3. Managing Multiple Environments

Using Environment Files:

The recommended way to manage multiple environments is to use .env files:

# .env.dev
BASE_URL=https://dev.api.example.com
API_TOKEN=dev-token-123

# .env.prod
BASE_URL=https://api.example.com
API_TOKEN=prod-token-xyz

# req.toml
[tasks.api-call]
GET = "${BASE_URL}/endpoint"

[tasks.api-call.auth]
bearer = "${API_TOKEN}"

Switch between environments:

$ req api-call -e .env.dev
$ req api-call -e .env.prod

Auto-loading .env file:

You can configure req to automatically load a .env file:

[config]
env-file = true  # Loads .env by default

[tasks.api-call]
GET = "${BASE_URL}/endpoint"

Or specify a custom default env file:

[config]
env-file = ".env.development"  # Loads .env.development by default

Using Separate Config Files:

Alternatively, you can create separate config files for each environment:

# req.dev.toml
[variables]
BASE_URL = "https://dev.api.example.com"

[tasks.test]
GET = "${BASE_URL}/endpoint"

# req.prod.toml
[variables]
BASE_URL = "https://api.example.com"

[tasks.test]
GET = "${BASE_URL}/endpoint"

Switch between environments:

$ req test -f req.dev.toml
$ req test -f req.prod.toml

4. Sending Different Types of Request Bodies

Plain Text:

[tasks.plain]
POST = 'https://httpbin.org/post'

[tasks.plain.body]
plain = "Hello, World!"

JSON:

[tasks.json]
POST = 'https://httpbin.org/post'

[tasks.json.body.json]
name = "Alice"
age = 30
active = true

Form Data:

[tasks.form]
POST = 'https://httpbin.org/post'

[tasks.form.body.form]
username = "alice"
password = "secret"

Multipart (File Upload):

[tasks.upload]
POST = 'https://httpbin.org/post'

[tasks.upload.body.multipart]
document.file = "/path/to/document.pdf"
description = "My document"

5. Working with Query Parameters and Headers

[tasks.search]
GET = 'https://api.example.com/search'

[tasks.search.queries]
q = "rust programming"
limit = "10"
sort = "relevance"

[tasks.search.headers]
Accept = "application/json"
User-Agent = "req/1.0"

6. Testing Requests Before Sending

Use --dryrun to see what will be sent:

$ req create-user --dryrun

Generate equivalent curl command:

$ req create-user --curl
curl -X POST 'https://api.example.com/users' \
  -H 'Content-Type: application/json' \
  -d '{"name":"John Doe","email":"[email protected]"}'

7. Debugging Responses

Include response headers in output:

$ req get-user -i

8. Working with Self-Signed Certificates

For development/testing environments:

[config]
insecure = true

[tasks.dev-api]
GET = 'https://dev.local/api'

9. Following Redirects

[config]
redirect = 5  # Follow up to 5 redirects

[tasks.shortened]
GET = 'https://short.url/abc123'

10. Task-Specific Configuration

Override global config per task:

[config]
redirect = 0
insecure = false

[tasks.special]
GET = 'https://example.com/redirect'

[tasks.special.config]
redirect = 10
insecure = true

Next Steps

• See REFERENCE.md for complete configuration reference
• Check out example configurations in the examples/ directory
• Run req --help for all available options

Tips

• Store sensitive tokens in environment variables and pass them with -v
• Use descriptive task names to make your workflow self-documenting
• Share req.toml files with your team for consistent API testing
• Combine with shell scripts for automated testing workflows