Befehlsreferenz

Vollständige Übersicht aller CLI-Kommandos, ihrer Flags und — wichtig — wie die Ausgabe zu lesen ist. Für Konzepte und Konfiguration siehe Konfiguration.

ollama-agent [-config <pfad>] <kommando> [flags]

Globales Flag -config (vor dem Kommando): Pfad zur JSON-Config. Ohne Angabe wird gesucht: $OLLAMA_AGENT_CONFIG → ./config.json → ~/.ollama-agent/config.json.

Kurzübersicht:

Kommando	Zweck
`run`	Einen Prompt einmalig durch den Agent laufen lassen
`chat`	Interaktive Chat-Sitzung mit Gedächtnis
`serve`	Daemon: HTTP-API + Scheduler + MCP-Verbindungen
`endpoints`	Status der Ollama-Server (Erreichbarkeit, Modelle)
`models`	Modelle je Server + Task-Zuordnung
`skills`	Skills auflisten/anzeigen
`tools`	Verfügbare Tools (built-in + MCP)
`jobs`	Scheduler-Jobs verwalten
`probe`	Modell-Fähigkeitstest → Matrix
`probe deep`	Kontext-Tiefentest (Verständnis-Score)
`config`	Config prüfen / Beispiel erzeugen
`version`	Version anzeigen

run

Führt einen einzelnen Prompt aus und beendet sich. Kein Daemon nötig.

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

Flag	Bedeutung
`--model <name>`	Modell fest vorgeben, überspringt das automatische Routing
`--category <kat>`	Task-Kategorie aus der Config erzwingen (überspringt die Klassifikation)
`--skill <name>`	Diesen Skill vorab in den Kontext laden
`--no-stream`	Antwort komplett am Stück ausgeben statt tokenweise
`--json`	Ergebnis als JSON (mit Modell, Kategorie, Tool-Calls, Token-Zählern)

Auswertung. Standardmäßig wird die Antwort live gestreamt. Mit --json bekommst du ein Objekt:

output — die Antwort
model — welches Modell tatsächlich lief (nach Routing/Failover)
category — erkannte oder erzwungene Task-Kategorie
skill — automatisch geladener Skill (falls Trigger griff)
tool_calls[] — jeder Tool-Aufruf mit tool, args, result, ggf. error und salvaged (true = aus Plain-Text gerettet, das Modell gab keinen sauberen Tool-Call aus)
iterations — wie viele Loop-Runden es brauchte
usage — prompt_tokens / output_tokens

Ein hoher iterations-Wert oder viele salvaged-Calls deuten auf ein Modell hin, das mit Tools kämpft.

chat

Interaktive REPL mit Konversationsgedächtnis.

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

Meta-Kommandos in der Sitzung:

/model <name> — Modell wechseln, /model auto schaltet zurück auf automatisches Routing
/reset — Gesprächsverlauf löschen
/quit (oder /exit) — beenden

Auswertung. Nach jeder Antwort erscheint bei Tool-Nutzung eine Zeile (N tool call(s), model X). Der Verlauf wird bei Bedarf automatisch komprimiert (History-Kompaktierung), wenn er dem Kontextfenster des Modells nahekommt.

serve

Startet den Daemon: HTTP-API, Scheduler (wenn scheduler.enabled) und die MCP-Server-Verbindungen.

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

Flag	Bedeutung
`-addr <host:port>`	Lauschadresse, übersteuert `api.addr` aus der Config

Auswertung. Beim Start werden Adresse, Anzahl Endpoints, Skills und Tools ausgegeben, dann eine Zeile pro HTTP-Request. Vollständige API-Beschreibung: HTTP-API-Referenz. Sauberer Stopp mit Strg-C.

endpoints

Pingt alle konfigurierten Ollama-Server und zeigt Erreichbarkeit und Modellanzahl.

ollama-agent endpoints

Auswertung. Spalten:

NAME, URL — aus der Config
STATUS — up oder DOWN
LATENCY — Antwortzeit des Version-Pings
MODELS — Anzahl vorhandener Modelle, bei DOWN stattdessen die Fehlermeldung

Exit-Code 1, wenn mindestens ein Server down ist — dadurch als Monitoring-Check in Skripten/Cron nutzbar.

models

Zeigt, welches Modell auf welchem Server liegt, plus die Task-Zuordnung aus der Config.

ollama-agent models

Auswertung. Erst eine Tabelle MODELL → ENDPOINTS (auf welchen Servern jedes Modell verfügbar ist). Dann die Task-Zuordnung:

CATEGORY — die Task-Kategorie
MODELS — die Präferenzliste aus der Config (in Reihenfolge)
AVAILABLE — welches Modell davon aktuell tatsächlich erreichbar ist (das würde bei einer Anfrage dieser Kategorie gewählt); - heißt: keines verfügbar, es greift models.default

