---
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
```