reqsh 0.3.3

Interactive HTTP shell for API workflows
Documentation
---
title: Introduction
description: Master the interactive HTTP shell - install, configure and execute requests.
order: 1
---

# Introduction

Master the interactive HTTP shell. Learn how to install, configure your environment and execute requests efficiently.

## Getting Started

### 1. Install reqsh

Head over to the [installation guide](/docs/install) to download the binary or build from source.

### 2. Start the shell

Simply type `reqsh` in your terminal. This drops you into the interactive REPL.

```sh
reqsh
```

### 3. Set a base URL

Define your target host. All subsequent requests in this session will be appended to this base URL automatically.

```sh
reqsh> base https://api.example.com
```

### 4. Send a request

Type the HTTP method and the relative path. End the request with a `###` line to execute it.

```sh
reqsh> GET /users
.....> ###
```

## Sending Requests

The shell supports building complex requests step-by-step. Start with the method and path. HTTP methods are case-insensitive - `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS` are all supported. You can also use absolute URLs, no base URL required. Add query params with `name=value` lines and headers with `Name: value` lines. Leave a blank line to start writing the body. Terminate the request with a line containing `###`.

```sh
reqsh> PATCH /users/1
.....> Content-Type: application/json
.....>
.....> {"name": "Alice"}
.....> ###
```

The response includes the request line (method + resolved URL), the HTTP version, status code (color-coded), response time, all response headers and the body. JSON responses are automatically pretty-printed.

```sh
PATCH https://api.example.com/users/1
HTTP/1.1 200 OK 142ms
content-type: application/json
date: Mon, 01 Jan 2024 00:00:00 GMT

{
  "id": 1,
  "name": "Alice"
}
```

Session state (base URL, headers, variables, saved requests) is persisted automatically to `~/.reqsh_state.json` and restored when you restart the REPL. Command history is saved to `~/.reqsh_history`.

## Variables

Store values with `var set` and reference them anywhere in your request using `{{name}}`. Variables are interpolated at request time.

```sh
reqsh> var set token eyJhbGciOiJIUzI1NiJ9
reqsh> var set host api.example.com
reqsh> GET /users/{{token}}
.....> Authorization: Bearer {{token}}
.....> ###
```

## Query Parameters

Add query parameters with `name=value` lines. Values are URL-encoded automatically.

```sh
reqsh> GET /users
.....> page=1
.....> limit=20
.....> ###
```

## Timeout

Set a default timeout for all requests in a session.

```sh
reqsh> timeout 10
```

You can also set a timeout when starting the REPL:

```sh
reqsh --timeout 30
```

## Clear Session

`clear` clears the terminal screen. To reset specific session state, use the scoped clear commands:

```sh
reqsh> header clear
reqsh> var clear
reqsh> req clear
reqsh> history clear
```

## Session Persistence

Your session state is automatically saved to `~/.reqsh_state.json` when you exit and restored when you start the REPL again.

## Save & Run

Save a request to session memory after executing it, then run it again instantly without retyping.

```sh
reqsh> GET /users/{{id}}
.....> ###
reqsh> req save get-user
saved request: get-user
reqsh> req run get-user
```