yalethom.as/txtop

Configuration reference

txtop reads config.toml from the operating system’s standard per-user config directory. Pass --config <PATH> to use another file.

Platform Config Data and collector state
Linux ${XDG_CONFIG_HOME:-~/.config}/txtop/config.toml ${XDG_DATA_HOME:-~/.local/share}/txtop/
macOS ~/Library/Application Support/txtop/config.toml ~/Library/Application Support/txtop/
Windows %APPDATA%\txtop\config.toml %LOCALAPPDATA%\txtop\

The data directory contains usage.db, events.db, and collector lifecycle files. The optional live-agent registry is agents.toml next to config.toml.

Configuration precedence is highest to lowest:

  1. CLI flags
  2. TXTOP_* environment variables
  3. Config file
  4. Built-in defaults

Changes made in the Config panel are written to the active config file. Start with examples/config.toml, or follow see your first usage data for a guided setup.

Top-level fields

Field Default Values or purpose
refresh_interval_seconds 300 Background refresh cadence; must be greater than zero
openai_backfill_enabled false Fetch historical OpenAI usage in chunks
api_backfill_max_days 3 Maximum backfill lookback; must be greater than zero
show_backfill_debug_row false Show backfill status in the dashboard summary
runtime_event_logging false Write structured TUI events to the configured trace log
theme "vivid" classic, vivid, high-contrast, warm, or cool
graph_scale "linear" linear, log, or share
dashboard_hover_legend true Draw the legend inside the graph

Focus view

[focus]
graph_scale = "share"
time_bucket = "auto"

graph_scale accepts the normal graph scale values. Omit it to inherit the dashboard scale. time_bucket accepts inherit, auto, 10m, 1h, 1d, or 1w; the default is auto.

Subscription fields

[subscription]
enabled = true
codex_enabled = true
claude_code_enabled = true
gemini_cli_enabled = true
rescan_interval_seconds = 300
scan_workers = 2
additional_log_paths = ["/path/to/usage.jsonl"]
Field Default Purpose
enabled false Enable local subscription log scanning
codex_enabled false Scan Codex logs
claude_code_enabled false Scan Claude Code logs
gemini_cli_enabled false Scan Gemini CLI logs
rescan_interval_seconds 300 Scan cadence; must be greater than zero
scan_workers 2 Parallel scan workers; must be greater than zero
additional_log_paths [] Extra usage-log files; config-file only

Each source must be enabled explicitly. txtop discovers its standard log paths and fingerprints files for incremental scans.

For setup and verification, see track local coding-agent usage.

Live limits

Live limits require the subscription system, the global auth gate, the source, and its source-specific auth gate:

[subscription]
enabled = true
auth_requests_enabled = true

codex_enabled = true
codex_auth_requests_enabled = true

claude_code_enabled = true
claude_code_auth_requests_enabled = true
claude_code_live_limits_transport = "auto"
Field Default Purpose
auth_requests_enabled false Global gate for credential-backed requests
codex_auth_requests_enabled true Source gate for Codex live limits
claude_code_auth_requests_enabled true Source gate for Claude Code live limits
claude_code_live_limits_transport "auto" auto, oauth-usage, or quota-probe

These requests use locally stored credentials and undocumented provider behavior. They may break without notice and may violate provider terms of service; follow enable live subscription limits and review unofficial integrations before opting in.

API providers

[providers.openai]
enabled = true
api_key_env = "OPENAI_API_KEY"
# api_key = "..."
base_url = "https://api.openai.com"

[providers.anthropic]
enabled = true
api_key_env = "ANTHROPIC_API_KEY"
base_url = "https://api.anthropic.com"

[providers.openrouter]
enabled = true
api_key_env = "OPENROUTER_API_KEY"
base_url = "https://openrouter.ai"

[providers.ollama]
enabled = true
api_key_env = "OLLAMA_HOST"
base_url = "http://127.0.0.1:11434"

enabled overrides credential-based auto-enablement. api_key_env changes the credential environment variable; api_key stores a credential directly in the config file. Prefer environment variables. base_url must use HTTPS; plain HTTP is allowed only for loopback hosts.

OpenAI and Anthropic usage endpoints may require administrator credentials. txtop recognizes OPENAI_ADMIN_KEY and OPENAI_ADMIN_API_KEY for OpenAI; it recognizes ANTHROPIC_ADMIN_KEY and ANTHROPIC_ADMIN_API_KEY for Anthropic. These fixed aliases take precedence over the regular provider credential and can auto-enable the provider.

Ollama uses base_url as its local endpoint; its api_key_env default is retained for compatibility with OLLAMA_HOST.

For a task-oriented setup, see connect a provider API.

Model mappings

Model mappings can rename a raw model, combine it with an equivalent model, or use another model for pricing:

[model_mappings."local-model-name"]
display_name = "Local model"
equivalent_to = "canonical-model-name"
price_model = "openai/gpt-4.1-mini"

All fields are optional. The Config panel can manage mappings discovered in stored usage data.

Environment variables

Scalar config fields use TXTOP_ plus an uppercase field name. Subscription fields keep their section name; focus fields use TXTOP_FOCUS_DEFAULT_GRAPH_SCALE and TXTOP_FOCUS_DEFAULT_TIME_BUCKET:

export TXTOP_REFRESH_INTERVAL_SECONDS=60
export TXTOP_THEME=warm
export TXTOP_FOCUS_DEFAULT_TIME_BUCKET=1h
export TXTOP_SUBSCRIPTION_ENABLED=true
export TXTOP_SUBSCRIPTION_CODEX_ENABLED=true

Provider fields use the same pattern:

export TXTOP_OPENAI_ENABLED=true
export TXTOP_OPENAI_API_KEY_ENV=WORK_OPENAI_API_KEY
export TXTOP_OPENAI_BASE_URL=https://api.openai.com

TXTOP_<PROVIDER>_API_KEY supplies a credential directly to txtop. The unprefixed credential named by api_key_env, such as OPENAI_API_KEY, is the usual choice.

additional_log_paths and model mappings are config-file only.

CLI flags

CLI flags mirror scalar and provider settings; they take highest precedence. Use the binary as the source of truth:

txtop --help
txtop --version
txtop up --config ./config.toml
txtop ollama --help
txtop db --help

An automatically managed collector inherits the TUI’s effective CLI and config arguments. A persistent collector started with txtop up reads the default config unless --config <PATH> is supplied; environment variables are inherited in either case.

Subcommands have their own help. For example: txtop db doctor --help.

The command reference describes the supported command families and database maintenance tools.

Internal and development values

http_trace and use_fake_data exist in internal application state but are not stable config-file fields. HTTP tracing is a diagnostic CLI/environment option; fake data requires the demo build feature. They are outside the documented 1.x configuration contract.