skills

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

skills oder skills list — Tabelle aller gefundenen Skills: NAME, DESCRIPTION, TRIGGERS, SCRIPTS (Anzahl)
skills show <name> — vollständiger Inhalt eines Skills (Beschreibung, Trigger, Scripts, Pfad, Body)

Auswertung. Die TRIGGERS bestimmen, bei welchen Stichwörtern im Prompt ein Skill automatisch geladen wird (wenn skills.auto_load_on_trigger). SCRIPTS > 0 bedeutet, der Skill bringt Hilfsskripte mit (nur ausführbar bei skills.allow_scripts: true).

tools

ollama-agent tools

Verbindet sich einmalig zu den MCP-Servern und listet alle verfügbaren Tools.

Auswertung. Zuerst je MCP-Server eine Statuszeile (connected / NOT CONNECTED). Dann die Tool-Tabelle:

NAME — Tool-Name (MCP-Tools mit Präfix mcp_<server>_<tool>)
TAGS — Task-Kategorien, für die das Tool angeboten wird; * = immer relevant
DESCRIPTION — Kurzbeschreibung, die das Modell sieht

jobs

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

jobs list — alle Jobs: ID, SCHEDULE, ENABLED, CATEGORY, SKILL, SOURCE (config oder api), gekürzter PROMPT
jobs run <id> — Job sofort ausführen, gibt Ergebnis oder Fehler aus
jobs history <id> — letzte Läufe: START, DURATION, TRIGGER (cron/manual), RESULT (ok / skipped (overlap) / error: ...)

Auswertung. Die Cron-Ausführung läuft nur im Daemon (serve + scheduler.enabled). jobs run funktioniert immer manuell. Die History liegt im Speicher des Daemons (max. 50 Läufe, geht bei Neustart verloren).

probe

Standardisierter Fähigkeitstest aller Modelle → persistente Modell-Matrix. Nach einer Neuinstallation einmal ausführen.

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

Flag	Default	Bedeutung
`--models <m1,m2>`	alle auf dem Endpoint	Nur diese Modelle testen
`--exclude <p1,p2>`	`uncensored,heretic`	Auto-entdeckte Modelle überspringen, deren Name eines der Muster enthält (bei explizitem `--models` wirkungslos)
`--endpoint <name>`	Endpoint mit höchster Priorität	Server, oder `all` für alle
`--ctx-min <n>`	2048	Kleinste Kontextstufe (Tokens)
`--ctx-max <n>`	32768	Größte Kontextstufe (bis 262144)
`--skip-levels`	aus	Nur die Kontext-Leiter laufen, vorhandene Stufen-Ergebnisse behalten (zum Erweitern auf größere Kontexte)
`--call-timeout <dauer>`	10m	Timeout pro Modell-Call

Was gemessen wird pro Modell und Endpoint:

Komplexitätsstufen 1–5: einfache Antwort → Anweisung befolgen → Logik → Tool-Aufruf → Kette aus zwei abhängigen Tool-Aufrufen
Kontext-Leiter: Needle-in-Haystack bei wachsender Größe — die größte Größe, die das Modell auf diesem Server bewältigt
Antwortzeiten und Stabilität (technische vs. inhaltliche Fehler)
Wo es lief (GPU/CPU), gemessen per /api/ps

probe show — Auswertung der Matrix

ollama-agent probe show

Spalten:

Spalte	Bedeutung
`MODELL`, `ENDPOINT`	Modell und Server, auf dem gemessen wurde
`LÄUFT AUF`	gemessen, nicht geraten: `GPU` (voll im VRAM), `CPU` (kein VRAM), `GPU nn%` (teilweise ausgelagert → langsam)
`STUFE`	Höchste durchgängig bestandene Komplexitätsstufe (`n/5`)
`KONTEXT`	Größte im Needle-Test bestandene Kontextgröße auf diesem Server
`TOK/S`	Generierungstempo (Token pro Sekunde)
`KALT`	Zeit für die erste Antwort inkl. Modell-Laden
`WARM`	Antwortzeit auf eine kurze Frage bei geladenem Modell
`8K-KTX`	Antwortzeit mit 8k Tokens Kontext (realistische Agent-Last)
`STABIL`	Anzahl technischer Fehler (Timeout/5xx/Verbindung); inhaltlich falsche Antworten zählen hier nicht
`STUFEN`	Detail: `1✓ 2✓ 3✗ …` — welche Einzelstufe bestanden/gescheitert

So liest man es: STUFE 5/5 + hoher KONTEXT + STABIL ok = rundum brauchbar. STUFE 2/5 = scheitert an Logik/Tools (nur für einfache Aufgaben). Ein Modell mit LÄUFT AUF GPU 60% ist teilweise ausgelagert und dadurch langsamer als sein TOK/S-Wert vermuten ließe. Wichtig: KONTEXT ist eine Server-Eigenschaft — dasselbe Modell schafft auf einer schwächeren Instanz weniger.

