···11+---
22+title: CLI Reference
33+sidebar_label: CLI Reference
44+description: Overview of Noteleaf’s command hierarchy, flags, and developer utilities.
55+sidebar_position: 7
66+---
77+88+# CLI Reference
99+1010+This reference is a map of the top-level commands exposed by `noteleaf`. For flag-by-flag detail run `noteleaf <command> --help`—the human-friendly Fang help screens are always the source of truth.
1111+1212+## Command Structure
1313+1414+### Global flags
1515+1616+| Flag | Description |
1717+| ------------------------- | ----------------------------------------------------------------- |
1818+| `--help`, `-h` | Show help for any command or subcommand |
1919+| `--version` | Print the Noteleaf build string (includes git SHA when available) |
2020+| `--color <auto\|on\|off>` | Optional Fang flag to control ANSI colors |
2121+2222+Environment variables such as `NOTELEAF_CONFIG`, `NOTELEAF_DATA_DIR`, and `EDITOR` affect how commands behave but are not flags.
2323+2424+### Command hierarchy
2525+2626+- Root command: `noteleaf`
2727+- Task commands live under the `todo` alias (e.g., `noteleaf todo add`).
2828+- Media commands are grouped and require a subtype: `noteleaf media book`, `noteleaf media movie`, `noteleaf media tv`.
2929+- Publishing flows live under `noteleaf pub`.
3030+- Management helpers (`config`, `setup`, `status`, `reset`) sit at the top level.
3131+3232+### Help system
3333+3434+Every command inherits Fang’s colorized help plus Noteleaf-specific additions:
3535+3636+- `noteleaf article --help` prints the supported parser domains and storage directory by calling into the handler.
3737+- Interactive commands show the keyboard shortcuts inside their help output.
3838+- You can always drill down: `noteleaf todo add --help`, `noteleaf media book list --help`, etc.
3939+4040+## Commands by Category
4141+4242+### `todo` / `task`
4343+4444+Add, list, view, update, complete, and annotate tasks. Supports priorities, contexts, tags, dependencies, recurrence, and JSON output for scripting. Related metadata commands (`projects`, `tags`, `contexts`) summarize usage counts.
4545+4646+### `note`
4747+4848+Create Markdown notes (inline, from files, or via the interactive editor), list them with the TUI, search, view, edit in `$EDITOR`, archive/unarchive, and delete. Notes share IDs with leaflet publishing so they can be synced later.
4949+5050+### `media`
5151+5252+Umbrella group for personal queues:
5353+5454+- `noteleaf media book` — Search Open Library, add books, update status (`queued`/`reading`/`finished`), edit progress percentages, and remove titles.
5555+- `noteleaf media movie` — Search Rotten Tomatoes, queue movies, mark them watched, or remove them.
5656+- `noteleaf media tv` — Same as movies but with watching/watched states and optional season/episode tracking.
5757+5858+Each subtype has its own `list`, status-changing verbs, and removal commands. Use `-i/--interactive` on `add` to open the TUI selector (books today, other media soon).
5959+6060+### `article`
6161+6262+Parse and save web articles with `add <url>`, inspect them via `list`, `view`, or `read`, and delete them with `remove`. All commands operate on the local Markdown/HTML archive referenced in the handler output.
6363+6464+### `pub`
6565+6666+Leaflet.pub commands for AT Protocol publishing:
6767+6868+- `pull` / `push` to sync notes with the remote publication.
6969+- `status`, `list`, and `diff` to inspect what is linked.
7070+- Support for working drafts, batch pushes, and file-based imports (`--file`) when publishing is combined with local markdown.
7171+7272+### `config`
7373+7474+Inspect and mutate `~/.noteleaf.conf.toml`:
7575+7676+- `noteleaf config show` (or `get <key>`) prints values.
7777+- `noteleaf config set <key> <value>` writes back to disk.
7878+- `noteleaf config path` reveals the file location.
7979+- `noteleaf config reset` rewinds to defaults.
8080+8181+### `setup`
8282+8383+`noteleaf setup` initializes the database, config file, and data directories if they do not exist. `noteleaf setup seed` can load sample data (pass `--force` to wipe existing rows first).
8484+8585+### `status`
8686+8787+`noteleaf status` prints absolute paths for the config file, data directory, database, and media folders along with environment overrides—handy for debugging or verifying a portable install.
8888+8989+## Development Tools
9090+9191+`noteleaf tools ...` is available in development builds (`task build:dev`, `go run ./cmd`). It bundles maintenance utilities:
9292+9393+### Documentation generation
9494+9595+```
9696+noteleaf tools docgen --format docusaurus --out website/docs/manual
9797+noteleaf tools docgen --format man --out docs/manual
9898+```
9999+100100+Generates reference docs straight from the command definitions, keeping terminal help and published docs in sync.
101101+102102+### Lexicon fetching
103103+104104+```
105105+noteleaf tools fetch lexicons
106106+noteleaf tools fetch lexicons --sha <commit>
107107+```
108108+109109+Pulls the latest `leaflet.pub` lexicons from GitHub so the AT Protocol client stays current. You can point it at a specific commit for reproducible builds.
110110+111111+### Database utilities
112112+113113+```
114114+noteleaf tools fetch gh-repo --repo owner/repo --path schemas --output tmp/schemas
115115+```
116116+117117+Provides generic fetchers plus helpers used by CI and local testing to refresh schema files, warm caches, or introspect the SQLite database.
118118+119119+These tools intentionally live behind the dev build tag so production binaries stay lean. Use them when contributing documentation or publishing features.
···11+---
22+title: Terminal UI
33+sidebar_label: Terminal UI
44+description: Navigate Noteleaf’s Bubble Tea interfaces and their script-friendly counterparts.
55+sidebar_position: 6
66+---
77+88+# Terminal UI
99+1010+Most 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.
1111+1212+## Interactive Mode
1313+1414+### Navigation
1515+1616+- Launch the TUI with the default command (`noteleaf todo list`, `noteleaf note list`, `noteleaf media book add -i`, etc.).
1717+- 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.
1818+- Search is always available—press `/` and start typing to filter titles, tags, projects, or notes in real time.
1919+2020+### Keyboard shortcuts
2121+2222+All interactive components reuse the same key map defined in `internal/ui/data_list.go` and `internal/ui/data_table.go`:
2323+2424+| Keys | Action |
2525+|------|--------|
2626+| `j` / `↓` | Move down |
2727+| `k` / `↑` | Move up |
2828+| `enter` | Select the highlighted row |
2929+| `v` | Open the detail preview (when supported) |
3030+| `/` | Start search |
3131+| `r` | Refresh data from the database |
3232+| `1-9` | Jump directly to a row index |
3333+| `q`, `ctrl+c` | Quit the view |
3434+3535+The shortcuts appear in the on-screen help so you never have to memorize them all.
3636+3737+### Selection and actions
3838+3939+- Press `enter` to activate the primary action (open a note, view a task, confirm a media selection, etc.).
4040+- Some screens expose extra actions on letter keys (e.g., `a` to archive, `e` to edit). They are listed alongside the contextual help (`?`).
4141+- Interactive prompts such as `noteleaf media movie add` use the same selection model, so keyboard muscle memory carries over.
4242+4343+### Help screens
4444+4545+Hit `?` 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.
4646+4747+## Static Mode
4848+4949+### Command-line output
5050+5151+Add `--static` (or remove `-i`) to force plain text output. Examples:
5252+5353+```sh
5454+noteleaf todo list --static
5555+noteleaf note list --static --tag meeting
5656+noteleaf media book list --all --static
5757+```
5858+5959+Static 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`.
6060+6161+### Scripting with Noteleaf
6262+6363+Static output is predictable, making it straightforward to combine with familiar utilities:
6464+6565+```sh
6666+noteleaf todo list --static --project docs | rg "pending"
6767+noteleaf note list --static | fzf
6868+```
6969+7070+Because 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.).
7171+7272+### Output formatting
7373+7474+The task viewer supports the `--format` flag for quick summaries:
7575+7676+```sh
7777+noteleaf todo view 12 --format brief
7878+noteleaf todo view 12 --format detailed # default
7979+```
8080+8181+Brief mode hides timestamps and auxiliary metadata, which keeps CI logs or chat snippets short. Future commands will inherit the same pattern.
8282+8383+### JSON output
8484+8585+Use `--json` wherever it exists (currently on task views/lists) for structured output:
8686+8787+```sh
8888+noteleaf todo view 12 --json | jq '.status'
8989+noteleaf todo list --static --json | jq '.[] | select(.status=="pending")'
9090+```
9191+9292+JSON mode ignores terminal colors and uses machine-friendly field names so you can script exports without touching the SQLite file directly.