# onefirewall-ai

> **CLI for the OneFirewall AI Gateway** — chat, stream, and build agents from your terminal.

[![PyPI](https://img.shields.io/pypi/v/onefirewall-ai)](https://pypi.org/project/onefirewall-ai/)
[![Python](https://img.shields.io/pypi/pyversions/onefirewall-ai)](https://pypi.org/project/onefirewall-ai/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## Installation

```bash
pip install onefirewall-ai
```

---

## Quick Start

### 1. Login

```bash
onefirewall-ai login
```

You'll be prompted for:
- **Endpoint** — your OneFirewall AI Gateway URL (e.g. `https://onefirewall.ai`)
- **API Key** — generate one from the Profile page in the dashboard

Credentials are saved to `~/.onefirewall-ai/access.json`.

### 2. Chat

```bash
onefirewall-ai What is the capital of France?
onefirewall-ai "Explain Kubernetes in simple terms"
onefirewall-ai Write a Python function to reverse a string
```

The response streams directly to your terminal in real time.

### 3. Session Management

By default, every new command creates a unique session so conversation history is maintained separately. You can view past sessions or resume a previous session:

```bash
# List all recent chat sessions
onefirewall-ai sessions

# Continue an existing session by ID
onefirewall-ai --session <session-id> "What did we just talk about?"

# Create a custom named session
onefirewall-ai --session my-coding-task "Help me write a Python script"
```

---

## Commands

| Command | Description |
|---|---|
| `onefirewall-ai` | Show help |
| `onefirewall-ai help` | Show help |
| `onefirewall-ai login` | Configure endpoint & API key |
| `onefirewall-ai sessions` | List all recent chat sessions |
| `onefirewall-ai [--session ID] <message>` | Send a message and stream the AI response |
| `onefirewall-ai version` | Show version |

---

## Home Directory

All data is stored in `~/.onefirewall-ai/`:

```
~/.onefirewall-ai/
├── access.json          # Endpoint + API key (private)
├── MEMORY.md            # Persistent facts the agent remembers
├── SOUL.md              # System prompt / agent persona
└── sessions/
    └── <session_id>.md  # Full conversation history for each session
```

### Customise your agent

**Edit `~/.onefirewall-ai/SOUL.md`** to change the AI's persona:

```markdown
# Soul
You are a concise senior DevOps engineer. Always prefer CLI examples.
```

**Edit `~/.onefirewall-ai/MEMORY.md`** to give the AI persistent context:

```markdown
# Memory
- My project uses Python 3.12 and FastAPI.
- Always prefer async/await patterns.
```

---

## API Reference

The CLI uses the OpenAI-compatible endpoint:

```
POST {endpoint}/api/v1/chat/completions
```

With `stream: true` and SSE parsing for real-time output.

---

## License

MIT © OneFirewall
