DEV Community

Cover image for You already have .http files — I built a zero-dependency CLI to run them outside VS Code
benjamin
benjamin

Posted on

You already have .http files — I built a zero-dependency CLI to run them outside VS Code

#showdev #webdev #api #cli

If you use VS Code, you probably have .http files sitting in your repo — the ones the REST Client extension runs when you click "Send Request". They're great: requests live next to your code, in version control, in plain text.

Then you want to run one from a terminal, or in CI, and... you can't. The extension only works inside the editor. So your options become:

  • Fire up Postman / Insomnia — a GUI app and an account, to send one GET.
  • Switch to Hurl — excellent, but it uses its own .hurl format; your existing .http files don't run in it.
  • Use httpyac — it does run .http files, but pulls in dozens of dependencies.
  • Hand-translate the request into a wall of curl -H flags. Again.

I wanted to run the files I already have. So I built runhttp: it runs your .http files (REST Client format) from the command line, with zero dependencies.

npx runhttp api.http
Enter fullscreen mode Exit fullscreen mode

Given this file:

@base = https://api.example.com
@token = {{$env API_TOKEN}}

### Get the current user
GET {{base}}/me
Authorization: Bearer {{token}}
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

you get:

GET https://api.example.com/me   # Get the current user
  200 OK · 142ms · application/json · 318 B
  {
    "id": 7,
    "name": "Ada Lovelace"
  }
Enter fullscreen mode Exit fullscreen mode

What it does

  • Runs every request in the file, or just one: -n 2, or --name "Get the current user".
  • @variables and {{placeholders}}, plus {{$env TOKEN}} to pull secrets from the environment (so tokens never get committed) and --var key=value to override from the CLI.
  • Follows redirects, pretty-prints JSON, --list to see what's in a file, --json for machine-readable output, -i to include response headers.
  • An undefined variable is an error — a {{typo}} never gets silently sent to the wire.

Built for scripts and CI 

exit 0   every request came back < 400
exit 1   some request returned an HTTP status >= 400
exit 2   parse error, connection failure, or bad usage
Enter fullscreen mode Exit fullscreen mode 
runhttp smoke.http && echo "all endpoints healthy"
Enter fullscreen mode Exit fullscreen mode

Scope, on purpose

It handles the everyday .http: variables, headers, bodies, multiple requests per file, redirects. It deliberately does not do gRPC/WebSocket/GraphQL transports or response assertions — if you need those, httpyac and Hurl are great. runhttp is the small, dependency-free one for the 90% case, and the Node and Python ports are behavior-identical: same flags, same exit codes.

Install 

npx runhttp api.http       # Node >= 18
pip install runhttp        # Python >= 3.8
Enter fullscreen mode Exit fullscreen mode

What do you reach for when you need to run a saved request outside the editor — Postman, curl, an extension, something else? And is sticking to the REST Client .http format the right call, or do you wish there were one universal format for this?

Top comments (0)