ollama-remote-chat-cli 0.2.0
Remote CLI client for Ollama servers - Network-ready chat interface with history tracking and inference control
License: MIT
Requires Python: >=3.7
Keywords: ollama, chat, cli, remote, llm, ai, terminal, client, network

# Ollama Remote Chat CLI

[![PyPI version](https://img.shields.io/pypi/v/ollama-remote-chat-cli.svg)](https://pypi.org/project/ollama-remote-chat-cli/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.7+](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)

A network-ready command-line chat client for Ollama servers. Connect to local or remote Ollama instances from any machine on your network.

<img width="1180" height="845" alt="ollama-cli" src="https://github.com/user-attachments/assets/875d3ab0-a030-4c23-b7c0-6d7023bb4808" />

## Quick Start

### Installation

Install directly from PyPI:

```bash
pip install ollama-remote-chat-cli
```

Run the client:

```bash
orc
```

Or use the full command:

```bash
ollama-remote-chat-cli
```

### First Run Setup

The first time you run `orc`, a setup wizard will guide you through:
1. Configuring your Ollama server URL
2. Selecting your preferred model
3. Setting up your preferences

```bash
orc
# Follow the interactive setup wizard
```

### One-Shot Mode (CLI Arguments)

Run queries directly from the command line without entering the interactive shell:

```bash
# Direct query
orc "Explain quantum physics in 10 words"

# Pipe content (e.g., summarize a file)
cat README.md | orc "Summarize this file"

# Use specific model and system prompt
orc "Who are you?" -m llama2 -s "You are a pirate"
```

## Features



- 🌐 **Network-ready** - Connect to local or remote Ollama servers

- 🔐 **Authentication** - Support for Bearer tokens and Basic Auth for secured instances

- 👁️ **Multimodal** - Chat with images using vision models (Llava, Llama 3.2-Vision, Qwen2-VL, etc.)

- 📚 **RAG Support** - Ingest and chat with your own text documents (Retrieval-Augmented Generation)

- 🎨 **Retro terminal UI** - Clean, colorful command-line interface with dynamic spinner messages

- 🧹 **Smart screen clearing** - `/clear` and `/new` preserve header while clearing chat history

- 🎨 **Rich markdown rendering** - Beautiful syntax highlighting and formatting

- 🧠 **Thinking process support** - See how reasoning models think (DeepSeek R1, QwQ, etc.)

- 📝 **Chat history** - Full session management with search functionality

- ⚙️ **Inference control** - Configurable temperature, top_p, context window, and more

- 📊 **Real-time metrics** - Token usage, thinking metrics, and generation speed

- 🔄 **Model management** - Easy switching, pulling, and deletion of models

- 🔍 **History search** - Search through past conversations

- 💻 **System monitoring** - View running models and memory usage

- 🔒 **Secure configuration** - XDG-compliant storage and .env support

- 🐛 **Error Logging** - Detailed logs in `debug.log` for troubleshooting.



---



## Requirements



- Python 3.7 or higher

- Ollama server (local or remote)

- Required packages: `requests`, `python-dotenv`, `wcwidth`, `rich`



---



## Connection Methods



### Authentication

If your Ollama server is behind a reverse proxy (Nginx, Apache, Cloudflare Tunnel) that requires credentials, you can configure them using the `/auth` command.



- **Bearer Token**: Used for API key authentication.

- **Basic Auth**: Used for Username/Password authentication.

- **Security**: Credentials are stored in your local configuration file.



### Method 1: Local Connection (Default)



Ollama running on the same machine:

```env
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=llama2
```

**Setup:**
1. Install Ollama from [ollama.ai](https://ollama.ai)
2. Run: `ollama serve`
3. Pull a model: `ollama pull llama2`

---


### Method 2: Hostname Connection (.local / mDNS)

Connect to another computer on your local network:

```env
OLLAMA_HOST=http://my-computer.local:11434
OLLAMA_MODEL=llama3.3
```

**Setup:**
1. Find your server's hostname:
   - **Windows**: `hostname` in CMD
   - **Mac**: System Preferences → Sharing → Computer Name
   - **Linux**: `hostname` in terminal
   
2. Ensure mDNS/Bonjour is enabled:
   - **Windows**: Install [Bonjour Print Services](https://support.apple.com/kb/DL999)
   - **Mac/Linux**: Built-in support
   
3. Test: `ping my-computer.local`

4. Configure firewall to allow port 11434

---


### Method 3: Static IP Address

For computers with fixed network IPs:

```env
OLLAMA_HOST=http://192.168.1.100:11434
OLLAMA_MODEL=mistral
```

**Setup:**
1. Set static IP on your Ollama server
2. Find IP address:
   - **Windows**: `ipconfig`
   - **Mac**: `ifconfig en0 | grep inet`
   - **Linux**: `ip addr show`
   
3. Configure firewall to allow port 11434

---


### Method 4: Docker

Ollama running in a Docker container:

```env
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=llama2
```

**Docker setup:**
```bash
docker run -d -p 11434:11434 --name ollama ollama/ollama
docker exec -it ollama ollama pull llama2
```

---


### Method 5: WSL (Windows Subsystem for Linux)

Accessing Windows Ollama host from WSL:

```env
OLLAMA_HOST=http://host.docker.internal:11434
OLLAMA_MODEL=llama2
```

Or find Windows IP from WSL:
```bash
ip route | grep default | awk '{print $3}'
```

---


## Available Commands

| Command | Description |
|---------|-------------|
| `/help` | Show all available commands |
| `/multi` | Enter multi-line input mode |
| `/clear` | Clear conversation context |
| `/new` | Start a new chat session |
| `/exit` | Exit the chat |
| **Features** | |
| `/auth` | **Manage Authentication** (Bearer Token / Basic Auth) |
| `/image` | Attach an image for vision models (`/image path.png`) |
| `/ingest`| Ingest a text file for RAG (`/ingest file.txt`) |
| **Model Management** | |
| `/models` | **Unified Model Manager** (Switch, Download, Remove, Create, Info) |
| **Generation** | |
| `/generate` | Generate raw completion without chat context |
| **Configuration** | |
| `/config` | **Unified Configuration Manager** (Host, Inference, Defaults) |
| **History** | |
| `/history` | View and manage/delete chat history |
| `/search` | Search chat history |
| `/showthinking` | View thinking from last AI response |
| **System Monitoring** | |
| `/version` | Show Ollama server version |
| `/ps` | List running models (memory usage) |
| `/ping` | Test connection latency to server |

---


## Inference Settings

Fine-tune AI behavior with the `/settings` command:

**Temperature** (0.0-2.0) - Controls response creativity
- 0.1-0.3: Precise (coding, math, facts)
- 0.6-0.8: Balanced (general chat)
- 1.0-1.5: Creative (writing, brainstorming)

**Top P** (0.0-1.0) - Nucleus sampling threshold (default: 0.9)

**Top K** (1-100) - Limits token choices (default: 40)

**Context Window** (128-32768) - Conversation memory in tokens (default: 2048)

**Max Output** (1-4096) - Maximum response length (default: 512)

**Repeat Penalty** (0.0-2.0) - Reduces repetition (default: 1.1)

**Request Timeout** (5-3600s) - Max time to wait for server response (default: 120s)

**Advanced**: Seed, Mirostat, Mirostat Eta/Tau.

---


## Advanced Features

### Multimodal Support (Vision)
Chat with images using vision-capable models (like `llava`, `llama3.2-vision`, or `qwen2-vl`).

- **Usage**: Type `/image <path/to/image.png>` to attach an image.
- **Interaction**: Ask questions about the image (e.g., "Describe this image").
- **One-Shot**: Images are automatically cleared after each response to keep the context clean.
- **Supported Formats**: `.jpg`, `.jpeg`, `.png`.

### RAG (Retrieval-Augmented Generation)
Chat with your own text documents by indexing them into a local vector store.

- **Ingest**: Use `/ingest <path/to/file.txt>` to chunk and index a text file.
- **Automatic Retrieval**: When you ask a question, the CLI automatically searches for relevant context in your ingested documents.
- **Context Injection**: Relevant snippets are injected into the prompt, and the CLI will notify you when document context is being used.

### Thinking Process Visualization
For reasoning models like **DeepSeek R1**, **QwQ**, and others that use chain-of-thought:

- **Hidden by default**: Thinking process is hidden during streaming for cleaner output
- **View thinking**: Use `/showthinking` to see the AI's reasoning after response
- **Live thinking**: Enable in `/settings` to watch the model think in real-time
- **Saved in history**: Thinking is automatically saved for later review

**Settings control:**
- `show_thinking_live` - Display thinking as it happens (default: false)
- `save_thinking` - Save thinking to chat history (default: true)

### Rich Markdown Rendering
AI responses are automatically formatted with:
- **Syntax highlighting** for code blocks
- **Styled headers** and emphasis (bold, italic)
- **Formatted lists** and blockquotes
- **Colored output** optimized for all terminals

**Toggle in `/settings`:**
- `use_markdown` - Enable/disable Rich rendering (default: true)

### System Monitoring
**`/ps` command** shows:
- Currently loaded models in memory
- VRAM usage per model
- Model expiration times
- Total memory consumption

Useful for:
- Monitoring resource usage
- Debugging slow responses
- Managing multiple models

---

## Troubleshooting

### "Could not connect to Ollama"

**1. Check Debug Logs:**
Errors are logged to the `debug.log` file in your data directory (XDG compliant). Check this file for detailed error messages and stack traces.

**2. Verify Ollama is running:**
```bash
curl http://localhost:11434
# Should return: "Ollama is running"
```

**2. Check firewall:**
- Windows: Allow port 11434 in Windows Firewall
- Mac: System Preferences → Security → Firewall
- Linux: `sudo ufw allow 11434`

**3. Test hostname resolution:**
```bash
ping your-hostname.local
# If fails, use IP address instead
```

**4. Check Ollama binding:**
```bash
# Ensure Ollama is listening on all interfaces
OLLAMA_HOST=0.0.0.0 ollama serve
```

### "Model not found"

```bash
# List available models on server
ollama list

# Pull a model
ollama pull llama2
```

### "Module not found" or Import Errors

```bash
# Reinstall the package
pip install --upgrade --force-reinstall ollama-remote-chat-cli
```

### Command not found: `orc`

**Windows:**
```bash
# Add Python Scripts to PATH
# Location: C:\Users\YourName\AppData\Local\Programs\Python\Python3XX\Scripts
```

**Mac/Linux:**
```bash
# Ensure pip install location is in PATH
export PATH="$HOME/.local/bin:$PATH"

# Add to ~/.bashrc or ~/.zshrc to make permanent
```

---

## Configuration Files

Config files are stored in standard XDG system paths to keep your home directory clean.

**Config Location:**
- **Windows**: `%APPDATA%\ollama-remote-chat\config.json`
- **Linux/Mac**: `~/.config/ollama-remote-chat/config.json`

**Data & History Location:**
- **Windows**: `%APPDATA%\ollama-remote-chat\history.json`
- **Linux/Mac**: `~/.local/share/ollama-remote-chat/history.json`

**Migration**: Legacy files (`~/.ollama_chat_config.json`) are automatically migrated to the new location on first run.

**Manual configuration:**
Create a `.env` file in your home directory or project root:

```env
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=llama2
TEMPERATURE=0.8
TOP_P=0.9
```

---


## Alternative Installation Methods

### From Source (Development)

```bash
# Clone the repository
git clone https://github.com/Avaxerrr/ollama-remote-chat-cli.git
cd ollama-remote-chat-cli

# Install in editable mode
pip install -e .

# Run it
orc
```

### Building Standalone Executable

```bash
# Using Nuitka build script
python nuitka_build.py

# Follow the interactive menu
# Creates portable .exe or binary
```

---


## Updating

To get the latest version:

```bash
pip install --upgrade ollama-remote-chat-cli
```

Check your current version:

```bash
pip show ollama-remote-chat-cli
```

Or inside the app:
```bash
orc
# Then type: /version
```

---


## Development

### Running from source:
```bash
git clone https://github.com/Avaxerrr/ollama-remote-chat-cli.git
cd ollama-remote-chat-cli
pip install -e .
orc
```

### Running tests:
```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests (when available)
pytest
```

---


## License

MIT License - see [LICENSE](LICENSE) file for details.

**Copyright © 2026 Avaxerrr**

Permission is hereby granted, free of charge, to use, modify, and distribute this software.

---


## Links

- **PyPI**: [https://pypi.org/project/ollama-remote-chat-cli/](https://pypi.org/project/ollama-remote-chat-cli/)
- **GitHub**: [https://github.com/Avaxerrr/ollama-remote-chat-cli](https://github.com/Avaxerrr/ollama-remote-chat-cli)
- **Issues**: [https://github.com/Avaxerrr/ollama-remote-chat-cli/issues](https://github.com/Avaxerrr/ollama-remote-chat-cli/issues)
- **Changelog**: [CHANGELOG.md](CHANGELOG.md) - View release history and version updates
- **Ollama**: [https://ollama.ai](https://ollama.ai)

---


## Acknowledgments

- Built for [Ollama](https://ollama.ai)
- Inspired by modern CLI tools
- Community contributions welcome

---


## Support

Having issues? Here's how to get help:

1. Check the [Troubleshooting](#troubleshooting) section
2. Search [existing issues](https://github.com/Avaxerrr/ollama-remote-chat-cli/issues)
3. Open a [new issue](https://github.com/Avaxerrr/ollama-remote-chat-cli/issues/new) with:
   - Your OS and Python version
   - Error messages
   - Steps to reproduce