jqi

An interactive, lightweight TUI (Terminal User Interface) for jq, built with Go.

jqi (jq-interactive) allows you to build and preview jq queries in real-time against JSON data. It features property autocompletion and instant feedback, making complex jq filters easier to craft.

Features

• Instant Preview: Live, debounced jq evaluation (300ms) with syntax highlighting.
• Smart Autocompletion: Floating, case-insensitive substring (contains) suggestions for JSON keys, even during nested navigation.
• Performance Diagnostics: Real-time query execution duration persistently displayed in the RESULT panel header (e.g. RESULT - 450µs).
• Persistent History: Searchable history panel (Leader+R) with MRU deduplication and portable JSON-L storage.
• Result Export: Save your transformed data directly to a file (Leader+S).
• Leader-based Navigation: Standardized shortcuts (CTRL+B) for panel switching, history, and more.
• Responsive Layout: Automatically scales panels and dynamically hides/reduces overlays (like the Help panel) to preserve grid integrity on small screens.
• Performance: Handles large JSON files with optimized rendering and truncation.

Keyboard Shortcuts

• Execution: CTRL+ENTER or CTRL+J (Manual trigger)
• Leader Key: CTRL+B followed by:
  • 1, 2, 3: Switch Focus (Query, Source, Result)
  • ?: Toggle Help panel
  • r: Open History Search panel
  • s: Export Result to file
  • y: Copy result to clipboard
  • q: Quit application
• Navigation:
  • TAB: Open/filter key suggestions (cycles forward through matches).
  • Shift+TAB: Cycle backward through key suggestions.
  • UP/DOWN: Move cursor in multiline queries (or navigate History/Suggestions).
  • ESC: Close Help/Suggestions/History.
  • CTRL+C: Force quit.

Themes

jqi supports dynamic visual themes to customize your TUI appearance.

Available Themes

• Aura (Default - Purple)
• Dracula (Pink)
• Nord (Ice Blue)
• Catppuccin (Lavender)
• Monokai (Lime Green)
• Tokyo Night (Blue)

Cycling Themes

While the application is running, you can cycle through themes on-the-fly using the Leader Key shortcut:

• Press CTRL+B followed by t.

Default Theme Environment Variable

You can set a default theme startup color using the JQI_THEME environment variable. The value is case-insensitive. If an invalid or unsupported theme name is provided, jqi gracefully falls back to the default aura theme:

# Start jqi with the Dracula theme
export JQI_THEME=dracula
go run ./cmd/jqi data.json

Roadmap

• Phase 1: Foundation - Basic TUI with real-time gojq evaluation.
• Phase 2: Autocompletion - Smart key suggestions and nested context fallback.
• Phase 3: UX Polish - Result scrolling, copy-to-clipboard, and syntax highlighting.
• Phase 4: Advanced History - Persistent JSON-L storage with MRU order and search panel.
• Phase 5: Workflow Enhancements - Export results to file and live auto-evaluation.

Development Setup

Prerequisites

• Go 1.24 or later.
• jq (optional, for comparison).

Installation

git clone https://github.com/user/jqi.git
cd jqi
go mod download
go run ./cmd/jqi data.json

Building from Source

Since jqi is built with pure Go, you can easily compile it for your platform or cross-compile it for others.

For your current platform:

go build -o jqi ./cmd/jqi

Cross-compilation:

Linux (amd64):

GOOS=linux GOARCH=amd64 go build -o jqi ./cmd/jqi

Windows (amd64):

GOOS=windows GOARCH=amd64 go build -o jqi.exe ./cmd/jqi

macOS (Apple Silicon):

GOOS=darwin GOARCH=arm64 go build -o jqi ./cmd/jqi

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.