terminal-sherpa

A lightweight AI chat interface for fellow terminal dwellers.

Turn natural language into bash commands instantly. Stop googling syntax and start asking.

🚀 Getting Started

Get up and running:

# Install terminal-sherpa
pip install terminal-sherpa # installs the `ask` CLI tool

# Set your API key
export ANTHROPIC_API_KEY="your-key-here"

# Try it out
ask "find all .py files modified in the last week"

Example output:

find . -name "*.py" -mtime -7

✨ Features

• Natural language to bash conversion - Describe what you want, get the command
• Multiple AI provider support - Choose between Anthropic (Claude), OpenAI (GPT), Google (Gemini), xAI (Grok), OpenRouter (100+ models), and local models via Ollama
• Flexible configuration system - Set defaults, customize models, and manage API keys
• XDG-compliant config files - Follows standard configuration file locations
• Verbose logging support - Debug and understand what's happening under the hood

📦 Installation

Requirements

• Python 3.9+
• API key for Anthropic, OpenAI, Google, or xAI (or local Ollama installation)

Install Methods

Using pip:

pip install terminal-sherpa

From source:

git clone https://github.com/lcford2/terminal-sherpa.git
cd terminal-sherpa
uv sync
uv run ask "your prompt here"

Verify installation:

ask --help

💡 Usage

Basic Syntax

ask "your natural language prompt"

Command Options

Practical Examples

File Operations:

ask "find all files larger than 100MB"
# Example output: find . -size +100M

ask "create a backup of config.txt with timestamp"
# Example output: cp config.txt config.txt.$(date +%Y%m%d_%H%M%S)

Git Commands:

ask "show git log for last 5 commits with one line each"
# Example output: git log --oneline -5

ask "delete all local branches that have been merged"
# Example output: git branch --merged | grep -v "\*\|main\|master" | xargs -n 1 git branch -d

System Administration:

ask "check disk usage of current directory sorted by size"
# Example output: du -sh * | sort -hr

ask "find processes using port 8080"
# Example output: lsof -i :8080

Text Processing:

ask "count lines in all Python files"
# Example output: find . -name "*.py" -exec wc -l {} + | tail -1

ask "replace all tabs with spaces in file.txt"
# Example output: sed -i 's/\t/    /g' file.txt

Network Operations:

ask "download file from URL and save to downloads folder"
# Example output: curl -o ~/Downloads/filename "https://example.com/file"

ask "check if port 443 is open on example.com"
# Example output: nc -zv example.com 443

⚙️ Configuration

Configuration File Locations

Ask follows XDG Base Directory Specification:

1. $XDG_CONFIG_HOME/ask/config.toml
2. ~/.config/ask/config.toml (if XDG_CONFIG_HOME not set)
3. ~/.ask/config.toml (fallback)

Environment Variables

export ANTHROPIC_API_KEY="your-anthropic-key"
export OPENAI_API_KEY="your-openai-key"
export GEMINI_API_KEY="your-gemini-key"
export XAI_API_KEY="your-xai-key"
export OPENROUTER_API_KEY="your-openrouter-key"

Example Configuration File

Create ~/.config/ask/config.toml:

[ask]
default_model = "openrouter"

[anthropic]
model = "claude-3-haiku-20240307"
max_tokens = 512

[anthropic.sonnet]
model = "claude-sonnet-4-20250514"
max_tokens = 1024

[openai]
model = "gpt-4o"
max_tokens = 1024

[gemini]
model = "gemini-2.5-flash-lite-preview-06-17"
max_tokens = 150

[gemini.pro]
model = "gemini-2.5-pro"
max_tokens = 1024

[grok]
model = "grok-3-fast"
max_tokens = 150
temperature = 0.5

[openrouter]
model = "openrouter/auto"
max_tokens = 150
temperature = 0.5

[openrouter.claude]
model = "anthropic/claude-3.5-sonnet"

[ollama]
model = "llama3.2"
host = "localhost"
port = 11434

[ollama.codellama]
model = "codellama"

🤖 Supported Providers

• Anthropic (Claude)
• OpenAI (GPT)
• Google (Gemini)
• xAI (Grok)
• OpenRouter (100+ models from many providers)
• Ollama (Local Models)

Note: Get API keys from Anthropic Console, OpenAI Platform, Google AI Studio, xAI Console, or OpenRouter

Using OpenRouter

OpenRouter gives you access to models from many providers (Anthropic, OpenAI, Meta, Mistral, and more) through a single OpenAI-compatible API and API key:

export OPENROUTER_API_KEY="your-openrouter-key"
ask --model openrouter "list files"

By default, openrouter uses OpenRouter's openrouter/auto model, which automatically routes your prompt to a suitable model. Pin a specific model with a named sub-config (see the example configuration above) or by setting model_name directly, using any OpenRouter model slug (e.g. anthropic/claude-3.5-sonnet, openai/gpt-4o, meta-llama/llama-3.1-8b-instruct:free).

Reasoning models

Some models route through OpenRouter with "thinking"/reasoning enabled by default, which spends part of your max_tokens budget on hidden reasoning before producing a response — with a low max_tokens, this can leave no room for the actual answer. Set reasoning_effort in your config to control this:

[openrouter.gemini]
model_name = "google/gemini-3.7-flash"
reasoning_effort = "low"   # "high" | "medium" | "low" | "none", depending on the model

[openrouter.claude]
model_name = "anthropic/claude-haiku-4.5"
reasoning_effort = "none"  # fully disable reasoning, where supported

Support for "none" and the available effort levels vary by model — some models require reasoning and reject "none". Check a model's supported_parameters and reasoning.mandatory fields at openrouter.ai/api/v1/models to see what it allows.

Local Models with Ollama

For local inference without API costs:

1. Install Ollama: Visit ollama.ai for installation instructions
2. Pull a model: ollama pull llama3.2
3. Start Ollama: ollama serve (if not auto-started)
4. Use with ask: ask --model ollama "your prompt"

Example:

ollama pull codellama
ask --model ollama:codellama "optimize this bash script"

🛣️ Roadmap

• Shell integration and auto-completion
• Additional providers (Cohere, Mistral)
• Additional local model support (llama.cpp)

🔧 Development

Setup

git clone https://github.com/lcford2/terminal-sherpa.git
cd ask
uv sync --all-groups
uv run pre-commit install

Testing

uv run python -m pytest

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run pre-commit checks: uv run pre-commit run --all-files
5. Run tests: uv run task test
6. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Issues

Found a bug or have a feature request? Please open an issue on GitHub Issues.