oAI — OpenRouter Chat CLI (oai.py)

Overview

oAI is a terminal-based chat interface to OpenRouter (https://openrouter.ai) designed to make interactive model usage pleasant in the terminal. It features:

Interactive chat

Persistent session history, system prompts and model switching.

Conversation management

Save/load/delete conversations in SQLite (oai_config.db).

File attachments

Attach code files, PDFs and images using the @/path/to/file syntax.

Export

Export conversations as Markdown, JSON or standalone HTML.

Cost & credits

Estimates cost per message and queries account credits via OpenRouter.

Rich terminal UI

Uses rich, prompt_toolkit and syntax-aware layouts.

First run: you'll be prompted to enter your OpenRouter API key (persisted in the app DB). You can also set it later with /config api.

Screenshot

Install

Minimal steps to get running locally.

Clone & setup

Download from the release page.
            
# Unzip and go to folder

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
chmod +x oai.py

# Optional: copy to a PATH location
mkdir -p ~/.local/bin
cp oai.py ~/.local/bin/oai

Alternative: alias

If you prefer not to copy the file, add an alias:

alias oai='python3 /path/to/oai.py'

Requirements

Python 3.7+
OpenRouter API key (get one at openrouter.ai)
Dependencies in requirements.txt

Quick Start

Run the script, set API key, select a model, and start chatting.

Start

./oai.py
# OR, if installed to PATH:
oai

First-time prompts

On first run you will be prompted for an API key. You can also run /config api in the app to set the key later.

Common workflow (example)

You> Hello, can you summarize this repository?
# Attach a file:
You> Please review @./scripts/example.py
# Save conversation:
You> /save my_review
# Export:
You> /export md my_review.md

Commands Reference (high level)

oAI exposes slash commands inside the chat prompt. Commands are case-insensitive.

Command	What it does
`/help`	Show detailed help and command list.
`/model [search]`	List & select available models.
`/config api`	Set OpenRouter API key (also supports other config subcommands).
`/memory on\|off`	Toggle conversation memory (include history in requests).
`/save <name>`	Save current conversation to the DB.
`/list`	List saved conversations (use numbers to load/delete).
`/load <name\|number>`	Load saved conversation.
`/export <md\|json\|html> <file>`	Export current conversation.
`@/path/to/file`	Attach files (images, pdf, code files). Example: `@document.pdf`
`/paste [prompt]`	Paste clipboard contents to the model (uses `pyperclip`).
`exit \| quit`	Exit the app; session summary is logged.

Notes: The app stores settings & conversations under ~/.config/oai/ (DB, history.txt, oai.log).

Examples & Patterns

1) Paste clipboard content and add a prompt

/paste Explain this function
# The app will paste clipboard contents and send them with your prompt.

2) Attach a code file for debugging

Debug this script @/home/user/projects/myscript.py

3) Parallel example: multi-step flow

You> Summarize README and list next steps.
You> /save meeting_notes
You> /export html meeting_notes.html

4) Export conversation as HTML

Export command

/export html my_session_report.html

The app provides three export formats: md, json, and html. The HTML export is a standalone file with basic styling — useful for sharing or archiving conversations.

Export, Storage & Logs

Storage paths (default):

`~/.config/oai/oai_config.db`	SQLite DB storing config and saved conversations.
`~/.config/oai/history.txt`	Prompt history used by prompt_toolkit.
`~/.config/oai/oai.log`	Application logs (rich-powered formatting).

Export formats

Markdown — good for note-taking and versioning.
JSON — machine-readable, includes metadata and messages.
HTML — standalone, styled export suitable for sharing.

Example: programmatic export

# inside the app:
# /export md conversation.md

Advanced / Tips

Streaming — Toggle streaming with /config stream on|off (helps when you want chunked streaming responses).
Token limits — Set a stored max with /config maxtoken <value> and session max with /maxtoken <value>.
Cost warnings — Configure a threshold with /config costwarning <amount>. The app estimates cost per message and checks account credits.
Middle-out transform — Enable with /middleout on to compress long prompts while preserving structure.
System prompt — Use /system <prompt> to set a session-level system prompt (guides the assistant).
File size limits — Files > 10MB are rejected to avoid sending huge payloads.