cli + tui to publish to leaflet (wip) & manage tasks, notes & watch/read lists 🍃
desertthunder.dev
charm
leaflet
readability
golang
1---
2title: CLI Reference
3sidebar_label: CLI Reference
4description: Overview of Noteleaf’s command hierarchy, flags, and developer utilities.
5sidebar_position: 7
6---
7
8# CLI Reference
9
10This 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.
11
12## Command Structure
13
14### Global flags
15
16| Flag | Description |
17| ------------------------- | ----------------------------------------------------------------- |
18| `--help`, `-h` | Show help for any command or subcommand |
19| `--version` | Print the Noteleaf build string (includes git SHA when available) |
20| `--color <auto\|on\|off>` | Optional Fang flag to control ANSI colors |
21
22Environment variables such as `NOTELEAF_CONFIG`, `NOTELEAF_DATA_DIR`, and `EDITOR` affect how commands behave but are not flags.
23
24### Command hierarchy
25
26- Root command: `noteleaf`
27- Task commands live under the `todo` alias (e.g., `noteleaf todo add`).
28- Media commands are grouped and require a subtype: `noteleaf media book`, `noteleaf media movie`, `noteleaf media tv`.
29- Publishing flows live under `noteleaf pub`.
30- Management helpers (`config`, `setup`, `status`, `reset`) sit at the top level.
31
32### Help system
33
34Every command inherits Fang’s colorized help plus Noteleaf-specific additions:
35
36- `noteleaf article --help` prints the supported parser domains and storage directory by calling into the handler.
37- Interactive commands show the keyboard shortcuts inside their help output.
38- You can always drill down: `noteleaf todo add --help`, `noteleaf media book list --help`, etc.
39
40## Commands by Category
41
42### `todo` / `task`
43
44Add, 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.
45
46### `note`
47
48Create 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.
49
50### `media`
51
52Umbrella group for personal queues:
53
54- `noteleaf media book` — Search Open Library, add books, update status (`queued`/`reading`/`finished`), edit progress percentages, and remove titles.
55- `noteleaf media movie` — Search Rotten Tomatoes, queue movies, mark them watched, or remove them.
56- `noteleaf media tv` — Same as movies but with watching/watched states and optional season/episode tracking.
57
58Each 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).
59
60### `article`
61
62Parse 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.
63
64### `pub`
65
66Leaflet.pub commands for AT Protocol publishing:
67
68- `pull` / `push` to sync notes with the remote publication.
69- `status`, `list`, and `diff` to inspect what is linked.
70- Support for working drafts, batch pushes, and file-based imports (`--file`) when publishing is combined with local markdown.
71
72### `config`
73
74Inspect and mutate `~/.noteleaf.conf.toml`:
75
76- `noteleaf config show` (or `get <key>`) prints values.
77- `noteleaf config set <key> <value>` writes back to disk.
78- `noteleaf config path` reveals the file location.
79- `noteleaf config reset` rewinds to defaults.
80
81### `setup`
82
83`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).
84
85### `status`
86
87`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.
88
89## Development Tools
90
91`noteleaf tools ...` is available in development builds (`task build:dev`, `go run ./cmd`). It bundles maintenance utilities:
92
93### Documentation generation
94
95```
96noteleaf tools docgen --format docusaurus --out website/docs/manual
97noteleaf tools docgen --format man --out docs/manual
98```
99
100Generates reference docs straight from the command definitions, keeping terminal help and published docs in sync.
101
102### Lexicon fetching
103
104```
105noteleaf tools fetch lexicons
106noteleaf tools fetch lexicons --sha <commit>
107```
108
109Pulls 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.
110
111### Database utilities
112
113```
114noteleaf tools fetch gh-repo --repo owner/repo --path schemas --output tmp/schemas
115```
116
117Provides generic fetchers plus helpers used by CI and local testing to refresh schema files, warm caches, or introspect the SQLite database.
118
119These tools intentionally live behind the dev build tag so production binaries stay lean. Use them when contributing documentation or publishing features.