qjp: An Interactive Command-Line Tool for JSON and Text Filtering

development-tools

qjp (quick JSON picker) is a powerful interactive command-line utility for filtering and selecting JSON objects or plain text lines. Enhance your shell scripts with real-time search, multi-selection, and flexible output options from stdin or files.

qjp (quick JSON picker) is an interactive command-line utility designed for filtering and selecting JSON objects or plain text lines. It offers a fast, pipeline-friendly method to integrate interactive menus into your shell scripts.

Feed qjp a JSON array via stdin or from a file, optionally specifying which field(s) to display. It will then present an interactive list. You can type to filter, use arrow keys to navigate, press Ctrl+Space for multi-selection, and press Enter to output your selection—either as complete JSON objects or specific field values.

Features

  • Interactive filtering and selection for JSON objects and plain text lines.
  • Granular control over displayed content and output format.
  • Real-time, as-you-type filtering.
  • Multi-select functionality using Ctrl+Space.
  • Input support from stdin or direct file reads.
  • Flexible display of single or multiple attributes during browsing.
  • Table mode for vertically aligned, readable attribute display.
  • Line mode for plain text input, mimicking percol behavior.
  • Optional line truncation for long content; otherwise, lines wrap.
  • Output options: full selected objects or specific attributes.
  • Arrays and objects are output as single-line JSON.

Installation

Download Pre-built Binaries

Download the binary for your platform directly from the Releases page.

Quick Install Scripts

Linux (x86_64)

sudo curl -L -o /usr/local/bin/qjp "https://github.com/plainas/qjp/releases/latest/download/qjp-linux-x86_64"
sudo chmod +x /usr/local/bin/qjp

Linux (ARM64 / aarch64)

sudo curl -L -o /usr/local/bin/qjp "https://github.com/plainas/qjp/releases/latest/download/qjp-linux-arm64"
sudo chmod +x /usr/local/bin/qjp

Linux (ARMv7)

sudo curl -L -o /usr/local/bin/qjp "https://github.com/plainas/qjp/releases/latest/download/qjp-linux-armv7"
sudo chmod +x /usr/local/bin/qjp

macOS (Intel)

sudo curl -L -o /usr/local/bin/qjp "https://github.com/plainas/qjp/releases/latest/download/qjp-darwin-x86_64"
sudo chmod +x /usr/local/bin/qjp

macOS (Apple Silicon)

sudo curl -L -o /usr/local/bin/qjp "https://github.com/plainas/qjp/releases/latest/download/qjp-darwin-arm64"
sudo chmod +x /usr/local/bin/qjp

Install the manpage on your system (optional)

sudo curl -L -o /usr/local/share/man/man1/qjp.1 "https://github.com/plainas/qjp/releases/latest/download/qjp.1"
sudo mandb

Build from Source

go build -o qjp

Usage

qjp [filename] [-d display-attribute] [-o output-attribute] [-s separator] [-t] [-T] [-l] [-a]
qjp [-d display-attribute] [-o output-attribute] [-s separator] [-t] [-T] [-l] [-a] < input

Arguments

  • filename: (optional) Specifies a JSON file to read (or plain text with -l). If not provided, qjp reads from stdin.
  • -d <attribute>: Displays specific attribute(s) in the list (can be used multiple times for multiple attributes).
  • -o <attribute>: Outputs a specific attribute from the selected object(s). Arrays and objects are output as single-line JSON.
  • -s <separator>: Defines the separator for multiple display attributes (default: " - ").
  • -t: Truncates long lines instead of wrapping them.
  • -T: Activates Table mode, aligning attributes in columns for better readability.
  • -l: Enables Line mode, treating input as plain text lines (similar to percol). Cannot be used with -d, -o, -s, -t, -T, or -a.
  • -a: Displays all attributes by automatically discovering and presenting all unique attributes from all objects in alphabetical order. Cannot be used with -d or -l. Particularly useful with -T for a structured overview.
  • -h, --help: Shows the help message.

Note: Input can be provided via stdin or a filename, but not both. For detailed usage information, see the man page: man ./qjp.1 or, after installation, man qjp.

Keyboard Controls

  • Type: Filters the list in real-time.
  • Up/Down arrows: Navigate through the list.
  • Ctrl+Space: Toggles selection (multi-select mode – selected items are shown with a green background).
  • Enter: Confirms selection (outputs selected item(s)).
  • Backspace: Deletes the last character from the filter.
  • Esc or Ctrl+C: Exits without selecting.

Examples

The examples below use the sample cars.json included in the source.

Read from file and display entire objects. Outputs entire objects, one per line.

qjp cars.json

Read from file and display only car models when selecting.

qjp cars.json -d model

Display car models and output only the ID.

qjp cars.json -d model -o id

Display multiple attributes (year, make, and model) with the default separator " - " and output price.

qjp cars.json -d year -d make -d model -o price

Display multiple attributes with a custom separator.

qjp cars.json -d model -d year -s "|"

Display multiple attributes in table mode (aligned columns).

qjp cars.json -d make -d model -d year -T

Display all attributes (discovers all keys automatically).

qjp cars.json -a

Display all attributes in table mode. Useful for quickly inspecting the contents of a file.

qjp cars.json -a -T

Truncate long lines. This can be useful when working with large objects.

qjp cars.json -t

Read from stdin (traditional pipe usage).

cat cars.json | qjp -d model

Display car make and model and output the price.

cat cars.json | qjp -d make -d model -o price

Line mode: select from plain text lines (like percol).

ls -la | qjp -l
cat file.txt | qjp -l
ps aux | qjp -l

Advanced Examples

Select one of Linus Torvalds' GitHub repositories and output its number of stars.

curl -s "https://api.github.com/users/torvalds/repos" | qjp -d name -d description -o stargazers_count

A country picker that displays common names and outputs two-letter country codes.

curl -s "https://www.apicountries.com/countries" | qjp -d name -o alpha2Code

Minimal lobste.rs feed on your terminal.

curl -s "https://lobste.rs/hottest.json" | qjp -d title -o url | xargs lynx

Get the ID of a Docker container by name, useful for feeding into other commands.

docker ps --format json | jq -s '.' | qjp -d Names -d Status -o ID

A quick way to find and install npm packages.

npm search --json typescript | qjp -d name -d description -o name | xargs npm install

Pick a cryptocurrency and retrieve its details from CoinGecko.

curl -s "https://api.coingecko.com/api/v3/coins/markets?vs_currency=usd&order=market_cap_desc&per_page=50" | qjp -d name -d symbol -d current_price | jq .

Development

Publishing a New Release

To create a new release, create a tag starting with v:

git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0

The GoReleaser workflow will automatically build binaries for all supported platforms and create a GitHub release.

Cross-compilation

To build for a specific platform locally:

Linux AMD64

GOOS=linux GOARCH=amd64 go build -o qjp-linux-amd64

macOS ARM64 (Apple Silicon)

GOOS=darwin GOARCH=arm64 go build -o qjp-darwin-arm64

Windows AMD64

GOOS=windows GOARCH=amd64 go build -o qjp-windows-amd64.exe