# onefirewall-ai

> CLI for the OneFirewall AI Gateway and any OpenAI-compatible provider — chat, stream, and run agent workflows 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
```

## First-Time Setup

### 1. Login

```bash
onefirewall-ai login
```

The login wizard asks you to choose a provider first:

```
Select a provider:

  1) OneFirewall AI  (managed AI gateway)
  2) Other           (any OpenAI-compatible provider)
```

#### Option 1 — OneFirewall AI

- Endpoint is pre-configured (`https://onefirewall.ai`)
- Asks for your OneFirewall API key
- Fetches your available workspaces / models from the gateway
- Lets you pick one from a numbered list
- Tests the connection, then saves

#### Option 2 — Custom OpenAI-compatible provider

Works with any provider that exposes an OpenAI-compatible API: OpenAI, Groq, Together AI, Ollama, Azure OpenAI, LM Studio, and others.

- Asks for a provider label (e.g. `OpenAI`, `Groq`)
- Asks for the API base URL (e.g. `https://api.openai.com`)
- Asks for your API key
- Tries to auto-fetch available models from `/v1/models` and lets you pick from a list
- If models can't be fetched automatically, asks you to enter a model name manually
- Tests the connection, then saves

Your config is saved to `~/.onefirewall-ai/access.json`.  
To switch providers or change your model, just run `onefirewall-ai login` again.

### 2. Start using it

```bash
onefirewall-ai
```

Running `onefirewall-ai` with no arguments opens the interactive REPL in agent mode.

## Common Ways To Use It

### Interactive agent REPL

```bash
onefirewall-ai
onefirewall-ai agent
```

Use this when you want the assistant to inspect files, run tools, and help across multiple turns in one session.

### Interactive chat-only REPL

```bash
onefirewall-ai chat
```

Opens the REPL without agent tool execution.

### One-shot chat message

```bash
onefirewall-ai "What is the capital of France?"
onefirewall-ai "Explain Kubernetes in simple terms"
onefirewall-ai chat "Summarize this error message"
```

Sends a single message and streams the answer back to your terminal.

### One-shot agent task

```bash
onefirewall-ai agent "Fix the failing tests in this repo"
onefirewall-ai agent "Read the README and explain the project structure"
```

Use this when you want the assistant to act autonomously for one task.

### Resume a session

```bash
onefirewall-ai --session my-task "continue"
onefirewall-ai --session my-task agent "add tests for the new endpoint"
```

Use `--session` to keep related work in the same saved conversation.

### List and inspect sessions

```bash
onefirewall-ai sessions
onefirewall-ai sessions view <session-id>
```

### Pipe input into the CLI

```bash
cat logs.txt | onefirewall-ai "Summarize the main errors"
cat diff.txt | onefirewall-ai agent "Review this patch"
echo "hello" | onefirewall-ai "Repeat this back"
```

Useful for logs, diffs, command output, or any text you want to send alongside a prompt.

## REPL Guide

### Agent mode vs chat mode

- **Agent mode** — the assistant can use tools, inspect files, and take action.
- **Chat mode** — conversation only, no tools.
- Switch modes at any time with `/agent` inside the REPL.

### Slash commands

| Command | Description |
|---|---|
| `/help` | Show REPL help |
| `/session` | Show current session ID |
| `/new` | Clear the current conversation |
| `/clear` | Clear the terminal screen |
| `/agent` | Toggle agent / chat mode |
| `/exit` or `/quit` | Leave the REPL |

### Multi-line input

- Press `Alt+Enter` to insert a newline
- Or end a line with `\` to continue on the next line

## Provider Configuration

The active provider and model are stored in `~/.onefirewall-ai/access.json`.

### OneFirewall AI example

```json
{
  "provider": "onefirewall",
  "endpoint": "https://onefirewall.ai",
  "api_key": "YOUR_API_KEY",
  "model": "openai/gpt-4o",
  "strategy": "balanced"
}
```

### Custom provider example (e.g. OpenAI)

```json
{
  "provider": "custom",
  "provider_label": "OpenAI",
  "endpoint": "https://api.openai.com",
  "api_key": "sk-...",
  "model": "gpt-4o",
  "strategy": "balanced"
}
```

The `provider` field controls which API path is used:

| Provider | Chat completions path |
|---|---|
| `onefirewall` | `{endpoint}/api/v1/chat/completions` |
| `custom` | `{endpoint}/v1/chat/completions` |

To change your provider or model at any time, run:

```bash
onefirewall-ai login
```

## Command Reference

| Command | What it does |
|---|---|
| `onefirewall-ai` | Open the REPL in agent mode |
| `onefirewall-ai agent` | Open the REPL in agent mode explicitly |
| `onefirewall-ai chat` | Open the REPL in chat-only mode |
| `onefirewall-ai "<message>"` | Send one message and stream the reply |
| `onefirewall-ai agent "<task>"` | Run one agent task |
| `onefirewall-ai --session <id> "<message>"` | Resume a chat session |
| `onefirewall-ai --session <id> agent "<task>"` | Resume an agent session |
| `onefirewall-ai sessions` | List saved sessions |
| `onefirewall-ai sessions view <id>` | Show a saved session |
| `onefirewall-ai login` | Configure provider, API key, and model |
| `onefirewall-ai help` | Show CLI help |
| `onefirewall-ai version` | Show installed version |

## Where Data Is Stored

```text
~/.onefirewall-ai/
├── access.json       ← provider, endpoint, API key, model
├── MEMORY.md         ← persistent context the assistant remembers
├── SOUL.md           ← persona and behavior guidance
└── sessions/
    └── <session_id>.md
```

## Customizing The Assistant

### `SOUL.md`

Edit `~/.onefirewall-ai/SOUL.md` to shape the assistant's persona:

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

### `MEMORY.md`

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

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

> **Note:** `MEMORY.md` is synced to the OneFirewall AI gateway when using the `onefirewall` provider.
> For custom providers it is used as local context only.

## License

MIT Copyright OneFirewall
