Back to Home View on PyPI

OneFirewall CLI

A Python CLI for chat, streaming, and agent workflows from your terminal.

onefirewall-ai connects directly to the OneFirewall AI Gateway or any OpenAI-compatible provider. Use it for interactive REPL sessions, one-shot prompts, piping terminal output, and longer agent-style tasks without leaving your shell.

Agent + Chat REPL

Launch an interactive terminal REPL with agent mode for file-aware tasks or stay in chat-only mode when you just want answers.

Session Memory

Use --session to persist context across debugging, writing, and long-running terminal workflows.

Pipe & One-shot

Send logs, diffs, or command output straight into the CLI for instant summaries, fixes, and explanations.

Any OpenAI Provider

Connect to OneFirewall AI, OpenAI, Groq, Ollama, Azure OpenAI, Anthropic, and other OpenAI-compatible endpoints.

1. Installation

pip install onefirewall-ai

2. Login & Provider Setup

The login flow now matches the landing page experience: pick OneFirewall AI for the managed gateway, or select Other to connect to any OpenAI-compatible base URL.

$ onefirewall-ai login
Select a provider:
1) OneFirewall AI (managed gateway)
2) Other (any OpenAI-compatible URL)
-> 1
Connected to OneFirewall AI Gateway

For OneFirewall AI, use your gateway URL and API key from the dashboard profile.

For Other, paste any OpenAI-compatible base URL and API key.

Credentials are stored locally in ~/.onefirewall-ai/access.json.

3. Agent + Chat REPL

Run the CLI without arguments to enter the interactive REPL. It can handle standard chat as well as agent-style tasks, and you can toggle modes from inside the session.

$ onefirewall-ai
OneFirewall AI Gateway - agent mode - gpt-4o
Type /help for commands, /agent to toggle mode
you > Fix the failing tests in this repo
Reading test files...
Running tests...
Found 3 issues, applying fixes
ai > Fixed import error in test_auth.py and mocked the DB connection in test_api.py.

4. Session Memory

Use sessions to keep context across multiple commands and longer tasks. This is the same session-memory story highlighted on the landing page.

# List recent sessions
onefirewall-ai sessions
# Resume an existing session
onefirewall-ai --session <session-id> "What did we just talk about?"
# Create your own named session
onefirewall-ai --session my-coding-task "continue"

5. Pipe & One-shot

Send logs, diffs, and command output directly into the CLI, or run a one-shot agent command when you do not need the full REPL.

# Pipe logs into the model
cat logs.txt | onefirewall-ai "Summarize the main errors"
# One-shot agent run
onefirewall-ai agent "Read the README and explain structure"
# Continue a saved task
onefirewall-ai --session my-task "continue"

CLI Commands

CommandDescription
onefirewall-aiStart the interactive REPL.
onefirewall-ai loginSelect a provider and save your credentials.
onefirewall-ai "Explain this stack trace"Run a one-shot prompt directly from your shell.
onefirewall-ai agent "Read the README and explain the repo"Run an agent-style task without entering the REPL first.
onefirewall-ai --session my-task "continue"Resume a named session with prior context.
onefirewall-ai sessionsList recent sessions.
onefirewall-ai versionShow the installed CLI version.

Home Directory Data

Local CLI state is stored under ~/.onefirewall-ai/.

  • access.jsonSaved provider selection, base URL, and API key.
  • MEMORY.mdPersistent facts the agent should remember.
  • SOUL.mdSystem prompt and persona customisation.
  • sessions/Conversation history for each saved session.

Customise Agent Persona

Edit SOUL.md

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

Add Persistent Rules

Edit MEMORY.md

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