CLI

The ollama binary is the project's primary deliverable. It uses spf13/cobra to dispatch among subcommands and is the same executable that runs as the daemon, the inference runner subprocess, and the launch-integration host.

Purpose

ollama lets a user pull, run, and manage local language models without writing code. Its subcommands cover every step of the model lifecycle plus the launchers that glue Ollama to third-party clients.

Directory layout

.
├── main.go                # one-line entry point
└── cmd/
    ├── cmd.go             # cobra command tree (~2,470 lines)
    ├── interactive.go     # ollama run REPL
    ├── start.go, start_*  # platform-specific daemon spawn
    ├── editor_*.go        # platform-specific external editor launch
    ├── background_*.go    # detach helpers per OS
    ├── warn_thinking_test.go
    ├── bench/             # CLI benchmarks
    ├── config/            # CLI-side config reader
    ├── internal/          # CLI internals
    ├── launch/            # ollama launch <integration>
    ├── runner/            # entry stub for the runner subprocess
    └── tui/               # bubbletea selectors and sign-in flows

Key abstractions

Symbol	Location	Purpose
cmd.NewCLI	cmd/cmd.go	Builds the cobra command tree. Single source of truth for every subcommand.
RunHandler, PullHandler, PushHandler, CreateHandler, ListHandler, ShowHandler, CopyHandler, DeleteHandler, PsHandler, ServeHandler	cmd/cmd.go	Each subcommand's main implementation.
interactiveSession	cmd/interactive.go	The ollama run REPL: reads input, streams /api/chat, renders thinking/tool-call blocks.
checkServerHeartbeat	cmd/cmd.go	PreRunE for any subcommand that talks to the daemon. Spawns ollama serve if not reachable.
tui.SelectSingle, tui.SelectMultiple, tui.RunSignIn, tui.RunConfirmWithOptions	cmd/tui/	Bubbletea pickers wired to launch.DefaultSingleSelector and friends in cmd.init.
runner.Execute	runner/runner.go	Entry point when the binary is re-execed as ollama runner ….

Subcommand map

Subcommand	Handler	Notes
serve	cmd.ServeHandler	Starts the daemon (server.Server).
run <model>	cmd.RunHandler → interactiveSession	One-shot prompt or REPL.
pull <model>	cmd.PullHandler	Calls /api/pull with progress bar.
push <model>	cmd.PushHandler	Calls /api/push.
create <model>	cmd.CreateHandler	Parses Modelfile and uploads blobs through /api/blobs/:digest then /api/create. Has an --experimental mode that goes through x/create/client/ for safetensors.
list (and aliases)	cmd.ListHandler	Tabulates /api/tags.
ps	cmd.PsHandler	Tabulates /api/ps.
show <model>	cmd.ShowHandler	Renders /api/show.
cp <src> <dst>	cmd.CopyHandler	Calls /api/copy.
rm <model>	cmd.DeleteHandler	Calls /api/delete.
stop <model>	cmd.StopHandler	Asks the daemon to evict a runner.
signin / signout / whoami	cmd/cmd.go handlers	Manage Ollama Cloud account state.
runner	runner.Execute	Re-exec target for the inference subprocess. Not user-facing.
launch <integration>	cmd/launch/launch.go	See launch integrations.

How it works

graph TD
    Main[main.go] --> NewCLI[cmd.NewCLI]
    NewCLI --> Cobra[cobra.Command tree]
    Cobra -->|user invokes| Handler[<X>Handler]
    Handler -->|HTTP| Daemon[ollama serve]
    Handler -.bubbletea pickers.-> TUI[cmd/tui]
    Handler -.spawn integration.-> ThirdParty[Claude Code, Codex, ...]
    Cobra -->|ollama runner ...| RunnerEntry[runner.Execute]
    RunnerEntry -->|--ollama-engine| OllamaRunner[ollamarunner]
    RunnerEntry -->|--mlx-engine| MLXRunner[mlxrunner]
    RunnerEntry -->|--imagegen-engine| ImageGen[imagegen]
    RunnerEntry -->|default| LlamaRunner[llamarunner]

Interactive mode

ollama run <model> enters cmd/interactive.go, built on the project's own line editor in readline/. It supports slash commands (/?, /save, /load, /show, /set, /clear, /bye), and uses progress/ for the streaming response indicator. Thinking output (when supported by the model) is rendered in a dimmed block, and tool calls are surfaced through tools/.

cmd.ensureThinkingSupport warns when the user runs a model without thinking capability. cmd.isLocalhost (cmd/cmd.go) decides whether features like the experimental safetensors creation flow can run, since some only work when the daemon and CLI are on the same machine.

TUI integration

cmd.init registers bubbletea-backed selectors with the launch package:

launch.DefaultSingleSelector = func(title string, items []launch.ModelItem, current string) (string, error) {
    ...
    return tui.SelectSingle(title, tuiItems, current)
}

The result is that ollama launch claude prompts a real bubbletea picker when run interactively but falls through to a "use --model in headless mode" error when stdin/stdout aren't a TTY.

Integration points

• Talks to the daemon over HTTP on OLLAMA_HOST (default 127.0.0.1:11434).
• Re-execs itself as the runner subprocess (see runners).
• Reads environment via envconfig/config.go.
• Uses api/client.go — the same Go client published as a public API.

Entry points for modification

• New subcommand → add to the tree in cmd.NewCLI and write a <Verb>Handler function nearby.
• New interactive slash command → extend the dispatcher in cmd/interactive.go.
• New launcher integration → see launch integrations; the CLI half is just the cobra subcommand registration.

Key source files

File	Purpose
main.go	Process entry point.
cmd/cmd.go	Cobra command tree and all subcommand handlers.
cmd/interactive.go	ollama run REPL.
cmd/tui/selector.go	Bubbletea selector models.
cmd/tui/signin.go	Sign-in flow with browser handoff.
cmd/runner/runner.go	Runner cobra subcommand stub.
runner/runner.go	Runner dispatch (see runners).