# 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:

```nu
# ~/.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:

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

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

```nu
$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](nixos.md)).

## cache management

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

```sh
# 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:

```sh
inshellah index /usr /usr/local
```