jiq — Interactive JSON query tool with real-time output

Features

• Real-time query execution - See results as you type
• AI assistant - Get intelligent query suggestions, error fixes, and natural language interpretation
• Context-aware autocomplete - Smart field suggestions with nested path navigation and JSON type hints
• Snippet library - Save and reuse frequently used jq queries
• 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
• Mouse support - Full mouse interaction including click-to-focus, scrolling, and selecting items in popups
• Clipboard support - Copy query or results to clipboard (also supports OSC 52 for remote terminals)
• VIM keybindings - VIM-style editing for power users
• Syntax highlighting - Colorized JSON output and jq query syntax
• Stats bar - Shows result type and count (e.g., "Array [5 objects]", "Stream [3 values]")
• Flexible output - Export results or query string

Demo

With AI Assistant

Offline Mode (with built-in help)

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"

[ai]
# Enable AI assistant
# For faster responses, prefer lightweight models:
# - Anthropic: claude-haiku-4-5-20251001
# - OpenAI: gpt-4o-mini
# - Gemini: gemini-3-flash
enabled = true
# Provider: "anthropic", "openai", "gemini", or "bedrock"
provider = "anthropic"
# Character limit at which JSON schema and output samples are truncated (default: 100000)
# Larger values send more context to AI but increase token usage/costs
# Smaller values send less context and decrease token usage/costs
max_context_length = 100000

# ─────────────────────────────────────────────────────────
# 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"

# ─────────────────────────────────────────────────────────
# OpenAI
# ─────────────────────────────────────────────────────────
[ai.openai]
# Get your OpenAI API key from: https://platform.openai.com/api-keys
api_key = "sk-proj-..."
model = "gpt-4o-mini"

# ═════════════════════════════════════════════════════════
# OpenAI-Compatible APIs
# ═════════════════════════════════════════════════════════
# Any API that follows the OpenAI format can be used by setting provider = "openai"
# and configuring the base_url and model fields.
#
# Basic pattern:
# [ai.openai]
# base_url = "https://your-api-endpoint/v1"  # API endpoint URL
# api_key = "your-api-key"                   # Optional: only if required by provider
# model = "model-name"                       # Model identifier

# Example configurations:

# Ollama (local)
[ai.openai]
base_url = "http://localhost:11434/v1"
model = "llama3"

# LM Studio (local)
[ai.openai]
base_url = "http://localhost:1234/v1"
model = "local-model"

# x.ai Grok
[ai.openai]
api_key = "your-xai-api-key"
base_url = "https://api.x.ai/v1"
model = "grok-4-fast-non-reasoning"

# ─────────────────────────────────────────────────────────
# Gemini
# ─────────────────────────────────────────────────────────
[ai.gemini]
# Get your API key from: https://aistudio.google.com/apikey
api_key = "AIza..."
# Gemini model to use (e.g., "gemini-3-flash-preview", "gemini-1.5-flash")
model = "gemini-3-flash-preview"

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

Known Limitations

• Autocomplete - Editing in the middle of a query falls back to root-level 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