TUI
An interactive terminal interface for reviewing and actioning pending approvals without leaving your terminal.
Launching
The TUI opens in your terminal and polls the local ledger every 3 seconds. Pending decisions appear as soon as they are recorded — no manual refresh needed.
Pass --ledger to point at a non-default ledger file, or set it in shotoku.config.json.
Layout
The TUI has three areas:
- Header — current time and pending count
- Main panel — list of pending decisions, one per row
- Footer — keyboard hint bar
Each pending row shows the actor, resource, amount (if any), age, and a one-line reason summary.
Keyboard shortcuts
| Key | Action |
|---|---|
| ↑ / ↓ | Navigate between pending decisions |
| Enter | Approve the selected decision |
| d | Deny the selected decision |
| e | Expand the selected decision — shows all reasons and full request detail |
| h | Toggle decision history panel |
| q | Quit the TUI |
After approving or denying, the TUI updates immediately — the actioned decision moves out of the pending list and into history.
Empty state
When there are no pending decisions, the TUI shows a quiet empty state. It keeps polling — as soon as an agent records a pending decision, it appears automatically.
When to use the TUI vs the CLI
Use shotoku status for a quick one-shot check. Use the TUI when you want a live view while an agent is running — it stays open and refreshes automatically so you can approve or deny decisions as they come in without switching back and forth between commands.