nexus-ai-cli 0.5.2
Ultra-minimal multi-provider AI framework
License: MIT
Requires Python: >=3.10
Keywords: ai, anthropic, chatgpt, cli, llm, ollama, openai

# Nexus AI

Ultra-minimal multi-provider AI CLI framework.

**Available on PyPI as `nexus-ai-cli`**

## Features

- **Unified Interface**: Single CLI for OpenAI, Anthropic, Ollama, and OpenRouter
- **Resilient Session Encryption**: AES-256 encryption with automatic fallback for WSL/Headless environments
- **Session Management**: Persistent conversations with search and export
- **Prompt Library**: Save and reuse system prompts
- **Smart Defaults**: Interactive model selection and fuzzy search
- **Streaming Output**: Real-time response streaming

## Installation

### Quick Install (Recommended)

```bash
pipx install nexus-ai-cli
```

**pipx** creates an isolated environment for Nexus AI, preventing conflicts with other Python packages.

### Alternative Installation Methods

**Using pip:**
```bash
pip install nexus-ai-cli
```

**Development install:**
```bash
git clone https://github.com/saadiqhorton/nexus-ai.git
cd nexus-ai
pip install -e .
```

### Updating

```bash
pipx upgrade nexus-ai-cli
# or
pip install --upgrade nexus-ai-cli
```

### System Requirements

- Python 3.10 or higher
- API keys for at least one AI provider (OpenAI, Anthropic, or OpenRouter)
- Ollama users: Ollama server running at http://localhost:11434

## Environment Setup

Copy the example environment file and add your API keys:

```bash
cp .env.example .env
```

Required environment variables (set at least one provider):

| Variable | Description |
|----------|-------------|
| `OPENAI_API_KEY` | OpenAI API key |
| `ANTHROPIC_API_KEY` | Anthropic API key |
| `OPENROUTER_API_KEY` | OpenRouter API key |

For local Ollama, no API key is needed - just ensure the server is running at `http://localhost:11434`.

If you run into session encryption issues in headless environments, you can provide a key via `NEXUS_ENCRYPTION_KEY` (see `SECURITY.md`).

## Quick Start

```bash
# Use default model
nexus "your prompt"

# Specify model
nexus -m gpt-4o "your prompt"

# Include file contents
nexus -f file.txt "explain this"

# Pipe content
cat file.txt | nexus "summarize"

# Interactive chat
nexus chat --session myproject
```

## Commands

| Command | Description |
|---------|-------------|
| `nexus "prompt"` | Send a prompt |
| `nexus chat` | Interactive REPL |
| `nexus models` | List available models |
| `nexus providers` | Show configured providers |
| `nexus config` | Display configuration |
| `nexus -d [model]` | Set default model |
| `nexus sessions` | Manage conversations |
| `nexus prompts` | Manage prompt library |
| `nexus completion` | Setup shell completion |

## Configuration

Config stored at `~/.nexus/config.yaml`:

```yaml
providers:
  openai:
    api_key: ${OPENAI_API_KEY}
  anthropic:
    api_key: ${ANTHROPIC_API_KEY}
  ollama:
    base_url: http://localhost:11434
  openrouter:
    api_key: ${OPENROUTER_API_KEY}

defaults:
  provider: openai
  model: gpt-4o
  temperature: 0.7
  max_tokens: 2000
  stream: true
```

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with Ollama integration
NEXUS_OLLAMA_URL=http://localhost:11434 pytest

# Linting
ruff check .
ruff format .
```

## Architecture

```
nexus/
├── cli/           # Click CLI commands
├── core/          # App, ProviderManager, CompletionHandler
├── providers/     # AI provider implementations
├── config/        # ConfigManager and models
├── session/       # Session persistence
├── prompts/       # Prompt library
└── utils/         # Cache, logging, errors
```