atagen/inshellah
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

riir

Browse source
This commit is contained in:
atagen 2026-05-19 23:32:51 +10:00
parent da4bc139eb
commit 8299fbbbbf
49 changed files with 10514 additions and 5482 deletions
Download patch file Download diff file Expand all files Collapse all files

55
doc/runtime-completions.md
View file

@ -1,30 +1,31 @@
# 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.
when a command isn't in the static index yet, `inshellah complete`
runs `--help` (or `-h`) on the binary, caches the result in the user
directory, and returns completions immediately. tab-completion just
works for tools installed outside the indexed prefixes — via cargo,
pip, npm, go, etc.
## how it works
when you type `docker compose up --<TAB>`:
typing `docker compose up --<TAB>`:
1. nushell calls `inshellah complete docker compose up --`
2. inshellah looks up the index for the longest matching prefix
2. inshellah looks up the longest matching prefix in the index
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
directory (`$XDG_CACHE_HOME/inshellah`), and returns completions
all subsequent completions for that command are instant (served from cache).
all subsequent completions for that command are served from cache.
elevation wrappers (`sudo`, `doas`, `pkexec`, `su`, `run0`) are
stripped before lookup: `sudo docker compose up --` resolves against
`docker`, not `sudo`. absolute paths after the wrapper are recognised
too.
## setup
the completer works with no extra configuration beyond the basic setup:
```nu
# ~/.config/nushell/config.nu
$env.config.completions.external = {
@ -36,18 +37,8 @@ $env.config.completions.external = {
}
```
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
}
}
```
with the nixos module, no extra config is needed beyond enabling the
module — the wrapper has the system paths baked in.
to manually specify system dirs, use colon-separated `--dir`:
@ -61,25 +52,15 @@ $env.config.completions.external = {
}
```
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)).
paths after the first in `--dir` are read-only system dirs.
## 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
# view stored data for a command
inshellah query docker
# clear cache