spaceapi-tui

A small TUI for posting updates to the SpaceAPI endpoint, built on gum for the UI and libsecret for credential storage.

Why

The shell scripts under scripts/update-*.sh work fine for cron and CI but require SPACEAPI_AUTH_KEY to be exported in the environment. The TUI keeps the same network behaviour while moving the API key out of any rc file and into the system keyring.

The original shell scripts remain in place and are unchanged — use them for headless / scripted invocations.

Requirements

Tool	Required?	Arch	Debian/Ubuntu	Fedora
gum	yes	gum	gum	gum
secret-tool	yes	libsecret	libsecret-tools	libsecret
curl	yes	curl	curl	curl
jq	optional	jq	jq	jq

A running keyring daemon is required for libsecret to function — typically gnome-keyring-daemon (GNOME, Sway+gnome-keyring) or kwalletd (KDE).

jq is used to pretty-print and colourise any JSON response body — both the full SpaceAPI document from Show status and the smaller replies from the update actions. Without it the raw response body is shown.

Install

./install-tui.sh

Symlinks spaceapi-tui into ~/.local/bin/spaceapi-tui. After a git pull the installed command is updated automatically. To pick a different install location:

INSTALL_DIR=/usr/local/bin ./install-tui.sh

First run

spaceapi-tui

Prompts for the SpaceAPI base URL and the API key, then stores them with:

secret-tool store --label="SpaceAPI base URL" service spaceapi kind base-url
secret-tool store --label="SpaceAPI auth key" service spaceapi kind auth-key

Both are read on every subsequent run via secret-tool lookup. Nothing is ever written to a plaintext file.

Menu

• Show status — GET the SpaceAPI base URL and display the document in a scrollable pager (press q to return to the menu). No authentication is sent — the SpaceAPI document is public. If jq is installed the output is colourised and pretty-printed; otherwise the raw body is shown.
• Update space state — choose open or closed, enter a message and trigger person, POST to /api/space/state.
• Update people count — enter a non-negative integer count and a location, POST to /api/space/people.
• Reconfigure credentials — overwrite the stored URL and key.
• Forget credentials — secret-tool clear both entries.
• Quit.

HTTP responses are colour-coded: green for 2xx, a red boxed banner for 401/403/429 and any other non-2xx code, with the response body printed underneath when present.

Rotate the API key

spaceapi-tui            # → Reconfigure credentials

Or directly:

secret-tool clear service spaceapi kind auth-key
secret-tool store  --label="SpaceAPI auth key" service spaceapi kind auth-key

Headless / scripted use

The TUI requires a TTY and a keyring daemon. For cron, CI, and SSH sessions without a session bus, keep using the original shell scripts:

SPACEAPI_URL=...  SPACEAPI_AUTH_KEY=...  ./scripts/update-space-status.sh open "..." "..."
SPACEAPI_URL=...  SPACEAPI_AUTH_KEY=...  ./scripts/update-people-count.sh 5 "Main Space"

Uninstall

rm ~/.local/bin/spaceapi-tui
secret-tool clear service spaceapi kind auth-key
secret-tool clear service spaceapi kind base-url