Completion on nushell¶

This is a recording of a real nushell session — the external completer wired the way the next section describes, Tab opening nushell's completion menu with descriptions, a prefix completing. Regenerated from a live shell on every docs build, so it cannot drift from what your terminal will do:

Install¶

fm --install-completion nushell     # `nu` works too

This writes the hook to $XDG_DATA_HOME/fm/completion.nu and appends one guarded source line to the config nushell itself reports ($nu.config-path). The hook registers an external completer — and it wraps whatever external completer you already run (carapace, a fish bridge, …) instead of replacing it: fm lines are answered by footman, every other command passes through untouched. Running the installer twice changes nothing.

nushell is the one shell without a session-only --setup-completion form: the hook mutates $env.config, which an eval can't apply. Install and exec nu (or open a new shell) instead.

What you get¶

The hook returns {value, description} records, so nushell's completion menu shows each task and group with its one-line docstring in the description column, filtered as you type:

$ fm <TAB>
build      compile and bundle
deploy     ship to an environment
docs       Documentation

Colours and appearance¶

The menu is nushell's completion_menu, styled from your config (config nu opens it). Override the menu entry to restyle it — this is plain nushell configuration, nothing footman-specific:

$env.config.menus ++= [{
    name: completion_menu
    only_buffer_difference: false
    marker: "| "
    type: {
        layout: columnar        # or `list` for one candidate per row
        columns: 4
        col_width: 20
        col_padding: 2
    }
    style: {
        text: green                       # candidate text
        selected_text: green_reverse      # the highlighted candidate
        description_text: yellow          # the docstring column
        match_text: { attr: u }           # matched characters (underlined)
        selected_match_text: { attr: ur }
    }
}]

Styles take named colours (green, yellow_bold), hex strings ("#ffb86c"), or records with fg/bg/attr (u underline, r reverse, b bold). A layout: list menu gives the description column the most room; columnar packs more candidates per screen.

Uninstall¶

fm --uninstall-completion nushell

Removes the script and the source line from your nushell config. Your previous external completer (if the hook wrapped one) is back in sole charge on the next shell start.