Metadata-Version: 2.4
Name: ollama-client
Version: 0.1.0
Summary: Lightweight CLI client for a remote Ollama server
Project-URL: Homepage, https://github.com/rhiza-fr/ollama-client
Project-URL: Repository, https://github.com/rhiza-fr/ollama-client
Author-email: Chris Kilner <chris@rhiza.fr>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,chat,cli,llm,ollama,remote
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: pyyaml>=6
Requires-Dist: rich>=13
Description-Content-Type: text/markdown

# ollama-client

A lightweight CLI client for a remote [Ollama](https://ollama.com) server. Designed to be a drop-in replacement for the `ollama` CLI when you need to talk to a server running on a different machine — output formats, column names, and flag names match the official client character-for-character wherever possible.

```bash
ollama-client --host http://my-server:11434 list
ollama-client -H http://my-server:11434 run qwen3.5:4b
```

- Download size for ollama (which includes server): ~1.9Gb
- Download size for ollama-client (no server): < 50k

## Why use this instead of the full ollama?

The official `ollama` binary bundles a complete inference server — CUDA runtimes, model management daemons, the works. That makes sense if you want to run models locally. It's overkill if you don't.

**You already have a server.** If Ollama runs on a desktop with a GPU, a home server, or a remote machine, every other device — laptops, CI runners, WSL terminals, Raspberry Pis — only needs the client. There's no reason to download 1.9 GB of server software onto machines that will never serve a model.

**Constrained environments.** Bandwidth-limited machines, shared CI infrastructure, network-restricted environments, and minimal containers all benefit from a < 50 KB install that has no compiled extensions and no native dependencies.

**Faster iteration.** `uv tool install ollama-client` completes in seconds and works in a plain Python environment — no separate install script, no PATH surgery, no sudo. Useful in scripts and automation where you want the tool available without ceremony.

**Separation of concerns.** Keeping the server on dedicated hardware and the client on workstations is a cleaner architecture: one place to manage models, one place to restart the service, one place to monitor GPU memory. The client follows the server's address wherever it moves.

**Compatible static output.** Tabular output (`list`, `ps`, `show`), size formatting, relative time strings, and error prefixes are verified to match the official client character-for-character — so scripts and tooling that parse `ollama` output work without changes. Terminal animations (spinners, pull progress) look similar but are not identical.

## Quick Start

Get started quickly with these common operations:

```bash
# Install the client
uv tool install ollama-client

# Point at your server (--host / -H, or set OLLAMA_HOST)
export OLLAMA_HOST=http://my-server:11434

# List available models on your Ollama server
ollama-client list
ollama-client -H http://my-server:11434 list   # one-off override

# Run a model interactively (REPL)
ollama-client run qwen3.5:4b

# Run a single prompt
ollama-client run qwen3.5:4b "What is the capital of France?"

# Pull a model from the registry
ollama-client pull qwen3.5:4b
```

## Installation

Requires Python 3.11+.

```bash
uv tool install ollama-client
```

Or with pip:

```bash
pip install ollama-client
```

Once installed, the `ollama-client` command is available globally. To run directly from source:

```bash
uv sync
uv run ollama-client
```

## Usage

```
ollama-client [command] [flags]

Commands:
  run     Run a model
  pull    Pull a model from a registry
  list    List models
  ps      List running models
  stop    Stop a running model
  show    Show information for a model
  rm      Remove a model
  cp      Copy a model
  launch  Launch an AI integration backed by this server
  signin  Sign in to ollama.com
  signout Sign out of ollama.com
  help    Help about any command
```

### run

```bash
# Interactive REPL (maintains conversation history)
ollama-client run qwen3.5:4b

# One-shot generation
ollama-client run qwen3.5:4b "Why is the sky blue?"

# With a system prompt
ollama-client run qwen3.5:4b "Summarise this." --system "You are a concise assistant."

# Show timing and token statistics after the response
ollama-client run qwen3.5:4b "Hello" --verbose
```

The REPL accepts `/help`, `/clear`, and `/bye`. `Ctrl+D` and `Ctrl+C` also exit cleanly.

### launch

Configure and launch an AI coding tool backed by the local Ollama server.

```bash
# Interactive menu — pick integration and model
ollama-client launch

# Launch directly
ollama-client launch claude
ollama-client launch claude --model qwen3.5:4b

# Configure only (write config files / print env vars, don't launch)
ollama-client launch codex --config --model qwen3.5:4b

# Pass extra arguments through to the integration
ollama-client launch codex -- --sandbox workspace-write
```

Supported integrations:

| Name | Description | Configuration method |
|---|---|---|
| `claude` | Claude Code | Environment variables (`ANTHROPIC_BASE_URL`, model overrides) |
| `copilot` | Copilot CLI | Environment variables (`COPILOT_PROVIDER_BASE_URL`) |
| `codex` | Codex | `~/.codex/config.toml` (merged, not overwritten) |
| `hermes` | Hermes Agent | `~/.hermes/config.yaml` (merged, legacy `ollama` provider removed) |
| `opencode` | OpenCode | `OPENCODE_CONFIG_CONTENT` environment variable |
| `pi` | Pi | `~/.pi/agent/models.json` and `~/.pi/agent/settings.json` |
| `vscode` | VS Code | Launches `code` (no Ollama config; use the Ollama VS Code extension) |

Aliases: `copilot-cli` → `copilot`, `code` → `vscode`.

### help

```bash
# Show top-level help
ollama-client help

# Show help for a specific command
ollama-client help run
ollama-client help launch
```

### pull / list / ps / stop / show / rm / cp

These match the official client's invocation exactly:

```bash
ollama-client pull qwen3.5:4b
ollama-client list
ollama-client ps
ollama-client stop qwen3.5:4b
ollama-client show qwen3.5:4b
ollama-client rm qwen3.5:4b
ollama-client cp qwen3.5:4b my-qwen
```

## Setting the host

The host is resolved in this order, stopping at the first match:

1. **`--host` flag** — `ollama-client --host http://192.168.1.10:11434 list`
   (also accepted as `-H` on any subcommand)
2. **`OLLAMA_CLIENT_HOST` environment variable** — `export OLLAMA_CLIENT_HOST=http://192.168.1.10:11434`
   (useful when you want to target a different remote host while leaving `OLLAMA_HOST` unchanged)
3. **`OLLAMA_HOST` environment variable** — `export OLLAMA_HOST=http://192.168.1.10:11434`
   (`0.0.0.0` is automatically rewritten to `localhost`, so a server-side bind address works as-is)
4. **Config file** — `~/.config/ollama-client/config.toml`
5. **Default** — `http://localhost:11434`

### Config file

Create `~/.config/ollama-client/config.toml`:

```toml
[ollama]
host = "http://192.168.1.10:11434"
```

The `http://` scheme is optional — bare `hostname:port` is accepted and normalised automatically.

## Compatibility with the official ollama CLI

The goal is that output piped from `ollama-client` is indistinguishable from `ollama` output. The following have been verified to match character-for-character:

| Feature | Compatible |
|---|---|
| `list` column names and spacing (NAME, ID, SIZE, MODIFIED) | Yes |
| `ps` column names and spacing (NAME, ID, SIZE, PROCESSOR, UNTIL) | Yes |
| `show` section layout (Model, Capabilities, Parameters, License) | Yes |
| `pull` success message (`success`) | Yes |
| Size formatting (SI units, ÷1000) | Yes |
| Relative time strings ("2 hours ago", "3 days ago") | Yes |
| `--verbose` stats layout (total/load/eval duration, token rates) | Yes |
| Error prefix format (`Error: ...` to stderr) | Yes |

### Divergencies

These are deliberate omissions or differences:

**Missing commands**

- `serve` — this tool is a client only; it does not start an Ollama server.
- `create` — building new models from a Modelfile is not supported.
- `push` — pushing models to a registry is not supported.

**`launch` differences**

The official `launch` command includes a full TUI, model capability detection (vision, reasoning, context length), auto-install of integrations, cloud model support, and `--yes` auto-confirmation. This client implements the core configuration and launch flow only — no TUI, no capability probing, no auto-install.

**Missing flags on `run`**

| ollama flag | Status |
|---|---|
| `--format FORMAT` | Implemented |
| `--nowordwrap` | Implemented |
| `--keepalive DURATION` | Implemented |
| `--think [VALUE]` | Implemented (true/false or high/medium/low) |
| `--verbose` | Implemented |
| Image path argument (`run llava image.jpg`) | Not implemented |

**REPL differences**

The official REPL supports extended slash commands (`/save`, `/load`, `/show`, `/set`, `/unset`) and multiline input via `"""`. This client supports only `/help`, `/clear`, and `/bye`.

The REPL uses a custom input handler on Windows so that `Ctrl+D` behaves as EOF (the standard `input()` call does not support this on Windows).

**`run MODEL PROMPT` vs REPL**

A one-shot `run MODEL PROMPT` call uses `/api/generate`. The interactive REPL uses `/api/chat` with full message history. This matches the official client's behaviour.

## Dependencies

This package has three runtime dependencies. `httpx` is self-evidently required. The other two:

**`rich`** — used for all terminal output: the `list`/`ps` tables, the `pull` progress bar, live streaming text, and the `--verbose` stats block. Replicating that output with stdlib `print` calls would require hundreds of lines of manual ANSI escape handling to match the column alignment and formatting that the official client produces. Rich handles it in a few declarative calls and stays out of the way when stdout is not a TTY.

**`pyyaml`** — used only by the `launch hermes` subcommand, which must read, merge into, and write back `~/.hermes/config.yaml` without destroying the user's existing configuration. Python's stdlib has no YAML parser; a hand-rolled round-trip would be riskier than the dependency.

## Development

```bash
uv sync
uv run pytest          # unit tests (fast, no server required)
uv run mypy src/ollama_client
uv run ruff check src/ollama_client
```

### Compatibility tests

The `compat` suite runs the client against a live Ollama server and verifies output matches the real `ollama` CLI. It requires:

- A running Ollama server (default `http://localhost:11434`)
- The `ollama` binary on `PATH`
- [`tmux`](https://github.com/tmux/tmux) for terminal interaction tests

```bash
# Run with the default model (rnj-1:latest)
uv run pytest -m compat

# Run with a specific model
OLLAMA_COMPAT_MODEL=qwen3.5:4b uv run pytest -m compat

# Run only the help-text flag checks (no server or tmux needed, just the ollama binary)
uv run pytest -m compat tests/test_compat.py::TestHelp
```