Command Reference

Complete overview of all CLI commands, their flags, and — importantly — how to read the output. For concepts and configuration see Configuration.

ollama-agent [-config <path>] <command> [flags]

Global flag -config (before the command): path to the JSON config. Without it, the following are searched in order: $OLLAMA_AGENT_CONFIG → ./config.json → ~/.ollama-agent/config.json.

Quick overview:

Command	Purpose
`run`	Run a prompt through the agent once
`chat`	Interactive chat session with memory
`serve`	Daemon: HTTP API + scheduler + MCP connections
`endpoints`	Status of the Ollama servers (reachability, models)
`models`	Models per server + task assignment
`skills`	List/show skills
`tools`	Available tools (built-in + MCP)
`jobs`	Manage scheduler jobs
`probe`	Model capability test → matrix
`probe deep`	Context depth test (comprehension score)
`config`	Check config / generate example
`version`	Show version

run

Runs a single prompt and exits. No daemon needed.

ollama-agent run [flags] "<prompt>"

Flag	Meaning
`--model <name>`	Force a specific model, skipping automatic routing
`--category <cat>`	Force a task category from the config (skips classification)
`--skill <name>`	Load this skill into the context up front
`--no-stream`	Print the response all at once instead of token by token
`--json`	Result as JSON (with model, category, tool calls, token counters)

Reading the output. By default the response is streamed live. With --json you get an object:

output — the response
model — which model actually ran (after routing/failover)
category — the detected or forced task category
skill — automatically loaded skill (if a trigger matched)
tool_calls[] — each tool call with tool, args, result, optionally error and salvaged (true = recovered from plain text, the model did not emit a clean tool call)
iterations — how many loop rounds it took
usage — prompt_tokens / output_tokens

A high iterations value or many salvaged calls indicate a model that struggles with tools.

chat

Interactive REPL with conversation memory.

ollama-agent chat [--model <name>] [--category <cat>] [--skill <name>]

Meta commands during the session:

/model <name> — switch model, /model auto switches back to automatic routing
/reset — clear conversation history
/quit (or /exit) — quit

Reading the output. After each response, a line (N tool call(s), model X) appears if tools were used. History is automatically compacted when it gets close to the model’s context window.

serve

Starts the daemon: HTTP API, scheduler (if scheduler.enabled), and the MCP server connections.

ollama-agent serve [-addr <host:port>]

Flag	Meaning
`-addr <host:port>`	Listen address, overrides `api.addr` from the config

Reading the output. On startup the address, number of endpoints, skills, and tools are printed, then one line per HTTP request. Full API description: HTTP API Reference. Clean stop with Ctrl-C.

endpoints

Pings all configured Ollama servers and shows reachability and model count.

ollama-agent endpoints

Reading the output. Columns:

NAME, URL — from the config
STATUS — up or DOWN
LATENCY — response time of the version ping
MODELS — number of models present; on DOWN, the error message instead

Exit code 1 if at least one server is down — this makes it usable as a monitoring check in scripts/cron.

models

Shows which model resides on which server, plus the task assignment from the config.

ollama-agent models

Reading the output. First a table MODEL → ENDPOINTS (on which servers each model is available). Then the task assignment:

CATEGORY — the task category
MODELS — the preference list from the config (in order)
AVAILABLE — which of these models is actually reachable right now (this is what would be chosen for a request in this category); - means none available, models.default applies

skills

ollama-agent skills [list | show <name>]

skills or skills list — table of all discovered skills: NAME, DESCRIPTION, TRIGGERS, SCRIPTS (count)
skills show <name> — full content of a skill (description, triggers, scripts, path, body)

Reading the output. The TRIGGERS determine which keywords in the prompt cause a skill to load automatically (if skills.auto_load_on_trigger). SCRIPTS > 0 means the skill ships helper scripts (only executable when skills.allow_scripts: true).

tools

ollama-agent tools

Connects to the MCP servers once and lists all available tools.

Reading the output. First a status line per MCP server (connected / NOT CONNECTED). Then the tool table:

NAME — tool name (MCP tools have the prefix mcp_<server>_<tool>)
TAGS — task categories for which the tool is offered; * = always relevant
DESCRIPTION — short description the model sees

jobs

ollama-agent jobs [list | run <id> | history <id>]

jobs list — all jobs: ID, SCHEDULE, ENABLED, CATEGORY, SKILL, SOURCE (config or api), truncated PROMPT
jobs run <id> — run a job immediately, prints the result or error
jobs history <id> — recent runs: START, DURATION, TRIGGER (cron/manual), RESULT (ok / skipped (overlap) / error: ...)

Reading the output. Cron execution only runs inside the daemon (serve + scheduler.enabled). jobs run always works manually. History lives in the daemon’s memory (max 50 runs, lost on restart).

probe

Standardized capability test for all models → persistent model matrix. Run once after a fresh install.

ollama-agent probe [flags]
ollama-agent probe show

Flag	Default	Meaning
`--models <m1,m2>`	all on the endpoint	Test only these models
`--exclude <p1,p2>`	`uncensored,heretic`	Skip auto-discovered models whose name contains one of the patterns (has no effect with explicit `--models`)
`--endpoint <name>`	endpoint with highest priority	Server, or `all` for all
`--ctx-min <n>`	2048	Smallest context level (tokens)
`--ctx-max <n>`	32768	Largest context level (up to 262144)
`--skip-levels`	off	Only run the context ladder, keep existing level results (for extending to larger contexts)
`--call-timeout <duration>`	10m	Timeout per model call

