raulkivi/osh

NLSH

Learn and use Linux through natural language — powered by local LLMs via Ollama or a local llama.cpp llama-server.

Describe what you want in plain English and get 3 executable command options, each with detailed explanations that break down every pipe, flag, and chained command so you understand what you're running.

Features

• Interactive shell mode — Run nlsh with no arguments to enter a REPL; type queries continuously, use !help for commands, or exit / !exit to leave
• Natural language to shell — Describe what you want; get valid commands back
• 3 alternatives per query — Each generated by its own focused LLM call: a couple of shell variants, then one-liners in awk, perl, python3, etc. depending on what's installed
• Detailed explanations — Each chained command (pipes, &&, ;) explained on its own line
• QA safety review — Second-pass LLM review flags dangerous, incorrect, or imprecise commands
• Command availability check — Detects whether each suggested tool is installed before you run it

• Language detection — Auto-detects available scripting languages (bash, awk, perl, python3, ruby, node, etc.) and only suggests commands using what's installed
• Cloud model support — Use any Ollama cloud model by appending :cloud or -cloud to the model name (e.g. llama3.2:cloud); authenticates via OLLAMAAPIKEY
• Per-invocation model override — Use -m <model to pick a different model without editing config; use -m - to select interactively from available Ollama models
• Thinking model support — Handles models that use a separate thinking field (e.g., gpt-oss, deepseek-r1) with automatic response extraction and reformatting
• Clipboard support — Copy any command to clipboard instead of executing
• Retry on failure — If a command fails or misses the question, refine and retry interactively

• Daily log files — All queries, responses, verdicts, and user actions logged to ~/.local/state/nlsh/YYYYMMDD.log
• XDG-compliant paths — Config in ~/.config/nlsh/, state in ~/.local/state/nlsh/, app in ~/.local/nlsh/
• ask companion — Pipe any text through ask for general-purpose LLM Q&A

Requirements

• Python 3.11+
• Ollama installed and running locally, or a local llama.cpp llama-server

Quick Start

# Install
./install.sh

# Use
nlsh what is my public IP address
nlsh find all python files modified in the last 24 hours
nlsh show failed ssh login attempts grouped by IP

Installation

./install.sh

The installer will:

• Copy app files to ~/.local/nlsh/
• Create symlinks in ~/.local/bin/ (nlsh, ask, computer)
• Prompt for Python environment (pyenv, venv, or system)
• Install pip dependencies
• Let you choose a backend — Ollama (lists installed models) or llama.cpp llama-server (lists models from a running server, or lets you type the model name)
• Save configuration to ~/.config/nlsh/config.json

After installation, ensure ~/.local/bin is in your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc

Manual Install