A command-line interface (CLI) chat application for interacting with AI language models via OpenRouter. Seamlessly switch between 300+ models, attach files (images and text), enjoy real-time streaming responses, and manage settings persistently—all from your terminal. Perfect for developers, writers, and AI enthusiasts looking for a fast, feature-rich chat experience without leaving the command line.

🌟 Features

Model Flexibility: Choose from hundreds of OpenRouter-supported models (e.g., GPT-4, Claude, Gemini) with substring-based search and selection github.com for template-inspired ease.
File Attachments: Attach images (JPEG, PNG) or plain text files directly to messages using @path syntax, with automatic Base64 encoding for models that support modalities.
Streaming Responses: Enable real-time streaming for faster, live responses; toggle on/off via config commands (inspired by streaming in modern chat apps).
Persistent Configuration: Securely store API keys, base URLs, and settings in a local SQLite database for reuse across sessions.
Rich UI in CLI: Enhanced console output with Rich library panels, tables, and progress indicators for a polished terminal experience.
Clipboard Integration: Copy AI responses to the clipboard with a single prompt.
Help Command: Built-in /help with examples for all commands, making the app self-documenting and user-friendly github.com.
Error Handling: Graceful prompts for missing configs, file issues, and model incompatibilities.
Cross-Platform: Works on any OS with Python and internet access, no heavy dependencies required.

🖼️ Screenshots

📋 Requirements

Python: 3.9 or higher
OpenRouter API Key: Free tier available at openrouter.ai. Models like GPT-4 may require a paid plan.
Dependencies: Listed in requirements.txt (generate automatically with tools like pipreqs if needed).
Internet Connection: For API calls to OpenRouter.

🚀 Installation

Clone the Repository:

git clone https://github.com/yourusername/oai-chat-app.git  # Replace with your actual repo URL
cd oai-chat-app

Install Dependencies: Use pip for simplicity or uv for faster management:

# Using pip
pip install typer rich openrouter pyperclip requests

# Using uv
uv add typer rich openrouter pyperclip requests

# Using pip and requirements.txt (recommended)
pip3 install -r requirements.txt

Set Up Configuration:
- The app creates a SQLite database at ~/.config/oai/oai_config.db on first run.
- Run the app once to set your API key: python oai_chat.py chat.
- For API key issues, visit openrouter.ai/settings/keys.

Make Executable (Optional):

chmod +x oai_chat.py  # For Unix-based systems

Your app is now ready! Run python oai_chat.py chat to start chatting github.com inspired by simple setup in AI tools.

💻 Usage

Launch the app and interact via commands or direct chat:

python oai_chat.py chat

Available Commands

Command	Description	Example
`/help`	Display a table with examples for all commands and features.	`/help`
`/model [search]`	Select or switch models; optional search for substring matching.	`/model gpt` (Filters to GPT models) `/model` (Shows all models)
`/config api`	Update OpenRouter API key and reinitialize the client.	`/config api` Enter key: sk-... [Output: API key updated!]
`/config url`	Change the base URL for custom OpenRouter endpoints.	`/config url` Enter URL: https://custom.openrouter.ai/api/v1
`/config stream on/off`	Toggle response streaming (default: on for real-time chat).	`/config stream off` (For full responses at once) `/config stream on`
`/config`	View current configurations.	`/config` (Displays table: API Key, Base URL, Streaming, Database path)
`exit`, `quit`, `bye`	Exit the app cleanly.	`exit`
Chatting with Files	Attach files using `@path` (e.g., images for vision models, text for context).	`Explain this @~/demo.png` (Attaches image if model supports it)

Example Session

Welcome to OAI! Type your message, '/model [search]' to select/change model, '/config api/url/stream' to configure, '/help' for examples, or 'exit'/'quit' to end.
No model selected. Use '/model' to choose one.

You: /help
[Displays help table as above]

You: /model gpt
(Shows table of GPT models)
Enter model number: 1
Selected: GPT-4o (openai/gpt-4o)

You: Hello, how are you?
Streaming response... (Press Ctrl+C to cancel)
Hello! I'm doing great, thanks for asking. How can I help you today?

Type 'c' to copy response to clipboard, or press Enter to continue: c
Response copied to clipboard!

You: Analyze this text @~/notes.txt
Streaming response... (Press Ctrl+C to cancel)
Based on the attached file, the text discusses...

You: exit
Goodbye!

Streaming: Enabled by default for live responses; press Ctrl+C mid-stream to cancel (supported by most providers).
File Limits: Max 10MB per file; only images for vision models, plain text otherwise. Supports @~/relative/path or absolute paths.
Error Recovery: If no models fetch initially, check your API key. Prompts guide you through setup.

For more on OpenRouter models and features (e.g., tool calling), see openrouter.ai/docs.

⚙️ Configuration

All settings are stored securely in ~/.config/oai/oai_config.db using SQLite:

API Key: Required for authentication (set via /config api).
Base URL: Defaults to https://openrouter.ai/api/v1 (change for custom endpoints via /config url).
Streaming: Toggles live responses (on for real-time, off for buffered). Defaults to on.
Database Path: Automatically created; view full path with /config.

Edit any setting during a session without restarting. The database persists settings for future runs.

🛠️ Troubleshooting

No Models Available? Ensure your API key is valid and has access to models openrouter.ai. Check network connectivity.
Streaming Issues? Some models/providers may fall back to non-streaming. Toggle with /config stream off.
File Attachment Errors? Confirm paths are absolute (e.g., @/home/user/file.png) and files are under 10MB. Unsupported MIME types will be rejected.
API Errors? Re-set your key or check model compatibility (e.g., vision models for images).
Permission Denied? Ensure the app has read access to attached files and the database directory.
Installation Fails? Verify Python version and try pip install --upgrade pip. Use uv for dependency resolution github.com.
Performance? Large files or complex prompts may slow responses—trim inputs as needed.

If issues persist, open a GitHub issue with error logs.

🤝 Contributing

We welcome contributions to improve the OAI Chat App!

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with OpenRouter for model access openrouter.ai.
Inspired by AI README generators for documentation structure github.com, github.com, github.com, github.com, github.com.
CLI framework via Typer and Rich for polished UX.

Star ⭐ if this app helps—it's open-source and free! Happy chatting!