probe deep

Kontext-Tiefentest: misst nicht, ob ein Modell einen Fakt im großen Kontext findet (das macht der Needle-Test oben), sondern wie gut es den Kontext wirklich versteht und nutzt — nach dem RULER-Prinzip. Jedes Modell wird auf seinem gemessenen Maximalkontext getestet.

ollama-agent probe deep              # zeigt die letzte Auswertung (startet NICHTS)
ollama-agent probe deep show         # dito
ollama-agent probe deep run [flags]  # startet einen Test
ollama-agent probe deep run --plan   # nur planen, nichts ausführen

Wichtig: probe deep ohne run zeigt nur an und startet nie einen (langen) Testlauf. Zum Starten immer probe deep run.

Flag	Default	Bedeutung
`--models <m1,m2>`	alle auf dem Endpoint	Nur diese Modelle
`--exclude <p1,p2>`	`uncensored,heretic`	Namensmuster ausschließen
`--endpoint <name>`	höchste Priorität	Server, oder `all`
`--ctx <n>`	0 (= je Modell dessen gemessenes Maximum)	Testkontext deckeln (schneller)
`--call-timeout <dauer>`	15m	Timeout pro Modell
`--plan`	aus	Nur auflisten: Modelle, Zielkontext, Zeitschätzung — führt nichts aus

Wie der Test funktioniert. Ein kohärentes Dokument (deterministisch generiert, pro Modell anders, nichts memorierbar) füllt ~85% des Fensters. Dann werden in einem Aufruf Fragen steigender Schwierigkeit gestellt:

Basis — triviale Mathe-Frage: bleibt das Modell unter Volllast überhaupt kohärent?
Retrieval (×1) — einzelne Fakten wörtlich finden, an drei Tiefen (Anfang/Mitte/Ende, deckt „lost in the middle” auf)
Multi-Hop (×2) — zwei Fakten verknüpfen
Aggregation (×3) — über das ganze Dokument zählen/vergleichen

Auswertung von `probe deep`

Spalten:

Spalte	Bedeutung
`SCORE`	Gewichteter Prozentwert der Kontextnutzung (Retrieval×1, Multi-Hop×2, Aggregation×3)
`RETRIEVAL`	`earned/max` — Fakten wörtlich gefunden
`MULTI-HOP`	`earned/max` — zwei Fakten korrekt verknüpft
`AGGREGAT.`	`earned/max` — korrekt über das ganze Dokument aggregiert
`BASIS`	`ok`/`✗` — triviale Mathe trotz vollem Kontext korrekt?
`KONTEXT`	Getestete Fenstergröße
`DAUER`	Gesamtzeit

So liest man es: Ein hoher SCORE heißt, das Modell nutzt seinen großen Kontext wirklich. Das typische Muster ist RETRIEVAL 3/3 (Fakten findet fast jedes Modell), aber AGGREGAT. 0/6 — hier zeigt sich, dass viele Modelle ihren Kontext eben nicht durchdringen. Genau diesen Unterschied macht der reine Needle-Test unsichtbar. BASIS ✗ bedeutet, das Modell wird schon durch die schiere Kontextlast inkohärent (rechnet z. B. 13+29 falsch).

probe deep —plan

Führt nichts aus, sondern zeigt vorab: welche Modelle (nach Filter), deren Zielkontext, die geschätzte Prozessierungszeit für einen Kontext-Durchlauf und eine Gesamt-Zeitschätzung (best case mit Prefix-Cache bis worst case). Zum Planen langer Läufe.

config

ollama-agent config validate     # Config prüfen (Default ohne Argument)
ollama-agent config init          # Beispiel-Config nach stdout

validate — lädt und prüft die Config (Endpoints, Kategorien, Cron-Ausdrücke, doppelte Namen); meldet OK mit Kennzahlen oder listet die Fehler
init — gibt eine vollständige Beispiel-Config aus, üblich: ollama-agent config init > config.json

version

ollama-agent version

Gibt die Build-Version aus.

Zusatz-Tool: modelbench

Ein separates, schnelleres Benchmark-Utility (kein Teil des Agent-Binaries), für einen groben Schnelltest ohne die volle Matrix:

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

Flag	Default	Bedeutung
`-host <url>`	http://127.0.0.1:11434	Ollama-Server
`-models <m1,m2>`	— (Pflicht)	Zu testende Modelle
`-timeout <dauer>`	5m	Zeitbudget pro Modell

Prüft je Modell: einfache Rechenaufgabe (Korrektheit + Tempo), Tool-Calling (structured/salvaged/none) und Router-Eignung (4 Klassifikations-Inputs). Für die belastbare, persistente Auswertung ist probe vorzuziehen.