ape-cli-terminal-experience

CLI Terminal Experience

A terminal UI that reads like Claude Code: mostly grey, a few deliberate accents, one line per fact, animation only while something is actually happening, and a plain-text fallback the moment the output stops being a terminal.

Every rule below is enforceable and testable. Follow them exactly rather than approximating the vibe.

---

1. The two laws

Subtle by default. Colour marks meaning -- a failure, a value the user will act on -- and nothing else. Labels, units, paths, and chrome are dim; values are plain. A full screen of output should read as mostly grey with a handful of accents, never as a colour test page. If you cannot say what a colour means, remove it.

Plain when not a terminal. Pipe the program anywhere and every escape sequence disappears, glyphs fall back to bracketed ASCII, rules vanish, and the spinner goes silent. Output stays greppable; a script parsing it never sees a byte of styling.

Three consequences that people get wrong:

• Colour detection and terminal detection are different questions. FORCE_COLOR should add colour to piped output, but carriage-return redraws still make no sense there. Gate colour on color_enabled(), gate animation on is_tty().
• Only colour is a colour question. Glyph shape, rules, and the spinner are terminal questions -- they gate on is_tty(). Conflating the two is the single most common bug in this module: NO_COLOR=1 in a real terminal then degrades ✓ to [OK], and FORCE_COLOR=1 | cat draws a horizontal rule into a pipe. --no-color on a terminal must keep ✓ and keep the rule, and just drop the escapes.
• --json output is data. Turn colour off for it globally, never decorate it.

---

2. One voice module

All user-facing output goes through a single presentation module (ui.py, ui.go, ui.ts -- one file). Logic modules never call print. They raise typed errors and return data; the CLI layer decides how it looks.

cli.py        argument parsing, flag wiring, orchestration, the exit-code map
ui.py         colours, glyphs, line shapes, listings, prompts, spinner, run()
everything    pure functions and typed exceptions -- zero output calls
else