- 📟 Tired of UI HTTP clients forcing sign-in just to create a workspace (and collect your email)?
- ⏳ Waiting forever for UI clients to load features and plugins you don’t need?
- 🗄️ Struggling to find past requests from months ago?
- 🔬 Searching how to change the request method in
curlbecause you rarely use it? - 📋 Working with modern JSON HTTP APIs?
- 💨 Want to write quick smoke tests for your API?
- 🔗 Need a scripting tool to chain requests together?
jsonr is a simple CLI tool for interacting with json http api's and writing
simple smoke tests. It's available from your terminal anytime when you need it
(so you don't need to switch context) and it's not aimed to be an ultimate
solution for everything. That's why it's so simple to use. No more need to
browse lots of documentation about tons of features that you don't need. 5
minutes and you are ready to send any requests.
1. Create .http files (store them in your git repository to share with other developers)
POST https://api.example.com/users
Authorization: Bearer @@apiKey@@
{
"name": "John Doe",
"email": "[email protected]"
}
2. Use simple command to send request and set input variable
jsonr create-user.http -i "apiKey: myApiKey123"3. Initialize jsonr config file
jsonr config --initThis creates a jsonr-config.json file with environment configurations:
{
"environments": {
"prod": {
"inputVariables": {
"baseUrl": "https://prod.api.example.com"
},
"secrets": "~/.secrets/jsonr-prod.json"
}
}
}The secrets file (~/.secrets/jsonr-prod.json) stores sensitive values
separately:
{
"apiKey": "prod_ApiKey123"
}4. Update .http file to use more variables
POST @@baseUrl@@/users
Authorization: Bearer @@apiKey@@
{
"name": "John Doe",
"example": "[email protected]"
}
5. Use environment from config when sending request
jsonr create-user.http -e prod6. Skip .http files and send request directly
(Content-Type: application/json header is added automatically)
jsonr -m POST -h 'Authorization: myApiKey123' -b '{"name": "John Doe", "email": "[email protected]"}' https://api.example.com/users7. Write simple smoke tests with response status code assertion (text assertion also available)
jsonr create-user.http -e prod -s 2018. Programmatic Usage - chaining requests
You can use jsonr programmatically in your Javascript scripts to chain
multiple requests and handle responses in code.
To get started, generate a template script:
jsonr run --init https://api.example.com/usersThis creates a jsonr-script.js file that you can customize. Here's an example
that creates a user and then posts an order using the returned user ID:
// Create a new user
const userResponse = await jsonr("create-user.http", {
inputVariables: {
name: "John Doe",
email: "[email protected]",
},
status: 201,
});
const userId = userResponse.body.id;
console.log(`Created user with ID: ${userId}`);
// Create an order for the newly created user
const orderResponse = await jsonr("https://api.example.com/orders", {
method: "POST",
body: {
userId,
items: ["product-123", "product-456"],
total: 99.99,
},
status: 201,
});
console.log(`Order created with ID: ${orderResponse.body.id}`);Run your script with:
jsonr run jsonr-script.jsThe jsonr function is automatically available in scripts run with
jsonr run - no import needed!
For complete documentation of all available options and detailed usage
instructions run jsonr --help or view the help text at:
https://sobanieca.github.io/jsonr/src/commands/help.js
This URL is particularly useful when working with AI assistants or LLMs - you can provide this link to give them comprehensive information about jsonr's capabilities and command-line options.
Prerequisites
Deno runtime environment
https://deno.com
deno install -g --allow-write --allow-net --allow-read --allow-env=HOME,USERPROFILE -f -r -n jsonr jsr:@sobanieca/jsonrPermissions:
--allow-write- Required for writing response bodies to files (-oflag) and creating config/script files--allow-net- Required for making HTTP requests--allow-read- Required for reading.httpfiles and config files--allow-env=HOME,USERPROFILE- Required for findingjsonr-config.jsonfiles in your home directory hierarchy
If you don't have Deno installed, you can install the pre-compiled binary with a single command:
curl -fsSL sobanieca.github.io/jsonr/install.sh | bashThis script automatically detects your OS and architecture (Linux/macOS,
x64/arm64) and installs the appropriate binary to /usr/local/bin.
To install to a custom location:
curl -fsSL sobanieca.github.io/jsonr/install.sh | INSTALL_DIR=~/bin bashDownload the latest pre-compiled binary for your operating system from the releases page:
Example for Linux x64:
curl -L -o jsonr https://github.com/sobanieca/jsonr/releases/latest/download/jsonr-linux-x64
chmod +x jsonr
sudo mv jsonr /usr/local/bin/Available binaries: jsonr-linux-x64, jsonr-linux-arm64, jsonr-macos-x64,
jsonr-macos-arm64
Use jsonr update command and follow presented instructions to update.
- It is recommended to wrap URLs with quotes to avoid shell conflicts:
jsonr "https://api.example.com/users?filter=active&sort=name"- Working with Large Responses
When dealing with large response bodies, you can pipe the output to grep to
filter specific content:
# Search for a specific property in a large JSON response
jsonr my-api-request.http | grep "someProperty" -C 10
# Extract specific fields from JSON responses
jsonr my-api-request.http | grep -E '"(id|name|email)"' -C 2- SSL Certificate Issues
If your requests are failing due to certificate validation errors (and you trust
target server) you can run temporary command like:
deno run --allow-net --unsafely-ignore-certificate-errors jsr:@sobanieca/jsonr ...
It will display warning about disable ssl verification, but you should be able
to perform requests. If you work frequently with such unsafe servers you can
consider introducing jsonr-unsafe sitting next to your main jsonr instance:
deno install -n jsonr-unsafe -g -f -r --unsafely-ignore-certificate-errors --allow-net --allow-read --allow-write --allow-env=HOME,USERPROFILE jsr:@sobanieca/jsonr
- If you want to disable colors (at least for main log messages), you can use:
NO_COLOR=1 jsonr ...If you want to implement/request new features you are more than welcome to
contribute. Please keep in mind that this tool is supposed to be super simple to
use and cover ~80% of use cases for playing around with JSON HTTP API's.
Instructions (jsonr --help) for this tool should be possible to read in less
than 5 minutes. If more features will be added this may be hard to achieve.