What is measured per model and endpoint:

Complexity levels 1–5: simple response → follow instruction → logic → tool call → chain of two dependent tool calls
Context ladder: needle-in-haystack at growing size — the largest size the model handles on this server
Response times and stability (technical vs. content errors)
Where it ran (GPU/CPU), measured via /api/ps

probe show — reading the matrix

ollama-agent probe show

Columns:

Column	Meaning
`MODEL`, `ENDPOINT`	model and server on which it was measured
`RUNS ON`	measured, not guessed: `GPU` (fully in VRAM), `CPU` (no VRAM), `GPU nn%` (partially offloaded → slow)
`LEVEL`	Highest complexity level passed consistently (`n/5`)
`CONTEXT`	Largest context size passed in the needle test on this server
`TOK/S`	Generation speed (tokens per second)
`COLD`	Time to first response including model load
`WARM`	Response time for a short question with the model already loaded
`8K-CTX`	Response time with 8k tokens of context (realistic agent load)
`STABLE`	Number of technical errors (timeout/5xx/connection); content errors don’t count here
`LEVELS`	Detail: `1✓ 2✓ 3✗ …` — which individual level passed/failed

How to read it: LEVEL 5/5 + high CONTEXT + STABLE ok = broadly usable. LEVEL 2/5 = fails at logic/tools (only suitable for simple tasks). A model with RUNS ON GPU 60% is partially offloaded and therefore slower than its TOK/S value would suggest. Important: CONTEXT is a server property — the same model achieves less on a weaker instance.

probe deep

Context depth test: doesn’t measure whether a model finds one fact in the large context (that’s what the needle test above does), but how well it actually understands and uses the context — following the RULER principle. Each model is tested at its measured maximum context.

ollama-agent probe deep              # shows the last evaluation (starts NOTHING)
ollama-agent probe deep show         # same
ollama-agent probe deep run [flags]  # starts a test
ollama-agent probe deep run --plan   # only plan, execute nothing

Important: probe deep without run only displays and never starts a (long) test run. To start one, always use probe deep run.

Flag	Default	Meaning
`--models <m1,m2>`	all on the endpoint	Only these models
`--exclude <p1,p2>`	`uncensored,heretic`	Exclude name patterns
`--endpoint <name>`	highest priority	Server, or `all`
`--ctx <n>`	0 (= each model’s measured maximum)	Cap the test context (faster)
`--call-timeout <duration>`	15m	Timeout per model
`--plan`	off	Only list: models, target context, time estimate — executes nothing

How the test works. A coherent document (deterministically generated, different per model, nothing memorizable) fills ~85% of the window. Then, in one call, questions of increasing difficulty are asked:

Basic — trivial math question: does the model stay coherent at all under full load?
Retrieval (×1) — find individual facts verbatim, at three depths (start/middle/end, exposes “lost in the middle”)
Multi-hop (×2) — connect two facts
Aggregation (×3) — count/compare across the whole document

Reading `probe deep`

Columns:

Column	Meaning
`SCORE`	Weighted percentage of context utilization (retrieval×1, multi-hop×2, aggregation×3)
`RETRIEVAL`	`earned/max` — facts found verbatim
`MULTI-HOP`	`earned/max` — two facts correctly connected
`AGGREG.`	`earned/max` — correctly aggregated across the whole document
`BASIC`	`ok`/`✗` — trivial math correct despite full context?
`CONTEXT`	Tested window size
`DURATION`	Total time

How to read it: A high SCORE means the model genuinely uses its large context. The typical pattern is RETRIEVAL 3/3 (almost every model finds facts), but AGGREG. 0/6 — this is where it shows that many models simply don’t penetrate their context. This is exactly the difference the plain needle test can’t reveal. BASIC ✗ means the model becomes incoherent from the sheer context load alone (e.g. computes 13+29 incorrectly).

probe deep —plan

Executes nothing, but shows in advance: which models (after filtering), their target context, the estimated processing time for one context pass, and an overall time estimate (best case with prefix cache through worst case). For planning long runs.

config

ollama-agent config validate     # check the config (default with no argument)
ollama-agent config init          # print an example config to stdout

validate — loads and checks the config (endpoints, categories, cron expressions, duplicate names); reports OK with metrics or lists the errors
init — outputs a complete example config, typically: ollama-agent config init > config.json

version

ollama-agent version

Prints the build version.

Extra tool: modelbench

A separate, faster benchmark utility (not part of the agent binary), for a quick rough test without the full matrix:

go run ./cmd/modelbench -host http://<server>:11434 -models "m1,m2,..."

Flag	Default	Meaning
`-host <url>`	http://127.0.0.1:11434	Ollama server
`-models <m1,m2>`	— (required)	Models to test
`-timeout <duration>`	5m	Time budget per model

Checks per model: simple arithmetic task (correctness + speed), tool calling (structured/salvaged/none), and router suitability (4 classification inputs). For robust, persistent evaluation, probe is preferable.