onefirewall-ai

CLI for the OneFirewall AI Gateway and any OpenAI-compatible provider — chat, stream, and run agent workflows from your terminal.

Installation

pip install onefirewall-ai

First-Time Setup

1. Login

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

onefirewall-ai

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

Common Ways To Use It

Interactive agent REPL

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

onefirewall-ai chat

Opens the REPL without agent tool execution.

One-shot chat message

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

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

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

onefirewall-ai sessions
onefirewall-ai sessions view <session-id>
onefirewall-ai sessions delete <session-id>

Pipe input into the CLI

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

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

Custom provider example (e.g. OpenAI)

{
  "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:

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 sessions delete <id>	Delete 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

~/.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:

# 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:

# 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