jiq — Interactive JSON query tool with real-time output

Features

• Real-time query execution - See results as you type
• [EXPERIMENTAL] Context-aware autocomplete - Intelligent suggestions with JSON type information for fields and functions
• Function tooltip - Quick reference help for jq functions with examples
• Search in results - Find and navigate text in JSON output with highlighting
• Query history - Searchable history of successful queries
• Clipboard support - Copy query or results to clipboard (also supports OSC 52 for remote terminals)
• Floating error overlay - Syntax errors appear in a non-disruptive overlay
• VIM keybindings - VIM-style editing for power users
• [EXPERIMENTAL] Syntax highlighting - Colorized JSON output and jq query syntax (experimental)
• Stats bar - Shows result type and count (e.g., "Array [5 objects]", "Stream [3 values]")
• Flexible output - Export results or query string

Demo

Installation

Requirements

• jq - JSON processor (installation guide)

Install via Script (macOS/Linux)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/bellicose100xp/jiq/releases/latest/download/jiq-installer.sh | sh

Install via Homebrew (macOS)

brew install bellicose100xp/tap/jiq

Install via Cargo

cargo install jiq

Download Binary

Download pre-built binaries from GitHub Releases

git clone https://github.com/bellicose100xp/jiq
cd jiq
cargo build --release
sudo cp target/release/jiq /usr/local/bin/

Quick Start

# From file
jiq data.json

# From stdin
cat data.json | jiq
echo '{"name": "Alice", "age": 30}' | jiq
curl https://api.example.com/data | jiq

Usage

Workflow:

1. Start typing your jq query (begins in INSERT mode)
2. Use autocomplete suggestions for functions and fields (Tab to accept)
3. See results update in real-time
4. Press Shift+Tab to navigate results
5. Press Enter to output results, or Ctrl+Q to output query

VIM users: Press ESC to enter NORMAL mode for advanced editing.

Keybindings

Examples

Filter active users:

cat users.json | jiq
# Type: .users[] | select(.active == true)
# Press Enter to output results

Extract query for scripts:

cat data.json | jiq
# Experiment with: .items[] | select(.price > 100) | .name
# Press Ctrl+Q to get just the query string

Pipeline integration:

# Build query interactively, then reuse
QUERY=$(echo '{}' | jiq)  # Press Ctrl+Q after building query
echo $QUERY | xargs -I {} jq {} mydata.json

Tips

• Empty query shows original JSON (identity filter .)
• Invalid queries display Syntax Error message above input while preserving last successful output.
• Results auto-scroll to top when query changes

Configuration

jiq looks for a configuration file at ~/.config/jiq/config.toml (or the platform default location).

[clipboard]
# Clipboard backend: "auto" (default), "system", or "osc52"
# - auto: tries system clipboard first, falls back to OSC 52
# - system: use only OS clipboard (may not work in SSH/tmux)
# - osc52: use terminal escape sequences (works in most modern terminals over SSH)
backend = "auto"

Known Limitations

• Autocomplete - Suggestions are based on output visible in results area. Editing in the middle of a query may produce suboptimal or no suggestions.
• Syntax highlighting - Basic keyword-based only, does not analyze structure like tree-sitter.

Contributing

See CONTRIBUTING.md for guidelines on code architecture, testing, and pull requests.

License

Dual-licensed under MIT OR Apache-2.0