Command reference
txtop opens the TUI when no command is given. Every command accepts --help at
its own level; this page names the supported command families and the maintenance
commands used elsewhere in the documentation.
TUI
txtop [OPTIONS]
Common options:
| Option | Purpose |
|---|---|
--config <PATH> |
Read another config file |
--refresh-interval-seconds <SECONDS> |
Override collector refresh cadence |
--theme <NAME> |
Select classic, vivid, high-contrast, warm, or cool |
--graph-scale <MODE> |
Select linear, log, or share |
--subscription-enabled <BOOL> |
Enable local subscription scanning |
--openai-enabled <BOOL> |
Override OpenAI auto-enablement |
--anthropic-enabled <BOOL> |
Override Anthropic auto-enablement |
--openrouter-enabled <BOOL> |
Override OpenRouter auto-enablement |
Run txtop --help for every scalar and provider override. CLI values have the
highest configuration precedence.
Collector lifecycle
| Command | Purpose |
|---|---|
txtop up [--config <PATH>] |
Start a persistent background collector |
txtop down |
Stop the collector |
txtop status |
Show collector state and process id |
A bare TUI starts a collector only while a TUI needs it. txtop up promotes an
automatically started collector to a persistent service.
The experimental OTLP receiver uses hidden collector flags documented in ingest OpenTelemetry.
Ollama proxy
txtop ollama <COMMAND>
The commands are run, start, up, hijack-default, stop, status,
doctor, print-env, map-model, and refresh-catalog. See
track Ollama usage for the safe setup sequence.
Database diagnostics
txtop db <COMMAND>
| Command | Purpose |
|---|---|
doctor |
Summarize database, source, projector, and collector health |
events |
Filter recent structured runtime and provider events |
backfill-status |
Inspect recent API backfill runs |
query |
Read recent minutes, daily costs, subscription events, or backfill runs |
check-invariants |
Check projected totals and storage invariants |
debug-bundle |
Write a redacted diagnostic bundle for review |
repair |
Rebuild subscription rollups after confirmation |
delete |
Delete the usage database after confirmation |
reset |
Reset database and config state after confirmation |
Use --json where a subcommand offers it. Destructive commands prompt for
confirmation; pass --yes to skip the prompt.
The remaining db and debug commands support development, soak testing, and
dashboard replay. Inspect their nested help before use.