Principle:Ollama Ollama CLIDisplay
| Knowledge Sources | |
|---|---|
| Domains | CLI, Terminal UI |
| Last Updated | 2025-02-15 00:00 GMT |
Overview
CLI Display encompasses the principles of rendering dynamic progress indicators in terminal environments, including spinners, progress bars, and status messages. These visual feedback mechanisms inform users about the state of long-running operations such as model downloads, loading, and inference initialization.
Core Concepts
Spinner Animation
A terminal spinner is a character-based animation that cycles through a set of frames (commonly |, /, -, \ or Unicode Braille patterns) at a fixed interval to indicate that an indeterminate operation is in progress. Spinners are rendered by repeatedly overwriting the same terminal line using carriage return (\r) or ANSI cursor positioning sequences. The animation loop runs in a separate goroutine or timer callback and must be coordinated with the operation it represents, stopping cleanly when the operation completes, fails, or is cancelled.
Progress Bar Rendering
Progress bars display determinate progress as a visual bar that fills proportionally to completion. Rendering involves calculating the percentage complete, mapping it to a fixed-width bar of filled and empty characters, and displaying additional metadata such as transfer speed, elapsed time, estimated time remaining, and absolute counts (e.g., bytes transferred / total bytes). The bar is updated by overwriting the current terminal line, requiring careful handling of terminal width to avoid line wrapping that would break the display.
Terminal Line Management
Dynamic terminal displays require managing one or more output lines that are repeatedly overwritten. This involves using ANSI escape sequences to move the cursor (\033[A for up, \033[K for clear line), prevent scrolling past the display region, and handle terminal resize events. When multiple concurrent operations each have their own progress indicator, the display must manage a multi-line region, updating individual lines independently without disrupting others.
Status Message Lifecycle
Progress displays typically follow a lifecycle: initialization (showing the operation name), active progress (animating or updating the bar), and completion (replacing the progress indicator with a final status message such as "done" or "failed"). The lifecycle must handle interruption gracefully, ensuring that partial output is cleaned up and the terminal is left in a consistent state even if the operation is cancelled via signal (SIGINT) or context cancellation.
Implementation Notes
In the Ollama codebase, CLI display is implemented through a progress spinner module that provides animated feedback during model pull, push, and loading operations. The spinner runs on a configurable tick interval and renders using carriage return-based line overwriting. Progress bars are used for model layer downloads, displaying transfer rates and completion percentages. The display system integrates with Go's context cancellation to ensure clean shutdown of animation goroutines when operations complete or are interrupted.