terminal-sherpa 0.5.1

AI-powered bash command generator

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) 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

Option	Description	Example
--model provider:model	Specify provider and model	ask --model anthropic "list files"
		ask --model anthropic:sonnet "list files"
		ask --model openai "list files"
		ask --model gemini "list files"
		ask --model gemini:pro "list files"
		ask --model grok "list files"
		ask --model ollama "list files"
		ask --model ollama:codellama "list files"
--verbose	Enable verbose logging	ask --verbose "compress this folder"

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"

Example Configuration File

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

[ask]
default_model = "anthropic"

[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

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

[ollama.codellama]
model = "codellama"

🤖 Supported Providers

• Anthropic (Claude)
• OpenAI (GPT)
• Google (Gemini)
• xAI (Grok)
• Ollama (Local Models)

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

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.