jiq — Interactive JSON query tool with real-time output

Features

• Real-time query execution — results update as you type
• Output — query or result
• AI assistant — error fixes, query optimizations, and a chat that remembers the conversation
• Context-aware autocomplete — schema-aware fields with type hints, plus value suggestions in comparisons
• Save result to file
• Snippet library — save and reuse jq queries
• Search in results — find and navigate matches in the output
• Query history — searchable history of successful queries
• VIM keybindings — full motions, operators, text objects
• Mouse support — click, scroll, drag-select
• Syntax highlighting — colorized JSON output and jq query
• Themes — light or dark color scheme

Demo

Autocompletion

With AI Assistant

Snippets

Search

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

# Smart picker: Clipboard or Interactive Paste
jiq

# Force a specific source, skip the picker
jiq --clipboard
jiq --paste

Usage

Workflow:

1. Start typing your jq query
2. Use autocomplete suggestions for functions and fields
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 above input while preserving last successful output; press Ctrl+E for a plain-language explanation and fix hint (jq's raw error, rewritten; works with jq 1.6+).

• Results auto-scroll to top when query changes

• Non-ASCII keys (CJK, emoji, accented Latin, hyphens, digit-start) must use bracket notation or quoted-dot notation — jq's .field shorthand only accepts ASCII identifiers. jiq's autocomplete emits bracket notation by default:

  .["名前"]      ✓ works (bracket notation, used by autocomplete)
  ."名前"        ✓ works (quoted-dot, valid alternative)
  .名前           ✗ jq syntax error
  

  Same rule applies to .["café"], .["👋"], .["中文"], .["日本語"], etc.

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"

[theme]
# Color theme: "auto" (default), "light", or "dark"
# - auto: detect the terminal background at startup, fall back to dark
# - light: force the light palette
# - dark: force the dark palette (the classic Galaxy theme)
mode = "auto"

[tooltip]
# Auto-show the function tooltip as the cursor lands on a known jq function (default: true)
auto_show = true

[query]
# Delay in milliseconds between the last keystroke and the jq re-run (default: 150)
debounce_ms = 150

[history]
# Maximum entries kept in the persisted query history (default: 1000)
max_entries = 1000

[save]
# Initial filename in the save dialog; supports {timestamp}, {cwd}, and ~ (default: "jiq-{timestamp}.json")
default_pattern = "jiq-{timestamp}.json"

[autocomplete]
# Number of array elements sampled to discover field suggestions for arrays where fields
# differ across elements. Increasing this may improve suggestions but adds a performance cost.
# Range: 1 - 1000 (default: 10)
array_sample_size = 10

[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
# Extra instructions appended to every AI prompt (optional; never replaces the built-in prompt)
extra_instructions = ""
# Whole-request timeout in seconds; 0 disables it (default: 120)
request_timeout_secs = 120

# ─────────────────────────────────────────────────────────
# 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"
# Optional reasoning effort for Claude 4.6+: "low", "medium", "high", "xhigh", "max"
effort = "high"
# Optional 1M-token context window beta (Claude Sonnet 4/4.5); raise max_context_length too
context_1m = false

# ─────────────────────────────────────────────────────────
# OpenAI
# ─────────────────────────────────────────────────────────
[ai.openai]
# Get your OpenAI API key from: https://platform.openai.com/api-keys
api_key = "sk-proj-..."
model = "gpt-4o-mini"
# Optional reasoning effort (sent as reasoning_effort, only when set):
# "minimal", "low", "medium", "high", "xhigh", "max"
effort = "medium"

# ═════════════════════════════════════════════════════════
# 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"
# Optional thinking level for Gemini 3+: "minimal", "low", "medium", "high"
# ("xhigh"/"max" clamp to "high"; omit for Gemini 2.5 models)
effort = "medium"

# ─────────────────────────────────────────────────────────
# AWS Bedrock
# ─────────────────────────────────────────────────────────
[ai.bedrock]
region = "us-east-1"
# Claude and OpenAI models both work via the Converse API (e.g. "us.openai.gpt-5.6-sol")
model = "global.anthropic.claude-haiku-4-5-20251001-v1:0"
profile = "default"  # Optional: AWS profile name (uses default credential chain if omitted)
# Optional reasoning effort, shaped per model family: "low", "medium", "high", "xhigh", "max"
effort = "high"
# Optional 1M-token context window beta (Claude Sonnet 4/4.5); raise max_context_length too
context_1m = false

Known Limitations

• Autocomplete - Editing in the middle of a query falls back to root-level suggestions; for arrays, a configurable number of elements are sampled to build field suggestions (default: 10, configurable via array_sample_size in [autocomplete] config section).
• Syntax highlighting - Basic keyword-based only, does not analyze structure like tree-sitter.

Troubleshooting

When reporting a bug, re-run with debug logging and attach /tmp/jiq-debug.log:

jiq --debug data.json        # or: JIQ_DEBUG=1 jiq data.json

Contributing

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

License

Dual-licensed under MIT OR Apache-2.0