inshellah/doc/runtime-completions.md

runtime completion resolution

the complete command has built-in on-the-fly resolution: when a command is not found in the index, it falls back to running --help, caches the result, and returns completions immediately. this means commands installed outside the system profile (via cargo, pip, npm, go, etc.) get completions on first tab-press with no manual setup.

how it works

when you type docker compose up --<TAB>:

1. nushell calls inshellah complete docker compose up --
2. inshellah looks up the index for the longest matching prefix
3. if found, it fuzzy-matches flags and subcommands against the partial input
4. if not found, it locates the binary in $PATH, runs --help, recursively resolves subcommands, caches the results in the user directory ($XDG_CACHE_HOME/inshellah), and returns completions. if --help produces rendered manpage output, the raw manpage source is located and parsed instead for richer results

all subsequent completions for that command are instant (served from cache).

setup

the completer works with no extra configuration beyond the basic setup:

# ~/.config/nushell/config.nu
$env.config.completions.external = {
    enable: true
    completer: {|spans|
        inshellah complete ...$spans
        | from json
    }
}

with the nixos module, the installed wrapper has the system paths hardcoded — no extra flags needed. the same snippet works:

$env.config.completions.external = {
    enable: true
    completer: {|spans|
        inshellah complete ...$spans
        | from json
    }
}

to manually specify system dirs, use colon-separated --dir:

$env.config.completions.external = {
    enable: true
    completer: {|spans|
        inshellah complete ...$spans --dir $"($env.XDG_CACHE_HOME)/inshellah:/run/current-system/sw/share/inshellah"
        | from json
    }
}

system directories (paths after the first in --dir) enable manpage-based fallback: when a command's --help delegates to man, the completer looks for the raw manpage in the sibling share/man directory (e.g. share/inshellah → share/man). if no system dirs are given, it falls back to man -w to locate the manpage.

or use the snippet option provided by the flake module (see nixos.md).

cache management

the user cache lives at $XDG_CACHE_HOME/inshellah (typically ~/.cache/inshellah).

# list cached commands
inshellah dump

# view cached data for a command
inshellah query docker

# clear cache
rm -rf ~/.cache/inshellah/

# re-index from a prefix
inshellah index /usr --dir ~/.cache/inshellah

when to use this vs build-time indexing

the nixos module (programs.inshellah.enable = true) handles system packages at build time. runtime resolution covers:

• commands installed outside the system profile (cargo, pip, npm, go)
• subcommand completions at arbitrary depth
• systems without the nixos module

for upfront indexing on non-nixos systems:

inshellah index /usr /usr/local