nushell-completions

name: nushell-completions description: This skill should be used when generating Nushell custom completions, writing completer functions, adding tab-completion to extern commands, using string@completer annotations, inline @[...] completion lists, or the @complete attribute. Relevant when the user asks to "add completions," "write a completer," "create an extern with tab completion," or "build context-aware argument suggestions" in Nushell.

Nushell Custom Completions

Generate completions for Nushell commands following these patterns.

Quick Reference

Inline Completions (Nu 0.108+)

Simplest approach for static options:

# Inline list directly in signature
def go [direction: string@[left up right down]] { $direction }

# Using const variable
const directions = [left up right down]
def go [direction: string@$directions] { $direction }

Command-Wide Completers (Nu 0.108+)

Use @complete attribute for all arguments of a command:

# Use the global external completer
@complete external
def --wrapped jc [...args] { ^jc ...$args | from json }

# Use a specific completer for all args
def carapace-completer [spans: list<string>] {
    carapace $spans.0 nushell ...$spans | from json
}

@complete carapace-completer
def --env get-env [name] { $env | get $name }

# For extern wrappers
@complete fish-completer
extern git []

Custom Completer Functions

For dynamic completions:

# Simple completer
def "nu-complete git remotes" [] {
    git remote | lines
}

# With descriptions
def "nu-complete branches" [] {
    git branch --format='%(refname:short)|%(subject)'
    | lines
    | split column '|' value description
}

# Context-aware (uses previous arguments)
def "nu-complete git branches" [context: string] {
    let remote = $context | split words | get 2?
    if $remote != null {
        git branch -r | lines | str trim | where { str starts-with $remote }
    } else {
        git branch | lines | str trim
    }
}

# Attach to command
def my-cmd [
    remote: string@"nu-complete git remotes"
    branch: string@"nu-complete git branches"
] { }

Completer Patterns

With Matching Options

def "nu-complete commands" [] {
    {
        options: {
            case_sensitive: false
            completion_algorithm: fuzzy
            sort: false  # preserve original order
        }
        completions: [
            { value: "build", description: "Build the project" }
            { value: "test", description: "Run tests" }
        ]
    }
}

For Extern Commands

export extern "git push" [
    remote?: string@"nu-complete git remotes"
    refspec?: string@"nu-complete git branches"
    --force(-f)
    --set-upstream(-u)
]

Module Naming Rule

When the file is named after the command (e.g., chafa.nu), the extern must be named main:

# File: chafa.nu
# Import: use chafa.nu

# ❌ WRONG - "Can't export known external named same as the module"
export extern chafa [...]

# ✅ CORRECT - `main` becomes the module's default command
export extern main [...]

Completer Signature Options

def completer [] { }                              # simple
def completer [context: string] { }               # with command line
def completer [context: string, pos: int] { }     # with cursor position
def completer [spans: list<string>] { }           # for @complete (list of args)

Best Practices

1. Prefer inline @[a b c] for small static lists
2. Use const @$var for reusable static lists
3. Naming: Use nu-complete <command> <what> pattern for functions
4. Module scope: Define completers as private, export only the command
5. Dynamic data: Shell out to get live values (git remote | lines)
6. Suppress completions: Return [ ] for args accepting any value
7. File fallback: Return null to use Nushell's file completions

Record Fields

Options Record