Using inshellah completions in nushell

inshellah generates nushell completions from three sources (in priority order):

Native generators — programs that can emit nushell completions directly
Manpages — groff/troff manpage parsing
--help output — parsing help text as a fallback

Each command gets a module-wrapped .nu file suitable for nushell's autoload.

Quick start

Generate completions for a single command:

# From a manpage
inshellah manpage /usr/share/man/man1/git.1.gz > git.nu

# From --help output (recursively resolves subcommands)
inshellah help rg > rg.nu

# Without recursive resolution (for on-demand / runtime caching)
inshellah help --iterative rg > rg.nu

# Pipe --help text directly
curl --help | inshellah parse-help curl > curl.nu

Full system generation

The generate command runs all three strategies across an entire system:

mkdir -p ~/completions
inshellah generate /usr/bin /usr/share/man -o ~/completions

This produces one .nu file per command in the output directory. Each file is module-wrapped:

module git-completions {
export extern "git" [
    --all(-a)
    --verbose(-v)
    ...
]
}

use git-completions *

Programs that provide their own nushell completion generators (e.g. niri completions nushell) are detected automatically and their native output is used instead of parsing.

NixOS module

Enable automatic completion generation at system build time:

{
  imports = [ ./path/to/inshellah/nix/module.nix ];
  programs.inshellah.enable = true;
}

This runs inshellah generate during the system profile build, producing per-command .nu files in nushell's vendor autoload path. Completions are available immediately with no manual configuration.

The module uses a three-phase pipeline:

Scans executables in $out/bin for native nushell completion support
Parses manpages from $out/share/man (man1 and man8 sections)
Falls back to --help parsing for unmanpaged executables

All phases run with ELF binary scanning to skip executables that don't contain help flags, parallel execution scaled to available cores, and 200ms timeouts.

Loading completions manually

Option A: Autoload directory (recommended)

Nushell automatically sources .nu files from vendor autoload paths (discovered via $XDG_DATA_DIRS) and ~/.config/nushell/autoload/.

mkdir -p ~/.config/nushell/autoload
inshellah generate /usr/bin /usr/share/man -o ~/.config/nushell/autoload

Option B: Batch to stdout

For simpler setups, the manpage-dir command writes all completions to stdout (without module wrapping):

inshellah manpage-dir /usr/share/man > ~/.config/nushell/autoload/completions.nu

What gets generated

Each command produces a nushell extern block with flags, parameter types, and descriptions extracted from the source:

export extern "rg" [
    --regexp(-e): string            # A pattern to search for
    --file(-f): path                # Search for patterns from the given file
    --count(-c)                     # Only show the count of matching lines
    --color: string                 # Controls when to use color
    --max-depth: int                # Limit the depth of directory traversal
]

Subcommand manpages (e.g. git-commit.1) are detected via SYNOPSIS parsing and generate the correct nushell name (git commit not git-commit).

Nushell built-in commands (ls, cd, mv, etc.) are excluded since nushell provides its own completions for these.

3.5 KiB Raw Blame History