jiq — Interactive JSON query tool with real-time output

Features

• Real-time query execution - See results as you type
• [EXPERIMENTAL] AI assistant - Get intelligent query suggestions, error fixes, and natural language interpretation
• [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

Navigation

Editing

Operators (delete/change + motion)

Undo/Redo

Note: Search is case-insensitive.

Successful queries are saved to your platform's application data directory:

• Linux: ~/.local/share/jiq/history
• macOS: ~/Library/Application Support/jiq/history
• Windows: %APPDATA%\jiq\history

Quick Cycling (without opening popup):

History Search Popup:

The AI assistant analyzes your query and data to provide intelligent suggestions for fixing errors, improving queries, or interpreting natural language.

Requires configuration (see Configuration section below)

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"

[ai]
# Enable AI assistant
# Prefer faster models like claude haiku or open ai mini or gemini flash
enabled = true
# Provider: "anthropic" (default), "openai", or "bedrock"
provider = "anthropic"

[ai.anthropic]
# Get your API key from: https://console.anthropic.com/settings/keys
api_key = "your-api-key-here"
model = "claude-haiku-4-5-20251001"

[ai.openai]
# Get your API key from: https://platform.openai.com/api-keys
api_key = "sk-proj-..."
# OpenAI model to use (e.g., "gpt-4o-mini", "gpt-4o")
model = "gpt-4o-mini"

[ai.bedrock]
region = "us-east-1"
model = "global.anthropic.claude-3-haiku-20240307-v1:0"
profile = "default"  # Optional: AWS profile name (uses default credential chain if omitted)

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