ai-input-output 0.1.0

AI-powered pipe-friendly terminal command assistant using litellm + OpenRouter.

aio - AI Terminal Assistant

An intelligent terminal command assistant powered by LiteLLM and OpenRouter. Get instant help with shell commands, log analysis, and file operations directly in your terminal.

Features

• 🤖 Smart Command Generation: Get exactly the commands you need, with explanations
• 📊 Log Analysis: Pipe logs, errors, or any text for instant analysis
• 🔄 Interactive Mode: Execute suggested commands with a single keypress
• 📁 File Support: Analyze files directly with -f flag
• 🎯 Minimal & Focused: Generates one command by default, up to 3 for complex tasks
• 🔒 Output Truncation: Automatically manages context to prevent token overflow

Installation

# Install from PyPI
pip install aio-shell

# Or install from source
cd /path/to/aio
pip install -e .

Configuration

Configure API keys according to your LLM provider. See LiteLLM documentation for provider-specific setup.

Common examples:

OpenAI:

export OPENAI_API_KEY="sk-..."

OpenRouter:

export OPENROUTER_API_KEY="sk-or-v1-..."

Anthropic:

export ANTHROPIC_API_KEY="sk-ant-..."

Optionally set a default model:

export AIO_MODEL_NAME="openrouter/anthropic/claude-sonnet-4.5"

Usage

Basic Usage

# Interactive mode - generates commands for actionable tasks
aio "give me the biggest file in the current directory"

# With file input (stays interactive)
aio -f error.log "extract and count unique errors"

# Piped input (auto non-interactive) - provides direct analysis
cat error.log | aio "explain these errors to me"

# No question - auto-summarizes
aio -f config.yaml

Key difference: Piping automatically triggers non-interactive mode and exits after response. Use -f to maintain interactive session.

Interactive Mode

Safety: Commands are NEVER auto-executed. You must type the number to confirm.

aio "find python files modified today"
# AI responds with numbered commands:
#   1: find . -name "*.py" -mtime -1

> 1  # Type number to execute
# Output shown to you and sent back to AI for analysis

> /reset  # Clear conversation history

Exit: Press Ctrl+C twice (within 2 seconds).

Options

• -m, --model MODEL: Specify model (default: env AIO_MODEL_NAME or openrouter/anthropic/claude-sonnet-4.5)
• -f, --file FILE: Read input from file (preferred over piping - keeps interactive mode)
• -n, --lines N: Max preview lines for buffers (default: 50 for input, 256 for output)
• -c, --chars N: Max preview characters for buffers (default: 2000 for input, 4096 for output)
• -e, --exec: Force exec mode (one-shot, non-interactive)
• -d, --dry-run: Show API call parameters without executing

Examples

Tasks → Commands Generated

# System tasks - generates executable commands
aio "give me the biggest file in the current directory"
aio "find all python files modified today"
aio "show me disk usage by directory"

# File operations - generates processing commands
aio "find and compress all jpg files larger than 10MB from last week"
aio -f data.json "pretty print this json"

# Text processing - generates transformation commands
cat data.csv | aio "convert to JSON format"
aio -f error.log "extract and count unique errors"

Analysis → Direct Answers

# Explains provided content
cat error.log | aio "explain these errors to me"
git diff | aio "review this change"
docker logs app | aio "why did this crash?"

# Summarizes when no question provided
aio -f /var/log/app.log
cat config.yaml | aio

# Conceptual questions
aio "what is a race condition?"
aio "why might my application be slow?"

How It Works

1. Input: Text via stdin (piped), file (-f), or direct instruction
2. Mode: Piping auto-triggers non-interactive; -f stays interactive
3. Smart Response:
   • Actionable tasks (find, show, convert) → Generates bash commands
   • Analysis requests on provided content → Direct answers
   • No question → Summarizes content
4. Execution: You manually run commands by typing their number (interactive mode only)
5. Truncation: Inputs/outputs truncated for token efficiency (configurable via -n/-c)

Buffer Management

• Input: Defaults to 50 lines / 2000 chars (adjust with -n/-c)
• Output: You see full output; AI gets truncated version (256 lines / 4096 chars)
• Tip: Use -f instead of piping to stay in interactive mode

Command Format

# Explanation of what this does
command --with arguments

Commands include explanations and are executed exactly as shown when you type their number.

Best Practices

• Be specific: "find large files" → "find files larger than 100MB in /var"
• Use -f over piping: Keeps interactive mode for follow-up questions
• Action verbs for commands: "show", "find", "convert" → generates commands
• Analysis language for explanations: "explain", "why", "summarize" → direct answers
• Review before executing: Commands require your confirmation

Troubleshooting

Commands not generated? Use action verbs: "give me", "show me", "find", "convert"

Output too long? Adjust with -n and -c flags, or pipe through head/tail

API errors? Check your API key is set and has credits; try different model with -m

License

MIT

Contributing

Contributions welcome! Feel free to open issues or submit pull requests.