Metadata-Version: 2.4
Name: argo-shell-assistant
Version: 0.1.0
Summary: Natural language assistant for the Linux shell
Project-URL: Homepage, https://gitlab.com/gianfrasoft/argo
Project-URL: Documentation, https://gitlab.com/gianfrasoft/argo/-/blob/main/README.md
Project-URL: Repository, https://gitlab.com/gianfrasoft/argo
Project-URL: Issues, https://gitlab.com/gianfrasoft/argo/-/issues
Author: Argo contributors
License: MIT
License-File: LICENSE
Keywords: cli,llm,natural-language,ollama,openai,shell
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Shells
Requires-Python: >=3.10
Requires-Dist: ollama>=0.3.0
Requires-Dist: openai>=1.0.0
Requires-Dist: prompt-toolkit>=3.0.0
Description-Content-Type: text/markdown

# 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

```bash
# 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](https://ollama.com) running
  - `ollama serve` — start the server
  - `ollama pull llama3.2` — download a model

## Basic usage

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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

```bash
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

```bash
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

```bash
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:**

```bash
# 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):

```bash
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:**

```bash
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](LICENSE)
