cli-guidelines

# CLI Guidelines for Nushell

Comprehensive reference for building excellent command-line interfaces in Nushell, based on [clig.dev](https://clig.dev) principles and adapted for Nushell's structured data paradigm. Great CLIs are not just functional - they are empathetic, discoverable, consistent, and robust.

## Why CLI Guidelines Matter

Command-line interfaces are often the primary way developers and power users interact with tools. A well-designed CLI:

- **Reduces cognitive load** - Users can focus on their tasks, not fighting the tool
- **Builds trust** - Consistent, predictable behavior creates confidence
- **Enables automation** - Scripts and pipelines work reliably
- **Scales knowledge** - Learning one well-designed CLI transfers to others

## Core Philosophy from clig.dev

The eight principles that guide excellent CLI design:

### 1. Human-First Design

**Humans come first, machines second.** Optimize for human understanding by default.

```nushell
# Human-friendly: structured output Nushell displays beautifully
def "files analyze" [path: path = "."] -> table {
    ls $path
    | where type == "file"
    | select name size modified
    | sort-by size --reverse
    | first 10
}

# Machine-readable when needed: one pipe away
# files analyze | to json
# files analyze | to csv
```

**Nushell advantage:** Tables and records are both human-readable AND machine-parseable. No need to choose.

### 2. Simple Parts That Work Together

**Do one thing well.** Build small, focused commands that compose via pipelines.

```nushell
# GOOD: Single responsibility, composable
export def "git branches-merged" [] {
    git branch --merged
    | lines
    | where $it !~ '\*'
    | str trim
}

# Can be composed: git branches-merged | each { git branch -d $in }

# BAD: Trying to do too much
export def "git-cleanup-everything" [] {
    # Fetches, prunes, deletes merged, deletes stale, garbage collects...
    # Violates single responsibility
}
```

### 3. Consistency Across Programs