jq zsh plugin

Interactively build jq expressions (gojq is also supported).

This zsh plugin gives you jq superpowers!

Fish users: you can use this friendly fork: rmartine-ias/jq-fish-plugin

Table of contents

• Demos
• Installation
• Usage
• Key bindings

Demos

Interactive jq query construction

Insert jq query in the middle of a pipeline

Installation

Besides jq, this plugin also requires fzf (a recent version) to be installed and available on your PATH.

The following installation methods are proven to work:

• Oh My Zsh
• zplug
• Antigen
• Zgen

Oh My Zsh

• Clone the repository:

git clone https://github.com/reegnz/jq-zsh-plugin.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/jq

• Add the plugin to the list of plugins for Oh My Zsh to load (inside ~/.zshrc):

plugins=(
	# other plugins...
	jq
)

• Start a new terminal session.

zplug

zplug reegnz/jq-zsh-plugin

Antigen

antigen bundle reegnz/jq-zsh-plugin

Zgen

zgen load reegnz/jq-zsh-plugin

Usage

• type out a command that you expect to produce json on its standard output
• press alt + j
• start typing jq expression and watch it being evaluated in real time (like a true

• use up/down and hit tab to select one of the suggestions
• or type out a jq query on your own
• press enter, and the jq expression is appended to your initial command!

Key bindings

Bringing up the jq query builder for a shell command: alt + j

During interactive querying, the following shortcuts can be used:

| Shortcut | Effect | | ------------------------ | ------------------------------------------------ | | ctrl-k or up | Navigate path queries | | ctrl-j or down | Navigate path queries | | tab | Select path query | | ctrl-p or shift-up | Scroll up | | ctrl-n or shift-down | Scroll down | | ctrl-alt-p | Scroll up half page | | ctrl-alt-n | Scroll down half page | | alt-up | Scroll up full page | | alt-down | Scroll down full page | | ctrl-r | Reload input | | ctrl-y | Yank selected path to clipboard (GNU/Linux only) |

gojq support

If you want to use an alternative jq implementation, like gojq then you can override the default jq command used by the plugin. Set the following environment variable:

JQREPLJQ=gojq

Internals

The project consists of the following components:

• a jq.plugin.zsh providing a

• a jq-repl command to interactively build jq expressions, utilizing fzf for its UI
• a jq-paths command to get all valid jq paths in the provided JSON document, used for suggesting paths.

Troubleshooting

MacOS: Pressing alt-j creates a ∆ symbol in iTerm2

You need to remap your alt-key to Esc+ in iTerm2:

• Cmd + , to enter preferences
• Go to Profiles
• select your profile from the pane on the left hand side
• go to the keys tab
• Set Left Option (⌥ ) Key to Esc+

Another option is to map to ctrl+j instead by putting this in your .zshrc:

bindkey ^j jq-complete

Disable expanding shell aliases

The plugin automatically expands shell aliases in a command before passing it to jq-repl. To disable, put the following line into your .zshrc:

JQZSHPLUGINEXPANDALIASES=0