nlsh-tool-beta 0.1.0

Natural language shell — describe what you want, get the command

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.

pipx install nlsh

Or with pip:

pip install nlsh

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

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.

nlsh --install-widget
source ~/.zshrc

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

Usage

# 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.