LLM Shell Hint

A command line tool that uses LLMs to generate shell commands based on natural language queries with a TUI interface for selection.

The code, appropriately, was mostly generated by Aider. As was much of this README. As always, do not run commands you don’t understand; this gives you assistance, not a liability waiver.

Features

• Generate shell commands from natural language descriptions
• Interactive TUI for browsing and selecting commands
• Configurable LLM backend (OpenAI API compatible)
• Supports output to stdout or file
• Persists configuration between runs

Installation

Using Nix flakes

# Run directly without installing
nix run github:yourusername/llm-shell-hint

# Install permanently
nix profile install github:yourusername/llm-shell-hint

Manual Build

go build -o llm-shell-hint .

Usage

Usage: llm-shell-hint [options] [query]

Options:
  -help           Show help
  -version        Show version
  -config-file    Path to config file (default: ~/.config/llm-shell-hint/config.toml)
  -verbose        Enable debug logging
  -output         Path to output file (default: stdout)
  -provider-url   Override LLM provider URL
  -api-key        Override API key
  -shell-type     Override shell type
  -model          Override model name
  -color-scheme   Override color scheme (light/dark)

Examples

1. Basic query:

llm-shell-hint "recursively find all video files ordered by size"

2. Save command to file:

llm-shell-hint "convert all PNGs in directory to JPG" -output convert.sh

3. With debug logging:

llm-shell-hint -verbose "backup important files to remote server"

Configuration

The configuration file is stored in TOML format at ~/.config/llm-shell-hint/config.toml.

Example configuration:

LLMProviderURL = "https://openrouter.ai/api/v1/chat/completions"
APIKey = "your-api-key-here"
ShellType = "fish"
ModelName = "anthropic/claude-sonnet-4"

If llm-shell-hint cannot find a config file, it will query you for parameters, and create one.

Getting an API Key

1. Sign up at OpenRouter.ai or any other OpenAI-compatible provider
2. Get an API key from your account dashboard
3. Add it to the config file

Building from Source

git clone https://github.com/yourusername/llm-shell-hint.git
cd llm-shell-hint
go build -o llm-shell-hint .

License

AGPLv3