CLI reference¶
Every calemdar subcommand, grouped by purpose. Run calemdar --help or
calemdar <command> --help for the built-in version.
Global flags¶
Vault resolution: --vault flag → $CALEMDAR_VAULT → vault: in config →
error.
Daemon¶
calemdar serve¶
Run the long-lived daemon: filesystem watcher plus nightly timers. Reacts
to changes in recurring/ and events/ live, and runs reconcile + archive
on the schedule defined by nightly_at.
Usually invoked from the systemd user unit — see examples/calemdar.service.
One-shot maintenance¶
These all do what the daemon does continuously, but once. Safe to run while
serve is also running; they share the same vault state.
calemdar setup¶
Create the calendar subfolders under the vault (or under base_path).
Idempotent. The daemon does this at startup too.
calemdar reindex¶
Rebuild the SQLite cache from disk. The cache is a projection, not a source
of truth — delete it and reindex will put it back exactly as it was.
calemdar reactor¶
One-shot scan of events/ for Full-Calendar-authored recurring events
(events that still carry FC's recurrence frontmatter). Each found event is
translated into a root under recurring/ and expanded into flat
occurrences.
You rarely need to run this by hand — the daemon runs it on startup and reacts to new FC recurring events live.
calemdar extend¶
Reconcile every recurring series, extending each to the configured horizon
(horizon_months, default 12). Runs nightly inside the daemon; useful to
invoke after a horizon bump.
calemdar expand <id-or-slug>¶
Reconcile a single series. Identify the series by either its UUIDv7 id
field or the current filename slug (without .md).
calemdar archive¶
Move events older than archive_cutoff_months (default 6) into archive/.
Filenames are preserved; directory structure mirrors events/ but rooted
at archive/.
Series management¶
calemdar series new¶
Interactive prompt-driven recurring root creation. Writes the new root to
recurring/<slug>.md and immediately expands it.
calemdar series list¶
Tabular listing of all recurring series.
Columns: slug, calendar, title, freq, interval, start date, until date.
calemdar series show <id-or-slug>¶
Detailed view of one series — every frontmatter field plus the file path.
calemdar recurring list¶
List every active recurring series. Same column shape as series list,
exposed under recurring for one-stop discovery alongside the safeguard
ops.
calemdar recurring delete [id-or-slug] [--purge-events] [-l]¶
Safe-delete a recurring root. Drops a backup copy under
<vault>/.calemdar/backup/recurring/<slug>-<RFC3339-utc>.md (laptop-local,
not synced), removes the root file with the self-delete flag set so the
watcher does NOT auto-restore, and clears the sqlite series row.
With --purge-events, also removes future non-user-owned expanded
events for this series. Past events stay (archive-bound). User-owned
events are always preserved — they stand on their own once the user has
edited them.
With -l (or --list), prints the deletable series and exits — same
output as recurring list. Slug-less invocation without -l errors
out with a usage hint.
calemdar recurring delete -l # show what's deletable
calemdar recurring delete workout
calemdar recurring delete workout --purge-events
calemdar recurring restore [slug] [-l]¶
Find the most recent backup matching <slug>-*.md under
<vault>/.calemdar/backup/recurring/ and copy it back to
recurring/<slug>.md. Refuses to overwrite an existing root — move it
out of the way first.
With -l (or --list), prints every backup grouped by slug, newest
first. This replaces the older backup-list subcommand.
The daemon (if running) will pick up the restored file via fsnotify and
reconcile. If you're running standalone, follow up with calemdar reindex.
calemdar series except <id-or-slug> <date>¶
Add a date to the series' exceptions list and reconcile. The occurrence
on that date is dropped (or swept if already materialised and not
user-owned).
Warns if <date> is in the past — past occurrences are immutable, so the
exception will have no effect on them.
One-off events¶
calemdar event new¶
Interactive prompt-driven one-off event creation. Writes directly under
events/<calendar>/<YYYY-MM-DD>-<slug>.md with no series-id — the
daemon will not touch it.
calemdar event list [--range=<range>]¶
List events in a date range.
calemdar event list --range=today
calemdar event list --range=week # default
calemdar event list --range=month
calemdar event list --range=all
calemdar event show <path>¶
Detailed view of one event. Path can be absolute or relative to the vault.
Notifications¶
Per-event rules live in event/root frontmatter (notify: — see
Schema). The daemon dispatches them through the backends
enabled in notifications.backends
and may also spawn local scripts via actions. These
subcommands help set up and verify the wiring.
calemdar notify test [backend]¶
Fire a test message through every enabled backend, or one named. Bypasses the schedule layer entirely — the point is to prove backend wiring before any rule actually fires.
calemdar notify test # every enabled backend
calemdar notify test ntfy # restrict to ntfy
calemdar notify test system # restrict to system (notify-send)
Errors if no matching backend is enabled or configured.
calemdar notify actions¶
List action entries registered in
~/.config/calemdar/actions.yaml (or the path set in
notifications.actions.config_path). Useful for confirming a name is
known before referencing it in a notify: rule.
Config¶
calemdar config path¶
Print the config file lookup path (does not check existence).
calemdar config show¶
Print the active config — defaults merged with the file on disk. If no file exists, prints defaults with a note at the top.
calemdar config init [--override]¶
Write a default config file. Errors if one already exists, unless
--override is passed. Drops into $EDITOR after writing if $EDITOR
is set.
calemdar config edit¶
Open the config in $EDITOR and validate on save. If the file does not
exist, a default stub is written first. Invalid YAML or out-of-range
values print diagnostics and leave the in-process config unchanged.