# nlsh — natural language shell

Describe what you want to do, get shell commands back. Pick one, it runs.

```
$ nlsh "find the 3 largest files in this repo"

  ❯ du -ah . | sort -rh | head -4
    find . -type f -exec du -h {} + | sort -rh | head -3
    ls -lhS | head -4

  ──────────────────────────────────────────────────────
  summarize disk usage for all files and dirs
  du -ah .     →  report size of every file and dir
  sort -rh     →  sort human-readable sizes, largest first
  head -4      →  show top 4 results (includes header)

  [↑↓] navigate   [↵] run   [y] copy   [q] quit
```

## Install

Requires Python 3.10+ and an [Anthropic API key](https://console.anthropic.com).

```bash
pipx install nlsh
```

Or with pip:

```bash
pip install nlsh
```

Set your API key (add to `~/.zshrc` or `~/.bashrc`):

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
```

## Optional: zsh widget

Press `ctrl+f` at any prompt to invoke nlsh inline. The selected command lands in your prompt and executes immediately.

```bash
nlsh --install-widget
source ~/.zshrc
```

To change the keybinding, edit `~/.config/nlsh/widget.zsh`.

## Usage

```bash
# basic
nlsh "compress this directory as a tarball"

# add context — URL (fetched) or plain text, repeatable
nlsh "start the dev server" -c "https://vitejs.dev/guide/"
nlsh "run tests" -c "we use pnpm, not npm"
nlsh "deploy" -c "https://fly.io/docs/launch/" -c "app name is my-api"

# fix a failed command — pipe in the error
npm run build 2>&1 | nlsh --fix
cargo build 2>&1 | nlsh --fix

# or describe what broke
nlsh --fix "permission denied writing to /usr/local"

# flat output (no TUI) — useful for scripting
nlsh -v "list open ports"

# see commands without running
nlsh --dry-run "clean up docker"
```

## How it works

1. Captures your current directory, git status, and file listing as context
2. Sends your query to Claude (Haiku) with that context
3. Gets back 3–5 `{command, explanation}` suggestions as JSON
4. Shows them in an interactive picker — explanation only for the item you're hovering on
5. Runs the chosen command via your shell

## Security

nlsh executes AI-generated shell commands. A few things to know:

- **Review before running** — the picker lets you read the command before pressing enter. Use `--dry-run` if you want to see suggestions without any risk of execution.
- **Your API key** — store it in a file with restricted permissions (`chmod 600`), not directly in `.zshrc` where it might be shared or version-controlled.
- **Network** — `-c` URLs are fetched over HTTPS. Content is sent to the Anthropic API along with your query.

## Configuration

| Environment variable | Default | Description |
|---|---|---|
| `ANTHROPIC_API_KEY` | — | Required. Your Anthropic API key. |

More configuration options (model choice, default context, keybinding) are on the roadmap.
