reference
Reference
Commands, configuration, crates and validation for kittui 0.1.7. Command output on this site comes from that release.
kittui commands
kittui --helpkitty graphics for TUIsUsage: kittui [OPTIONS] <COMMAND>Commands: build-info Print exact binary provenance, app schema and runtime capabilities app Build, validate, inspect, run and test declarative kittui applications inline Render inline one-line components for prompts/statuslines box Render a box (filled, stroked, rounded) at the given footprint gradient Render a linear gradient strip glow Render a glow layer panel Render a tonal panel chrome scene chip Render a pill-shaped chip chrome scene divider Render a single-row divider chrome scene wm-chrome Render the reusable kittwm window chrome scene wm-session Render a kittwm SESSION_JSON manifest as window chrome scenes title-bar Render a title-bar chrome scene compose Compose a scene from a JSON file render Render a scene JSON file to PNG bytes without terminal placement image Render an image from a path/bytes through Node::Image place Re-place an already-uploaded image id at a terminal footprint delete Delete an uploaded image or one placement from the terminal cache Cache management subcommands probe Probe terminal capabilities proof Walk the full kitty graphics protocol surface and emit labelled output update Download and install a released kittui binary mcp Expose shared kittui tools over MCP stdio| Global option | Effect |
|---|---|
--renderer cpu|gpu|auto | Choose the renderer |
--transport direct|tmux|file|memory | Override transport detection |
--json, --json-bytes | Describe the placement as JSON, optionally with the upload, placement and placeholder strings |
--upload-only, --placement-only, --embed-only | Print just one part of the output |
--scene-json | Print the scene instead of rendering it |
--dry-run | Build everything but write no bytes |
--terminal-cols, --terminal-rows | Terminal size, for percentage footprints such as -w 100% |
--cache-dir | Cache location |
kittwm commands
kittwm help topic covers each area, and kittwm quickstart, examples and cheat are the daily guides:
kittwm helpstart launch modes, startup environment, and first terminal panes pane lifecycle, focus, layout, movement, and sessions input text, key, mouse, bytes, paste, and semantic actions inspect status, panes, chrome, shortcuts, help, and text reads session save/restore session manifestsevents bounded event streams and typed SDK event helpersapps app discovery and launch helpersssh pooled SSH workflows for remote apps, displays, and terminals log debug log path and tailing workflowscompletions shell completion setup| Helper | For |
|---|---|
kittwm-launch | Start kittwm with a browser or other first pane |
kittwm-terminal | Terminal panes and text event streams, locally or remotely |
kittwm-browser | Headless browser surfaces and semantic snapshots |
kittwm-top | A process viewer for kittwm, built on the SDK, or --json |
kittwm-bar | A status bar that reserves its row |
kittwm-demo | The mixed-source demo, with --plan to preview what this machine can run |
The full socket command set is generated from the in-tree help catalogues, with tests that fail if a command is undocumented.
Environment
Every kittui flag can also come from the environment as KITTUI_COMMAND_FLAG, such as KITTUI_BOX_RADIUS; --json reports where each setting came from. The settings most worth knowing:
| Variable | Default | Controls |
|---|---|---|
KITTUI_RENDERER | auto | CPU or GPU rendering |
KITTUI_TRANSPORT | detected | How graphics reach the terminal |
KITTUI_KITTY_COMPRESSION | zlib | Frame compression: zlib, auto or none |
KITTUI_ZLIB_MIN_BYTES | 16384 | The auto threshold |
KITTUI_CACHE_DIR | XDG cache | Where rendered scenes live |
KITTUI_CACHE_BUDGET | 256 MiB | Disk cache size |
KITTUI_CACHE_HOT_MAX_ENTRIES, _BYTES | 64, 16 MiB | The in-memory hot cache |
KITTWM_NATIVE_RENDERER | ANSI | kitty draws panes with graphics |
KITTWM_NATIVE_CHROME_RENDERER | built-in | affordance-scene draws chrome with kittui scenes |
KITTWM_WORKSPACE | unset | The workspace label |
KITTWM_STARTUP_TERMINAL | off | Open a terminal immediately |
The repository's configuration references list all 41 KITTUI_ and 63 KITTWM_ entries.
Install and build
nix profile install .#kittwm # kittwm with every helper and the right native backendsnix run .#kittui-showcase # the SDK studionix run .#kittwm-demo -- --plan # what the demo would run herecargo run -p kittui-cli -- box -w 60 -h 8kittui update # download and install a released kittui binaryThe flake builds platform-native backends by default: ScreenCaptureKit and Quartz on macOS, Xvfb on Linux. The repository also ships kittui-md, a Markdown viewer.
Crates
| Layer | Crates |
|---|---|
| Renderer | kittui-core (scenes, geometry, colour, hashing, animation), kittui-render-cpu, kittui-render-gpu, kittui-kitty (the only crate that writes escapes), kittui-cache, kittui (the public facade) |
| Hosts | kittui-cli, kittui-ffi, kittui-sdk, ratakittui, kittui-app, kittui-affordances, kittui-tmux, kittui-overlay, kittui-watch, kittui-input, kittui-vt, kittui-ghostty-vt |
| Window manager | kittui-wm, kittui-wm-layout, kittwm-sdk, kittui-surface, kittui-window-host, kittui-quartz, kittui-xvfb |
| Browser | kittui-web (the WebAssembly shell), kittui-transport (the host and browser wire protocol) |
Validation
Changes prove themselves before they merge:
nix run .#agent-check- One fast-failing preflight: formatting,
cargo check, strict Clippy against a baseline, the focused SDK tests, a self-test of the evidence gate, and the visual golden harnesses. Each step printsPASSorFAIL. - Golden harnesses
- Render, chrome and scene changes are compared pixel for pixel with checked-in images;
KITTUI_REFRESH_GOLDENSregenerates them deliberately. - Evidence gate
- Work is closed only with evidence that shows the feature working; an artifact that merely shows a command ran, or shows the feature broken, does not count. The gate itself is tested against good and bad fixtures.
- Contract locks
- Tests whose only job is to pin a behavioural contract that nothing tested before, so a later change to it has to be deliberate.
- Performance self-validation
- A fixed micro-workload runs in preflight and is compared with recorded budgets, so hot-path regressions are caught deterministically rather than by feel.
The kittui proof command walks the whole kitty graphics protocol surface and labels each output, for checking a terminal by eye.