ollama-cli/README.md at bdbd90709ce9041e2204cf385de80cf72720dc16

Files

Paul Bailey bdbd90709c Update readme

2026-02-22 15:29:12 +00:00

7.7 KiB

Raw Blame History

# ollama-cli

A feature-rich interactive command-line client for Ollama’s chat API. This script lets you chat with local models, manage conversation sessions, integrate with MCP and language servers, and even control it remotely via ntfy.sh notifications.[file:1]

---

## Features

- **Interactive chat** with streaming responses against your local Ollama server (`/api/chat`).[file:1]  
- **Model management**: list models, switch default model, and exclude models you do not want to use.[file:1]  
- **Session management**: save, load, and list past chat sessions stored under `~/.ollama-cli-sessions`.[file:1]  
- **Config file support** at `~/.ollama-cli-config.json` for excluded models, Ollama URL, MCP servers, git/Gitea, and ntfy settings.[file:1]  
- **Context files**: add local files as context for the assistant to use.[file:1]  
- **Knowledge base**: simple built-in knowledge storage and search.[file:1]  
- **MCP integration**: connect to MCP servers over stdio and expose their tools to the assistant.[file:1]  
- **LSP integration**: start language servers (Python, TypeScript/JavaScript, Rust, Go, etc.) via built-in commands.[file:1]  
- **Remote control via ntfy.sh**: send notifications to a topic and get answers back as notifications.[file:1]  
- **Export to Markdown** and basic git/Gitea helpers for working with repositories.[file:1]

---

## Requirements

- Python 3.8+.[file:1]  
- A running Ollama server (e.g. `ollama serve`) reachable at `http://localhost:11434` or another configured URL.[file:1]  
- Optional tools (only needed if you use the respective features):[file:1]  
  - MCP servers (any binaries you want to connect via `/mcp connect`).[file:1]  
  - Language servers: `pyright-langserver`, `typescript-language-server`, `rust-analyzer`, `gopls`, etc., on your `PATH`.[file:1]  
  - `git` and a Gitea instance if you use git / Gitea integration.[file:1]  

Install Python dependencies (if any external libraries beyond the standard library are used, such as `requests`):[file:1]

```bash
pip install requests

Installation

Copy ollama-cli.py somewhere on your PATH, for example:[file:1]

mkdir -p ~/.local/bin
cp ollama-cli.py ~/.local/bin/ollama-cli
chmod +x ~/.local/bin/ollama-cli

Ensure ~/.local/bin is in your PATH.[file:1]
Start your Ollama server, e.g.:[file:1]
```
ollama serve
```

Basic Usage

Run the CLI:

ollama-cli
# or
python3 ollama-cli.py

On startup it will:[file:1]

Load ~/.ollama-cli-config.json (or create defaults in memory).[file:1]
Detect available models from the Ollama server.[file:1]
Show the current directory, home directory, and a list of supported commands.[file:1]

You then type messages at the > prompt and responses are streamed back to the terminal.[file:1]

Exit with:

/quit

or Ctrl+D / Ctrl+C.[file:1]

Commands

At the > prompt you can use various slash-commands.[file:1]

Core commands

/quit – Exit the program.[file:1]
/clear – Clear conversation history while keeping the system context.[file:1]
/retry – Retry the last request to the model.[file:1]

Sessions

/save – Save current history to chat_history.json in the current directory.[file:1]
/save [name] – Save as a named session under ~/.ollama-cli-sessions/<name>.json.[file:1]
/load <name> – Load a saved session by name.[file:1]
/sessions – List the most recent saved sessions.[file:1]

Models

/models – List available models from the Ollama server.[file:1]
/model <name> – Switch the default model for subsequent queries.[file:1]
/exclude <name> – Add a model to the excluded list in the config; takes effect after restart.[file:1]
/list-excluded – Show excluded models.[file:1]

Configuration and server

/server – Set the Ollama server URL (stored in config).[file:1]
/config git – Configure git credentials/remote in the config file.[file:1]
/config gitea – Configure Gitea server URL and token.[file:1]

Files, context, and export

/run – Execute a file (script helper, see implementation details in code).[file:1]
/context – Add a file to the context for the assistant.[file:1]
/context list – List context files.[file:1]
/context clear – Clear all context files.[file:1]
/export – Export the current conversation to Markdown.[file:1]

Knowledge base

/kb add – Add content to the internal knowledge base.[file:1]
/kb search – Search entries in the knowledge base.[file:1]

MCP (Model Context Protocol)

/mcp connect <name> <command> [args...] – Start an MCP server over stdio and register its tools.[file:1]
/mcp list – List connected MCP servers and their tools.[file:1]
/mcp disconnect <name> – Disconnect a specific MCP server.[file:1]

When connected, MCP tools are exposed to the assistant and described in the system prompt.[file:1]

LSP (Language Server Protocol)

/lsp start <language> [path] – Start a language server for a given language, optionally with a project root path.[file:1]
- Supported language keys include python, javascript, typescript, rust, go (see start_lsp_server).[file:1]

Subagents

/agents – Show status of running subagents.[file:1]

Notifications (ntfy.sh)

/notify setup – Configure ntfy settings in the config file (server, topic, enable flag).[file:1]
/notify off – Disable notifications in config.[file:1]
/notify test – Send a test notification.[file:1]

When notifications are enabled, the CLI starts an ntfy listener thread and:[file:1]

Listens to server/topic/json for incoming notifications.[file:1]
Converts each notification into a user message.[file:1]
Sends back the assistant’s response as another notification (title Response).[file:1]

Configuration

Config is stored at:

~/.ollama-cli-config.json

A typical structure includes:[file:1]

{
  "excluded_models": [],
  "git": {
    "remote_url": "",
    "username": "",
    "password": ""
  },
  "gitea": {
    "url": "",
    "token": ""
  },
  "auto_save_sessions": true,
  "mcp_servers": {},
  "ollama_url": "http://localhost:11434/api/chat",
  "ntfy": {
    "enabled": false,
    "topic": "",
    "server": "https://ntfy.sh"
  }
}

You can edit this by hand or through the /config and /notify commands.[file:1]

Sessions Storage

Session files are stored under:

~/.ollama-cli-sessions

Each session is a JSON document containing the messages and a timestamp, named like YYYYMMDD_HHMMSS.json (or your custom name).file:1 You can back this folder up or sync it to move history between machines.[file:1]

Development Notes

The script uses requests for HTTP calls, subprocess for MCP/LSP processes, threading for the notification listener, and standard modules such as json, os, sys, and pathlib.[file:1]
The main loop keeps a messages list of system, user, and assistant messages and trims it to avoid unbounded context size.[file:1]
The default model is llama3.2, but this can be changed either at runtime via /model or by editing the script/config.[file:1]

License

Add your preferred license here (e.g. MIT, Apache-2.0).

Roadmap / Ideas

Some potential future improvements:

Automatic reconnection and health checks for MCP and LSP servers.[file:1]
Richer TUI (colors, panes for context, session browser).[file:1]
Plugin system for additional transports or notification backends.[file:1]


Do you want this README tailored for publishing on GitHub (badges, screenshots, example configs), or kept minimal for local use?

7.7 KiB Raw Blame History Unescape Escape