title: CLI Reference sidebar_label: CLI Reference description: Overview of Noteleaf’s command hierarchy, flags, and developer utilities. sidebar_position: 7#

CLI Reference#

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.

Command Structure#

Global flags#

Environment variables such as NOTELEAF_CONFIG, NOTELEAF_DATA_DIR, and EDITOR affect how commands behave but are not flags.

Command hierarchy#

• Root command: noteleaf
• Task commands live under the todo alias (e.g., noteleaf todo add).
• Media commands are grouped and require a subtype: noteleaf media book, noteleaf media movie, noteleaf media tv.
• Publishing flows live under noteleaf pub.
• Management helpers (config, setup, status, reset) sit at the top level.

Help system#

Every command inherits Fang’s colorized help plus Noteleaf-specific additions:

• noteleaf article --help prints the supported parser domains and storage directory by calling into the handler.
• Interactive commands show the keyboard shortcuts inside their help output.
• You can always drill down: noteleaf todo add --help, noteleaf media book list --help, etc.

Commands by Category#

todo / task#

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.

note#

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.

media#

Umbrella group for personal queues:

• noteleaf media book — Search Open Library, add books, update status (queued/reading/finished), edit progress percentages, and remove titles.
• noteleaf media movie — Search Rotten Tomatoes, queue movies, mark them watched, or remove them.
• noteleaf media tv — Same as movies but with watching/watched states and optional season/episode tracking.

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).

article#

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.

pub#

Leaflet.pub commands for AT Protocol publishing:

• pull / push to sync notes with the remote publication.
• status, list, and diff to inspect what is linked.
• Support for working drafts, batch pushes, and file-based imports (--file) when publishing is combined with local markdown.

config#

Inspect and mutate ~/.noteleaf.conf.toml:

• noteleaf config show (or get <key>) prints values.
• noteleaf config set <key> <value> writes back to disk.
• noteleaf config path reveals the file location.
• noteleaf config reset rewinds to defaults.

setup#

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).

status#

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.

Development Tools#

noteleaf tools ... is available in development builds (task build:dev, go run ./cmd). It bundles maintenance utilities:

Documentation generation#

noteleaf tools docgen --format docusaurus --out website/docs/manual
noteleaf tools docgen --format man --out docs/manual

Generates reference docs straight from the command definitions, keeping terminal help and published docs in sync.

Lexicon fetching#

noteleaf tools fetch lexicons
noteleaf tools fetch lexicons --sha <commit>

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.

Database utilities#

noteleaf tools fetch gh-repo --repo owner/repo --path schemas --output tmp/schemas

Provides generic fetchers plus helpers used by CI and local testing to refresh schema files, warm caches, or introspect the SQLite database.

These tools intentionally live behind the dev build tag so production binaries stay lean. Use them when contributing documentation or publishing features.