# Using inshellah completions in nushell

inshellah generates nushell completions from three sources (in priority order):
1. **Native generators** — programs that can emit nushell completions directly
2. **Manpages** — groff/troff manpage parsing
3. **`--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:

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

# From --help output
inshellah help 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:

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

```nu
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:

```nix
{
  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:
1. Scans executables in `$out/bin` for native nushell completion support
2. Parses manpages from `$out/share/man` (man1 and man8 sections)
3. 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/`.

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

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

```nu
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.