Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/reegnz/jq-zsh-plugin
jq zsh plugin
https://github.com/reegnz/jq-zsh-plugin
cli fzf jq shell zsh zsh-plugin zshell
Last synced: 30 days ago
JSON representation
jq zsh plugin
- Host: GitHub
- URL: https://github.com/reegnz/jq-zsh-plugin
- Owner: reegnz
- License: mit
- Created: 2020-01-29T16:53:31.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-08-23T08:46:32.000Z (3 months ago)
- Last Synced: 2024-09-28T08:20:50.419Z (about 1 month ago)
- Topics: cli, fzf, jq, shell, zsh, zsh-plugin, zshell
- Language: Shell
- Homepage:
- Size: 29.3 KB
- Stars: 316
- Watchers: 7
- Forks: 17
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# jq zsh plugin
Interactively build [jq](https://stedolan.github.io/jq/) expressions ([gojq](https://github.com/itchyny/gojq)
is also supported).
This zsh plugin gives you jq superpowers!
[Fish](https://fishshell.com/) users: you can use this friendly fork:
[rmartine-ias/jq-fish-plugin](https://github.com/rmartine-ias/jq-fish-plugin)
## Table of contents
- [Demos](#demos)
- [Installation](#installation)
- [Usage](#usage)
- [Key bindings](#key-bindings)
## Demos
### Interactive jq query construction
[](https://asciinema.org/a/IqAqzPS0ZgeaduQ3qs1B5ZgRI)
### Insert jq query in the middle of a pipeline
[](https://asciinema.org/a/9Q4Va21OzD2VTbHwntmLWGvm6)
## Installation
Besides [jq](https://stedolan.github.io/jq/), this plugin also requires
[fzf](https://github.com/junegunn/fzf#installation)
([a recent version](https://github.com/reegnz/jq-zsh-plugin/issues/19)) to be installed and available on your
PATH.
The following installation methods are proven to work:
- [Oh My Zsh](#oh-my-zsh)
- [zplug](#zplug)
- [Antigen](#antigen)
- [Zgen](#zgen)
### [Oh My Zsh](https://ohmyz.sh)
1. Clone the repository:
```sh
git clone https://github.com/reegnz/jq-zsh-plugin.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/jq
```
2. Add the plugin to the list of plugins for Oh My Zsh to load (inside `~/.zshrc`):
```sh
plugins=(
# other plugins...
jq
)
```
3. Start a new terminal session.
### [zplug](https://github.com/zplug/zplug)
```sh
zplug reegnz/jq-zsh-plugin
```
### [Antigen](https://github.com/zsh-users/antigen)
```sh
antigen bundle reegnz/jq-zsh-plugin
```
### [Zgen](https://github.com/tarjoilija/zgen)
```sh
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
[REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop)!)
- 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](https://github.com/itchyny/gojq) then you
can override the default jq command used by the plugin. Set the following environment variable:
```sh
JQ_REPL_JQ=gojq
```
## Internals
The project consists of the following components:
- a `jq.plugin.zsh` providing a
[user-defined zsh line-editor widget](https://zsh.sourceforge.io/Doc/Release/Zsh-Line-Editor.html),
utilizing the `jq-repl` command
- 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+`
See other suggestions on stackoverflow if the above one doesn't help you:
https://stackoverflow.com/q/196357/205318
Another option is to map to `ctrl+j` instead by putting this in your `.zshrc`:
```sh
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`:
```sh
JQ_ZSH_PLUGIN_EXPAND_ALIASES=0
```