argo-shell-assistant 0.1.0

Natural language assistant for the Linux shell

Argo

Terminal assistant that translates natural language requests into Linux commands.

What it is

Argo is a CLI tool that:

• interprets natural language requests (Italian, English, etc.)
• generates appropriate shell commands via LLM (Ollama)
• classifies commands by risk level (🟢 read-only, 🟡 write, 🔴 destructive)
• allows preview, edit, explain and execution time estimation before running
• learns from your choices and improves suggestions over time

Installation

# Quick install script
./install.sh
# or without sudo (installs to ~/.local)
./install.sh --user

# Manual
pip install -e .
# or run from source without installing
./run.sh --version

Requirements

• Python 3.10+
• Ollama running
  • ollama serve — start the server
  • ollama pull llama3.2 — download a model

Basic usage

# Interactive mode (REPL)
argo

# Single query
argo find files larger than 1gb
argo find files modified today
argo search for "error" in logs

After generation you'll see a list of commands: use arrow keys to select, Enter to run. Keys: p preview, e edit, t estimate, x explain, q exit.

Examples

Single commands

# Preview (what the command would do)
argo preview "rm *.log"

# Step-by-step explanation
argo explain "grep -r error logs/"

# Execution time estimate
argo estimate ls -la
argo estimate find . -name "*.log"

Learning and memory

# Save a preferred command
argo learn grep -r error logs/

# List learned commands
argo memory

# Remove one
argo forget 1

# Optimize knowledge (deduplicate, learn from history)
argo optimize
argo optimize --dry-run

Configuration

argo config set llm.model llama3.2
argo config set language.output it
argo config get language.output
argo config list

# Verify environment
argo check
argo check --fix   # create missing config files

Custom risk rules

argo risk add command mytool danger
argo risk add pattern "curl.*\|.*sh" critical
argo risk protect /etc
argo risk list
argo risk remove command mytool

Auto-execute

argo -y find .log files          # auto if read-only
argo -y2 copy files to backup/   # auto if read-only or write
argo -y3 any command            # use with caution!

Session options

argo --lang it      # session in Italian
argo --auto         # same as -y for REPL
argo --no-color     # disable colors

Remote LLM (OpenAI, OpenRouter, etc.)

Argo can use remote APIs instead of local Ollama. API keys are read from environment variables (never stored in config).

OpenAI / compatible APIs:

# Set your API key (never commit this!)
export OPENAI_API_KEY="sk-..."

# Enable remote in config
argo config set llm.remote.enabled true
argo config set llm.remote.model gpt-4

OpenRouter (access to many models with one key):

export OPENAI_API_KEY="sk-or-..."
argo config set llm.remote.enabled true
argo config set llm.remote.base_url "https://openrouter.ai/api/v1"
argo config set llm.remote.model "anthropic/claude-3-haiku"

Custom env var name:

export MY_API_KEY="sk-..."
argo config set llm.remote.api_key_env MY_API_KEY

If remote fails or the openai package is missing, Argo falls back to local Ollama.

Configuration

Files in ~/.config/argo/:

• config.json — LLM, language, colors
• knowledge.json — learned commands
• history.json — choice history
• risk-rules.json — custom risk rules
• perf.json — performance estimate cache

License

MIT — see LICENSE