nu_plugin_skim

This is a Nushell plugin that adds integrates the skim fuzzy finder.

The regular sk executable filters lines of text, but the sk command added by this plugin can filter Nushell's structured data.

Installing

Install the crate using:

> cargo install nu_plugin_skim

Then register the plugin using (this must be done inside Nushell):

> plugin add ~/.cargo/bin/nu_plugin_skim

Usage

Pipe the input of any Nushell command into sk:

> ps | sk --format {get name} --preview {}

This will open the skim TUI, allowing you to select an item from the stream:

                    │╭─────────┬─────────────╮            1/9
                    ││ pid     │ 4223        │
                    ││ ppid    │ 3944        │
> /usr/bin/nu       ││ name    │ /usr/bin/nu │
  nu                ││ status  │ Running     │
  nu                ││ cpu     │ 28.78       │
  nu                ││ mem     │ 37.4 MiB    │
  nu                ││ virtual │ 1.4 GiB     │
  nu                │╰─────────┴─────────────╯
  6/258         5/0 │
> 'nu               │

The item will be returned as the same structured Nushell type that was fed into sk:

> ps | sk --format {get name} --preview {}
╭─────────┬─────────────╮
│ pid     │ 4223        │
│ ppid    │ 3944        │
│ name    │ /usr/bin/nu │
│ status  │ Running     │
│ cpu     │ 28.57       │
│ mem     │ 37.8 MiB    │
│ virtual │ 1.4 GiB     │
╰─────────┴─────────────╯

Of course, the result of the command can be piped into another command:

> ps | sk --format {get name} --preview {} | kill $in.pid

Notable flags

nu_plugin_skim aims to repliacte skim's sytnax, but there are some differences to better integrate with Nushell:

• --multi / -m - this flag works exactly the same as in the regular skim, but unlike the regular skim that always returns text - here sk returns structured Nushell data, and this flag changes the type of that data. Without it, the chosen item is returned as is. With it, it gets returned as a list (even if the user only chooses a single item)

  > seq 1 10 | sk | describe
  int
  > seq 1 10 | sk -m | describe
  list<int> (stream)
  

• --format - this is a flag that the regular skim does not have. It receives a Nushell closure, and pipes the items through that closure before showing them as user selectable rows.

  If the closure returns a complex Nushell data type, it'll be formatted in a notation similar to Nushell's debug command

  Note that in skim one would use --with-nth for a similar purpose - but the syntax and usage are different enough to warren a different name.

• --preview - unlike the regular skim, where --preview accepts a string, here --preview accepts a Nushell closure. The item under the cursor will get piped into the closure and the result will be displayed inside the preview window.

  If the closure returns a complex Nushell data type, it'll be formatted into a table.

  To display the item as is, use the empty closure --preview {}.

• --bind - unlike regular sk that recieves bindings as a comma-separated list of colon-seperated key-values (e.g. sk --bind alt-s:down,alt-w:up), here the bindings are given as a record (e.g. sk --bind {alt-s: down, alt-w: up})

• --expect - unlike regular sk that receives actions as comma-specified list of keys (e.g. sk --expect ctrl-v,ctrl-t,alt-s), here the actions are given as a list of strings (e.g. sk --expect [ctrl-v, ctrl-t, alt-s])

  When this flag is given (even with an empty list), the result will be a record with an action field that contains the action (or null, if regular Return was used) and a selected field that contains the selected item (or a list of them, if -m / --multi was used)

• --tiebreak - unlike regular sk that receives actions as comma-specified list of criteria, here the criteria are given as a list of strings.

• --algo and --case - in regular sk setting them to an unsupported value will fall back to the default. Here it'll raise an error.

• --pre-select-items - unlike regular sk where it receives a newline-seperated list, here it receives a Nushell list.