curl-runner Documentation

A powerful CLI tool for HTTP request management using YAML configuration files. Built with Bun for blazing-fast performance.

Copy Markdown

Features

YAML Configuration

Define HTTP requests using simple, readable YAML files with support for variables and templates.

Fast Execution

Built with Bun for blazing-fast performance. Execute requests sequentially or in parallel.

Powerful CLI

Comprehensive command-line interface with beautiful output, progress indicators, and error handling.

Flexible Configuration

Global settings, variable interpolation, response validation, and customizable output formats.

What is curl-runner?

curl-runner is a modern CLI tool that transforms how you manage and execute HTTP requests. Instead of writing complex curl commands or maintaining scattered shell scripts, you define your API requests in clean, readable YAML files with powerful features like parallel execution, response validation, and variable templating.

Built with Bun for exceptional performance, curl-runner is perfect for API testing, automation workflows, CI/CD pipelines, and development environments where speed and reliability matter.

Quick Start

Get up and running with curl-runner in just a few minutes.

Prerequisites

For npm/yarn/pnpm installation: Bun runtime must be installed on your system.

Install Bun: curl -fsSL https://bun.sh/install | bash

For standalone builds: No prerequisites needed! The standalone executable includes Bun bundled within it.

1. Install curl-runner

# Install curl-runner globally
npm install -g @curl-runner/cli

# Or using yarn
yarn global add @curl-runner/cli

# Or using pnpm
pnpm install -g @curl-runner/cli

# Or using bun
bun install -g @curl-runner/cli

# Install curl-runner globally
npm install -g @curl-runner/cli

# Or using yarn
yarn global add @curl-runner/cli

# Or using pnpm
pnpm install -g @curl-runner/cli

# Or using bun
bun install -g @curl-runner/cli

2. Create a YAML file

api-test.yaml

# Basic API test configuration
collection:
  name: "My API Tests"
  requests:
    - name: "Get users"
      url: "https://jsonplaceholder.typicode.com/users"
      method: GET
      expect:
        status: 200
        
    - name: "Create user"
      url: "https://jsonplaceholder.typicode.com/users"
      method: POST
      headers:
        Content-Type: "application/json"
      body: |
        {
          "name": "John Doe",
          "email": "john@example.com"
        }
      expect:
        status: 201

# Basic API test configuration
collection:
  name: "My API Tests"
  requests:
    - name: "Get users"
      url: "https://jsonplaceholder.typicode.com/users"
      method: GET
      expect:
        status: 200
        
    - name: "Create user"
      url: "https://jsonplaceholder.typicode.com/users"
      method: POST
      headers:
        Content-Type: "application/json"
      body: |
        {
          "name": "John Doe",
          "email": "john@example.com"
        }
      expect:
        status: 201

3. Run your requests

curl-runner api-test.yaml

curl-runner api-test.yaml

Next Steps

Installation Guide

Detailed installation instructions for all platforms

Get Started

Use Cases

Discover real-world applications and examples

Explore

Tutorials

Step-by-step guides and walkthroughs

Learn

Examples

Browse practical code examples

View

Key Concepts

Master these essential concepts to get the most out of curl-runner