tickerbox-cli

README

tickerbox-cli

Command-line client for a TickerBox device's /rest/ API.

Table of contents

• Quickstart
• Install
• Security
• Concepts
• Getting started
• Targeting a device
• Global flags
• Command groups
• Endpoints covered
• Shell completion
• Network behaviour
• Recipes
• Troubleshooting
• Tests
• Documentation

Quickstart

1. Find the device. device discover probes tickerbox.local and scans the local /24 subnet for anything that answers as a TickerBox, then offers to save each match:

$ tickerbox device discover
HOST            HOSTNAME
192.168.10.89   tickerbox
Add 192.168.10.89 as a device? [y/N]: y
Name for 192.168.10.89: office
added device office (http://192.168.10.89)

2. Check it. status pulls every dashboard endpoint in one call:

$ tickerbox --device office status
Features
Project:            yes
NTP:                yes
OTA:                yes
Upload Firmware:    yes
TickerBox:          yes
Shopify:            no
Extra ETF:          no

System
Platform:          esp32
SDK Version:       v5.1.2
CPU Frequency:     240 MHz
Free Heap:         142.3 KB
Flash Chip Size:   4.0 MB
Filesystem:        612.0 KB / 1.5 MB used

Wi-Fi
Status:        CONNECTED
SSID:          HomeNet
IP Address:    192.168.10.89
RSSI:          -52 dBm
Channel:       6
...

3. Add tickers. tickers add appends one or more symbols that share a type, refresh interval and currency:

$ tickerbox --device office tickers add --type crypto --time 15min --currency EUR BTC ETH
Added 2 ticker(s)

Set office as the default so --device office can be dropped from later commands:

tickerbox device use office

Install

$ go install github.com/openbunny/tickerbox-cli@latest

go install places the tickerbox binary in $(go env GOPATH)/bin. Prebuilt binaries, .deb and .rpm packages are attached to each release.

Homebrew, on macOS and Linux:

$ brew install oa/tap/tickerbox-cli

From a clone:

$ go build -o tickerbox .

Verify a downloaded release archive before extracting it: see SECURITY.md, Verifying releases.

Security

The TickerBox device's REST API has no authentication. Any client on the same network can call GET /rest/wifiSettings and GET /rest/apSettings and read the Wi-Fi and access-point passwords in cleartext — this is a device-firmware property, not a defect in tickerbox. tickerbox doctor always reports a plaintext credentials check at warn severity as a standing reminder.

All CLI-to-device traffic is plain HTTP; the client has no TLS path. Anyone who can observe LAN traffic to the device can read or alter a request or response, including a wifi set carrying a new password.

By default, no command writes a device secret to a local file: internal/section.Capture strips any wifi/ap field whose key contains password or secret before it reaches a snapshot. Three flags are the only paths that put a secret on disk or unmask one:

Command	Effect
profile save --all	Captures wifi/ap sections, including their passwords, into the profile file.
config export --show-secrets	Captures wifi/ap passwords into the exported snapshot file.
wifi settings --show-secrets	Unmasks the password in the live printed response only; writes no file.

A file that gains a secret this way is written 0600, the same as config.toml; Load warns to stderr, but does not refuse to read, a file that later becomes group- or other-readable. Treat it like a password file: do not commit it, do not sync it to a shared drive.

See SECURITY.md for vulnerability reporting and release verification.

Concepts

tickerbox composes four objects that look similar but serve different purposes:

• Device — an entry in the local config.toml (name → host). A network target only; never holds a credential.
• Config snapshot (config export/import/diff) — a whole-device capture: every section (tickers, display, clock, ntp, wifi, ap) in one JSON file, tied to one device's exact state. Use it to back up before a risky change and restore that same device.
• Profile (profile save/apply/diff/list/show/rm) — a named, local, device-agnostic snapshot, meant to be replayed across multiple devices. Its default section set is narrower than a config export (tickers/display/clock/ntp); --all/--include widens it.
• Template (tickers template list/show/apply) — a built-in, read-only ticker-list preset shipped in the binary. apply seeds a starting ticker list; it is not a saved, portable object like a profile — capture the result with profile save to replay it elsewhere.

	config export	profile save
Default sections	every section	tickers, display, clock, ntp
Widen with	(always full)	--all, --include
Typical target	the same device later	any device now
Named, reusable	one file per export	named, listed with profile list

How they compose: tickers template apply seeds a ticker list, tickers add/edit refines it, profile save captures the whole working config as a reusable name, and profile apply --device <other> replays it on another device. config export sits outside this chain — a same-device backup/restore tool, not a reuse tool.

Getting started

The Quickstart above discovers a device, checks it, and adds tickers. From there:

1. Run tickerbox --device office doctor once before changing anything, to see baseline health and the standing plaintext credentials note (see Security).
2. Set the clock: tickerbox --device office tz set "Europe/London", then tickerbox --device office ntp set.
3. Replace a manual ticker list with a built-in preset: tickerbox --device office tickers template list, then tickerbox --device office tickers template apply crypto-majors.
4. Tune the display: tickerbox --device office display set, tickerbox --device office brightness 180.
5. Save the result as a reusable profile: tickerbox --device office profile save office — see Concepts for what that captures versus config export.

Targeting a device

tickerbox resolves the device host once per invocation, in this order:

Precedence	Source	Example
1	--host URL	--host http://192.168.10.89
2	--device NAME (-d)	--device office, a name registered with device add
3	TICKERBOX_HOST environment variable	TICKERBOX_HOST=http://192.168.10.89 tickerbox status
4	The default device set with device use	tickerbox device use office
5	http://tickerbox.local, resolved by the OS's mDNS resolver	no flag, no env var, no default set

The first source with a value wins; lower rows are never consulted once a higher one resolves.

$ tickerbox device add office http://192.168.10.89
added device office (http://192.168.10.89)
$ tickerbox device use office
default device set to office
$ tickerbox --device office wifi status

Note device add and device use only edit the local device config file (tickerbox device list shows its path); neither makes a request to the device.

Global flags

These are persistent flags on the root command, so they go before the command group: tickerbox --host http://10.0.0.5 --timeout 5s wifi status.

Flag	Effect
--host URL	Device base URL. Overrides --device, $TICKERBOX_HOST and the default device.
-d, --device NAME	Named device from the config file.
-j, --json	Emit raw device JSON instead of a decoded table.
--retry N	Retry an idempotent request up to N times on a transient failure (default 2).
--timeout D	Per-request timeout, e.g. 5s (default 10s).

Command groups

Group	Purpose	Example
status	Aggregate dashboard: features, system, network, AP, NTP, display and clock state in one call.	tickerbox status, or --all for every configured device
wifi	Station SSID, credentials, static IP, and network scan.	tickerbox wifi scan
ap	The device's own access point.	tickerbox ap status
ntp	NTP sync configuration, including timezone.	tickerbox ntp set --tz "Europe/London"
time	Set the device wall-clock time; with no argument, sends the current UTC instant.	tickerbox time 2026-01-01T00:00:00
tz	Timezone lookup and device timezone.	tickerbox tz list --grep Europe, tickerbox tz set "Europe/London"
display	Ticker screen brightness, rotation interval, sleep schedule.	tickerbox display settings
clock	Clock screen.	tickerbox clock set --enabled
brightness	Shortcut for display brightness: set, or step up/down.	tickerbox brightness 180, tickerbox brightness up 20
uptime	Device uptime since last boot, formatted as 1d 2h 3m 4s.	tickerbox uptime
reboot	Shortcut for system restart, with a confirmation prompt.	tickerbox reboot -y
tickers	The asset list shown on the display: add, edit, move, remove, clear, list, export, import, validate, template.	tickerbox tickers add --type crypto --time 15min --currency EUR BTC ETH
system	Device status, features, and maintenance actions. restart, factory-reset and firmware-upload mutate the device and prompt for confirmation unless --yes/-y is given.	tickerbox system info
config	Whole-device config as one JSON snapshot, covering every section (tickers, display, clock, ntp, wifi, ap).	tickerbox config export --file office.json
profile	Named, device-agnostic snapshots stored locally; default section set is tickers/display/clock/ntp (--all or --include widens it). --all also captures the device's WiFi/AP passwords into the local snapshot file.	tickerbox profile save office
device	The local device registry: add NAME HOST, use NAME, list, rm NAME, ping [NAME|--all], discover (LAN scan for TickerBoxes).	tickerbox device discover
doctor	Read-only health check (heap, filesystem headroom, wifi, NTP, AP exposure); exits non-zero on a critical finding.	tickerbox doctor --all
watch	Re-runs a read-only view (status by default) on an interval until interrupted; refuses any command that is not read-only.	tickerbox watch tickers list --interval 5s
version	CLI build version.	tickerbox version
open (alias ui)	Opens the device's web UI in the default browser.	tickerbox open

tickers add (SYM... form shown above) merges what was formerly a single-ticker add; every symbol given shares one --type/--time/ --currency.

tickers subcommands

Subcommand	Effect	Example
add SYM...	Append tickers sharing one type/time/currency.	tickerbox tickers add --type crypto --time 15min --currency EUR BTC ETH
edit <index|sym>	Change one entry in place, by index or symbol.	tickerbox tickers edit BTC --time 5min
move <from> <to>	Reorder the display cycle.	tickerbox tickers move 3 1
remove <index|sym>	Remove one entry.	tickerbox tickers remove BTC
clear	Remove every entry.	tickerbox tickers clear
list	List configured tickers.	tickerbox tickers list
export / import	Round-trip the list as JSON.	tickerbox tickers export --file list.json
validate	Report illegal fields and duplicate symbols without changing anything.	tickerbox tickers validate
template list / show <name> / apply <name>	Built-in presets.	tickerbox tickers template apply crypto-majors

Endpoints covered

Command	Method	Endpoint
status	GET	features, systemStatus, wifiStatus, apStatus, ntpStatus, settingsState, clockSetupState
wifi status	GET	wifiStatus
wifi settings	GET	wifiSettings
wifi set	GET, POST	wifiSettings
wifi scan	GET	scanNetworks, listNetworks
ap status	GET	apStatus
ap settings	GET	apSettings
ap set	GET, POST	apSettings
ntp status	GET	ntpStatus
ntp settings	GET	ntpSettings
ntp set	GET, POST	ntpSettings
time	POST	time
tz set	GET, POST	ntpSettings, clockSetupState
tz list	—	bundled timezones.json, no device call
display settings	GET	settingsState
display set	GET, POST	settingsState
brightness, brightness up/down	GET, POST	settingsState
clock settings	GET	clockSetupState
clock set	GET, POST	clockSetupState
tickers list/add/edit/move/remove/clear/export/import/validate/template apply	GET, POST	coinSetupState
tickers template list/show	—	bundled presets, no device call
system info	GET	systemStatus
system features	GET	features
system restart, reboot	POST	restart
system factory-reset	POST	factoryReset
system firmware-upload	POST (multipart)	uploadFirmware
uptime	GET	ntpStatus
config export/diff/import	GET, POST	coinSetupState, settingsState, clockSetupState, ntpSettings, wifiSettings, apSettings
profile save/apply/diff	GET, POST	same section set as config, restricted to what was captured
device discover/ping	GET	features (probe only, to confirm a host is a TickerBox)
doctor	GET	features, systemStatus, wifiStatus, apStatus, ntpStatus

device add, device use, device list, device rm, profile list/show/rm, tz list and version make no device call.

Shell completion

tickerbox completion generates a shell completion script; it is a cobra built-in, not a project-specific feature, so its behaviour follows cobra's current documentation for the subcommand of your shell.

Shell	Load for this session	Install for every session
bash	source <(tickerbox completion bash)	tickerbox completion bash > /etc/bash_completion.d/tickerbox (Linux) or tickerbox completion bash > $(brew --prefix)/etc/bash_completion.d/tickerbox (macOS); requires the bash-completion package
zsh	source <(tickerbox completion zsh)	tickerbox completion zsh > "${fpath[1]}/_tickerbox"; requires compinit enabled in ~/.zshrc
fish	tickerbox completion fish | source	tickerbox completion fish > ~/.config/fish/completions/tickerbox.fish
powershell	tickerbox completion powershell | Out-String | Invoke-Expression	add that line to your PowerShell profile

$ tickerbox completion bash --help
Generate the autocompletion script for the bash shell.

This script depends on the 'bash-completion' package.
If it is not installed already, you can install it via your OS's package manager.

To load completions in your current shell session:

	source <(tickerbox completion bash)
...

Network behaviour

tickerbox makes network calls only to the device host resolved from --host, --device, $TICKERBOX_HOST, or the default device (see Targeting a device). It never contacts any host outside that resolution and does not phone home.

Two exceptions send LAN broadcasts instead of a request to the resolved host: device discover probes tickerbox.local and every address in the local /24 subnet, and device ping probes each configured device, both looking only for TickerBoxes on the local network.

tickerbox does not check for updates on its own. version reports the build embedded at compile time and makes no request.

Recipes

Provision a device end to end.

$ tickerbox device discover
$ tickerbox device use office
$ tickerbox tz set "Europe/London"
$ tickerbox tickers template apply crypto-majors
$ tickerbox display set
$ tickerbox doctor

Mirror one device's settings to several others.

$ tickerbox --device office profile save office
$ tickerbox profile apply office --device kitchen
$ tickerbox profile apply office --device lobby

The default section set is tickers/display/clock/ntp; widen with --all/--include if wifi/ap should also be replayed — see Concepts.

Back up before a factory-reset.

$ tickerbox --device office config export --file office-backup.json
$ tickerbox --device office system factory-reset
$ tickerbox --device office config import --file office-backup.json

Fleet health check.

$ tickerbox doctor --all --json | jq .

doctor exits non-zero exactly when any device's verdict is critical; wire the exit code into cron or CI — see Troubleshooting.

Watch a dashboard while making changes elsewhere.

$ tickerbox watch status --interval 5s

watch only accepts a read-only view; see Troubleshooting for the exact allow-list.

Troubleshooting

doctor checks.

Check	Condition
plaintext credentials	always reported at warn — see Security
free heap	critical below 20 KiB free, warn below 50 KiB free
fs headroom	critical below 8 KiB free, warn below 32 KiB free
wifi	critical if station status is not CONNECTED
ntp	warn if not ACTIVE
ap exposure	warn if the device's own AP is ACTIVE or LINGERING

A fetch failure for any underlying endpoint (features, systemStatus, wifiStatus, apStatus, ntpStatus) is reported as its own critical check rather than aborting the run.

Exit code. doctor exits non-zero exactly when any device's aggregate verdict is critical; a run with only warn/ok checks exits 0. With --all, this is evaluated per device. doctor --all with no devices configured fails with no devices configured: --all has nothing to check — run device add first.

watch refuses a target. Error: "<command>" is not a read-only view watch can re-run. Only these targets are allowed: status, system info, system features, wifi status, wifi settings, ap status, ap settings, ntp status, ntp settings, display settings, clock settings, tz list, tickers list. With no argument, watch re-runs status.

Common CLI-side errors.

Symptom	Likely cause	Fix
Request to tickerbox.local fails	Device not resolvable by mDNS from this host, or on a different subnet.	Run device discover, or set --host to its IP directly.
unknown device on --device NAME	Name not in config.toml.	device list to see registered names.
Request times out	Device slow to respond, or wrong host.	Raise --timeout; confirm the host with device ping.
Transient failure on an idempotent command	One dropped packet on the LAN.	Already retried up to --retry times (default 2); raise it for a flaky link.

Tests

$ go test ./...
ok  	github.com/openbunny/tickerbox-cli/cmd	0.412s
ok  	github.com/openbunny/tickerbox-cli/internal/client	0.038s
ok  	github.com/openbunny/tickerbox-cli/internal/config	0.021s
...

Tests use net/http/httptest; they never contact a device.

Documentation

• CLI reference — every command and flag, generated from the cobra command tree.
• Configuration schema — the on-disk device config and profile store: location, permissions, field reference.
• docs/README.md — index of the above plus the profile-snapshot JSON schema and the timezone-data provenance record.
• SECURITY.md — vulnerability reporting and release verification.