cli + tui to publish to leaflet (wip) & manage tasks, notes & watch/read lists 馃崈
desertthunder.dev
charm
leaflet
readability
golang
1---
2title: Terminal UI
3sidebar_label: Terminal UI
4description: Navigate Noteleaf鈥檚 Bubble Tea interfaces and their script-friendly counterparts.
5sidebar_position: 6
6---
7
8# Terminal UI
9
10Most list-style commands (tasks, notes, books) have two personalities: an interactive Bubble Tea view for exploration and a static text output for piping into other tools. This page explains how both modes behave.
11
12## Interactive Mode
13
14### Navigation
15
16- Launch the TUI with the default command (`noteleaf todo list`, `noteleaf note list`, `noteleaf media book add -i`, etc.).
17- Use `j`/`k` or the arrow keys to move the selection. Page Up/Down jump faster, while `g`/`G` (or Home/End) snap to the top or bottom depending on the view.
18- Search is always available鈥攑ress `/` and start typing to filter titles, tags, projects, or notes in real time.
19
20### Keyboard shortcuts
21
22All interactive components reuse the same key map defined in `internal/ui/data_list.go` and `internal/ui/data_table.go`:
23
24| Keys | Action |
25|------|--------|
26| `j` / `鈫揱 | Move down |
27| `k` / `鈫慲 | Move up |
28| `enter` | Select the highlighted row |
29| `v` | Open the detail preview (when supported) |
30| `/` | Start search |
31| `r` | Refresh data from the database |
32| `1-9` | Jump directly to a row index |
33| `q`, `ctrl+c` | Quit the view |
34
35The shortcuts appear in the on-screen help so you never have to memorize them all.
36
37### Selection and actions
38
39- Press `enter` to activate the primary action (open a note, view a task, confirm a media selection, etc.).
40- Some screens expose extra actions on letter keys (e.g., `a` to archive, `e` to edit). They are listed alongside the contextual help (`?`).
41- Interactive prompts such as `noteleaf media movie add` use the same selection model, so keyboard muscle memory carries over.
42
43### Help screens
44
45Hit `?` at any time to open the inline help overlay. It mirrors the bindings configured for the active component and also hints at hidden actions. Press `esc`, `backspace`, or `?` again to exit.
46
47## Static Mode
48
49### Command-line output
50
51Add `--static` (or remove `-i`) to force plain text output. Examples:
52
53```sh
54noteleaf todo list --static
55noteleaf note list --static --tag meeting
56noteleaf media book list --all --static
57```
58
59Static mode prints tables with headings so they are easy to read or parse. Commands that default to prompts (like `noteleaf media movie add`) fall back to a numbered list when you omit `-i`.
60
61### Scripting with Noteleaf
62
63Static output is predictable, making it straightforward to combine with familiar utilities:
64
65```sh
66noteleaf todo list --static --project docs | rg "pending"
67noteleaf note list --static | fzf
68```
69
70Because each row includes the record ID, you can feed the result back into follow-up commands (`noteleaf note view 42`, `noteleaf todo done 128`, etc.).
71
72### Output formatting
73
74The task viewer supports the `--format` flag for quick summaries:
75
76```sh
77noteleaf todo view 12 --format brief
78noteleaf todo view 12 --format detailed # default
79```
80
81Brief mode hides timestamps and auxiliary metadata, which keeps CI logs or chat snippets short. Future commands will inherit the same pattern.
82
83### JSON output
84
85Use `--json` wherever it exists (currently on task views/lists) for structured output:
86
87```sh
88noteleaf todo view 12 --json | jq '.status'
89noteleaf todo list --static --json | jq '.[] | select(.status=="pending")'
90```
91
92JSON mode ignores terminal colors and uses machine-friendly field names so you can script exports without touching the SQLite file directly.