@shubham.dev/nlsh

nlsh — Natural Language Shell Agent

Talk to your terminal in plain English.

npm install -g @shubham.dev/nlsh
nlsh setup
nlsh "show all running containers"

nlsh is a shell agent that thinks in goals, not commands. You speak your intent, it builds a plan, executes step-by-step, watches results, and recovers from failures — all in a single terminal process.

Install

npm install -g @shubham.dev/nlsh

Requires Node.js 18+.

Setup

Configure your LLM API key:

nlsh setup

Get a free API key at https://console.groq.com and configure it:

export GROQ_API_KEY="gsk_..."

Usage

nlsh "check git status"
nlsh "push the latest changes to main"
nlsh "find all node_modules folders and show their sizes"
nlsh "run the test suite and fix any failures"

Commands

Command	Description
nlsh "intent"	Run the agent
nlsh --dry-run "intent"	Show plan and commands without executing
nlsh setup	Configure API keys
nlsh history	Show past command history
nlsh terrain	Show project terrain profile
nlsh terrain --refresh	Force rescan terrain
nlsh terrain --clear	Delete terrain profile
nlsh --help	Show help

How It Works

You: "push the latest changes to main"
        │
        ▼
  1. Terrain Scan ─── reads package.json, git log, docker-compose, etc.
        │
        ▼
  2. Planner ─── LLM generates a step-by-step plan
        │
        ▼
  3. You approve the plan ─── [Y/n]
        │
        ▼
  4. For each step:
     ─ Command Generator ─── LLM produces the exact shell command
     ─ Safety check ─── blocks dangerous commands (rm -rf /, etc.)
     ─ You confirm ─── [Y/n/e] (e = edit command)
     ─ Execute ─── streams output in real time
     ─ On failure ─── Recovery LLM diagnoses and revises remaining steps
        │
        ▼
  5. Done ─── summary with timing

Features

Terrain Awareness

Before acting, nlsh scans your project to understand its context — reads package.json, docker-compose.yml, git log, Makefile, and more. This context is injected into every LLM call, so commands are relevant to your actual project.

Safety System

Commands are checked against risk, reversibility, and confidence before execution:

• rm -rf / → blocked outright
• sudo apt install → requires typing "yes" (not just "y")
• docker rm -f $(docker ps -aq) → high risk warning

Commit Message Generation

When git commit is detected, nlsh captures the diff and generates a meaningful commit message automatically.

Recovery

If a step fails, the recovery LLM analyzes the error and produces a revised plan for the remaining steps — no need to restart from scratch.

TUI

Professional terminal UI built with Ink + React, styled in GitHub Dark colors with real-time streaming output.

Headless Mode

When stdin is not a TTY (piped input, CI), nlsh automatically falls back to a clean console mode. Use --headless explicitly in non-interactive environments.

Configuration

Config is stored at ~/.nlsh/config.json:

{
  "provider": "groq",
  "model": "llama-3.3-70b-versatile",
  "apiKey": "gsk_..."
}

API key priority: env var → config file

Development

git clone https://github.com/sankett13/nlsh.git
cd nlsh
npm install
npm run build
npm link

Scripts

Script	Description
npm run build	Compile TypeScript
npm run typecheck	Type-check without emitting
npm run test:unit	Run unit tests
npm run test:integration	Run integration tests
npm run start "intent"	Run via tsx (no build needed)

Tests

128 unit tests across 11 files covering planner, executor, memory, recovery, safety, UI controller, agent flow, editor, history, and committer.

npm run test:unit

License

MIT