TUI Guide

Launching the TUI

sd-todo tui
# or
sd-todo ui

Interface Layout

Three-Pane Layout (Folder Mode)

When using categories (folder mode), you get three panes:

+-- Categories --+-- Todos -------------------------+
| > Work    (5)  | > 1 [ ] Buy milk                 |
|   Personal(2)  |   2 [x] Call dentist              |
|   Shopping(0)  |   3 [ ] Review PR #123            |
+----------------+----------------------------------+
                 +-- Details ------------------------+
                 | ID: 1                             |
                 | Status: Pending                   |
                 | Description: Buy milk             |
                 +----------------------------------+

Two-Pane Layout (Single File Mode)

When using a single file, you get two panes:

+-- Todos -------------------------+
| > 1 [ ] Buy milk                 |
|   2 [x] Call dentist              |
|   3 [ ] Review PR #123            |
+----------------------------------+
+-- Details ------------------------+
| ID: 1                             |
| Status: Pending                   |
| Description: Buy milk             |
+----------------------------------+

Keyboard Shortcuts

KeyAction
Up or kMove up
Down or jMove down
TabSwitch between panes
EnterSelect category

Actions

KeyAction
aAdd new todo
eEdit selected todo
dDelete selected todo (or category in Categories pane)
SpaceToggle completion status
/Search todos
fCycle filter (All / Pending / Completed)
cClear all completed todos
+Add new category (when in Categories pane)
-Delete category (when in Categories pane)

Input Mode

When adding, editing, or searching:

KeyAction
EnterSubmit
EscCancel
BackspaceDelete character

Other

KeyAction
F1 or hToggle help overlay
qQuit TUI

Visual Indicators

  • Green border - Currently focused pane
  • Yellow highlight - Selected item
  • Gray text - Completed todos
  • > symbol - Current selection
  • [x] - Completed checkbox
  • [ ] - Pending checkbox

Details Pane

The details pane shows comprehensive information about the selected todo:

  • ID - The todo’s unique identifier
  • Status - Pending or Completed
  • Created - When the todo was created (with relative time)
  • Completed - When the todo was completed (if applicable)
  • Description - The full todo text

Filters

Press f to cycle through filters:

  • All - Show all todos
  • Pending - Show only incomplete todos
  • Completed - Show only completed todos

Tips

Quick Workflow

  1. Launch TUI: sd-todo tui
  2. Navigate with Up/Down or j/k
  3. Toggle completion with Space
  4. Add new todos with a
  5. Edit with e
  6. Delete with d
  7. Quit with q

Category Management

  1. Press Tab to focus Categories pane
  2. Navigate with Up/Down
  3. Press Enter to switch category
  4. Press + to add a new category
  5. Press - or d to delete selected category
  6. Press Tab again to return to Todos

Bulk Cleanup

  1. Press f to filter to “Completed”
  2. Review completed todos
  3. Press c to clear all completed
  4. Press f again to return to “All”

CLI vs TUI

Use CLI When

  • Quick one-off commands
  • Scripting/automation
  • Remote SSH (low bandwidth)
  • Adding single todo
  • Checking status quickly

Use TUI When

  • Managing many todos
  • Organizing/reviewing
  • Working with categories
  • Need visual overview
  • Long work sessions

Troubleshooting

TUI doesn’t launch

  • Make sure you’re using: sd-todo tui or sd-todo ui
  • Check terminal supports colors: echo $TERM
  • Try updating terminal emulator

Display issues

  • Resize terminal window
  • Check terminal size: tput cols and tput lines
  • Minimum recommended: 80x24

Keyboard shortcuts don’t work

  • Make sure terminal is in focus
  • Check for conflicting terminal shortcuts
  • Try different key combinations (arrows vs j/k)