Guide

Configuration

octoscope reads an optional TOML file at ~/.config/octoscope/config.toml (it honours $XDG_CONFIG_HOME). Every key is optional and falls back to a default; CLI flags override the file per run.

The file is not created automatically — drop the snippet below in to start. A malformed file makes octoscope exit with a clear error rather than silently ignoring your settings.

A complete config.toml

# ~/.config/octoscope/config.toml

# Auto-refresh cadence. Go duration syntax; floored at 5s.
refresh_interval = "1m"

# Hide private repos / PRs / issues from the list tabs.
public_only = false
# Dense card layout in the Overview tab.
compact = false

# Theme + optional accent override (#RGB / #RRGGBB or 0-255).
theme = "octoscope"
accent_color = ""

# Seed the list tabs at startup.
default_sort         = ""   # pushed|stars|forks|name|ci|release|updated|repo|number
default_work_filter  = ""   # prs-open|ci-broken|stale
default_star_history = ""   # density|cumulative

# Sticky sections, persisted as you pin.
pinned_repos  = ["gfazioli/octoscope"]
pinned_issues = ["gfazioli/octoscope#12"]
# Repos you don't own, monitored in a dedicated section.
watch_repos   = ["charmbracelet/bubbletea"]

# The launch sponsor splash, and the update check.
show_sponsor      = true
check_for_updates = true

Key reference

`refresh_interval`	Go duration (`30s`, `1m`, `5m`). Default `"1m"`; anything below 5s is floored to 5s.
`public_only`	Hide private items from the lists. Default `false`. Toggle live with `p`.
`compact`	Denser Overview cards. Default `false`.
`theme`	One of the seven palettes. Default `"octoscope"`. See Themes.
`accent_color`	Override just the accent — `#RGB` / `#RRGGBB` or an ANSI-256 index. Default empty (theme's own).
`default_sort`	Seed the list sort: `pushed · stars · forks · name · ci · release` (Repos) or `updated · repo · number` (PRs/Issues).
`default_work_filter`	Seed the Repos work filter: `prs-open · ci-broken · stale`.
`default_star_history`	Seed the star sparkline: `density` or `cumulative`.
`pinned_repos`	Array of `owner/name` to pin atop the Repos tab. Persisted as you press `P`.
`pinned_issues`	Array of `owner/name#N` to pin atop the Issues tab.
`watch_repos`	Array of `owner/name` you don't own, shown in a watched section.
`show_sponsor`	The one-time launch sponsor splash. Default `true`. (Suppressed under `--public-only`.)
`check_for_updates`	The launch/hourly update check. Default `true`. octoscope never self-updates.

A malformed pinned_* or watch_repos entry is dropped quietly rather than failing the whole file; an invalid theme / default_* value is rejected loudly at startup with the accepted set named.

The in-app settings panel

Press , for a live panel: refresh interval, compact and public-only toggles, the theme cycler, the accent colour override and the sponsor splash toggle. Save (Enter) applies immediately and writes back to the file — atomically, comments intact, and no key you didn't touch is ever dropped.