atagen e1974a7c1a update documentation for generate command and NixOS module

Rewrote nushell-integration.md to cover the three-strategy pipeline,
module wrapping, and the generate command. Simplified
runtime-completions.md. Added nixos.md with detailed explanation of
the build-time generation phases, module options, and troubleshooting.

2026-03-21 02:14:21 +11:00

2.5 KiB

Raw Blame History

Runtime completion caching

For commands not covered by build-time generation, inshellah can generate completions on first tab-press and cache the result.

Setup

Add an external completer to your nushell config that calls inshellah on cache miss:

# ~/.config/nushell/autoload/inshellah-completer.nu

const INSHELLAH_CACHE = ($nu.home-path | path join ".cache" "inshellah")

def inshellah-complete [spans: list<string>] {
    if ($spans | length) == 0 { return [] }
    mkdir $INSHELLAH_CACHE

    let max_depth = [($spans | length) 5] | math min
    mut cmd_spans = []

    for depth in (1..($max_depth)) {
        let candidate = ($spans | first $depth)
        let cache_key = ($candidate | str join "-")
        let cache_file = ($INSHELLAH_CACHE | path join $"($cache_key).nu")

        if ($cache_file | path exists) {
            $cmd_spans = $candidate
            break
        }

        try {
            let result = (run-external "inshellah" "help" ...($candidate) | complete)
            if $result.exit_code == 0 and ($result.stdout | str length) > 10 {
                $result.stdout | save -f $cache_file
                $cmd_spans = $candidate
                break
            }
        }
    }

    if ($cmd_spans | length) > 0 {
        let cache_key = ($cmd_spans | str join "-")
        let cache_file = ($INSHELLAH_CACHE | path join $"($cache_key).nu")
        if ($cache_file | path exists) { source $cache_file }
    }
}

Wire it in:

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

How it works

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

Nushell calls the completer with spans = ["docker", "compose", "up", "--"]
The completer tries progressively deeper prefixes as cache keys
On cache miss, runs inshellah help docker compose up
Caches the result; all subsequent completions are instant

First tab-press latency is ~100-200ms. Depth is capped at 5 levels.

Cache management

rm -rf ~/.cache/inshellah/          # Clear all
ls ~/.cache/inshellah/              # List cached
inshellah help docker run > ~/.cache/inshellah/docker-run.nu  # Regenerate one

When to use this vs build-time generation

The NixOS module (programs.inshellah.enable = true) handles most commands at build time. Runtime caching is useful for:

Commands installed outside the system profile (cargo, pip, npm, go)
Subcommand completions at arbitrary depth
Systems without the NixOS module

2.5 KiB Raw Blame History