nico2sh/kimun/kimun-cli

Kimün CLI Reference

Kimün is a local-first, terminal notes app. Notes are plain Markdown files indexed for fast search. Use the CLI to write, append, search, and read notes without opening the TUI — ideal for automation, piping, and AI-driven workflows.

Quick Reference

Writing Notes

All write commands accept content as a second argument or from stdin (when stdin is not a TTY).

Create

Creates a new note. Fails if the note already exists — use append if unsure.

kimun note create "inbox/idea" "My content"
echo "My content" | kimun note create "inbox/idea"

Append

Appends to a note. Creates it automatically if it doesn't exist. Safe to use as the default write command.

kimun note append "inbox/log" "New entry"
echo "Entry" | kimun note append "inbox/log"

Modifying Notes

Three destructive operations let you change or remove existing content. Each one backs up the note first (see below), so an edit is recoverable.

Overwrite

Replaces a note's entire body. Requires --force (it discards the old body). Content comes from an argument or stdin.

kimun note overwrite "projects/roadmap" "Brand new body" --force
echo "New body" | kimun note overwrite "projects/roadmap" --force

Replace

Swaps text for new text, leaving the rest of the note intact. The find text must match exactly once — the command errors if it is missing or appears more than once, so it never edits the wrong spot. Use --all to replace every occurrence. No --force needed (it's a targeted, scriptable edit).

By default the find text is a literal substring. Add --regex to treat it as a regular expression; the replacement may then use capture references ($1, ${name}; $$ for a literal $, and ${1}/${name} when the next character is alphanumeric, e.g. ${1}_). Inline flags (?m), (?s), (?i) control line/case behaviour. An invalid pattern errors without touching the note.

--preview is a dry run: it prints the resulting note content to stdout (match count to stderr) and writes nothing — useful to inspect before committing.

kimun note replace "projects/roadmap" "Q2" "Q3"
kimun note replace "projects/roadmap" "TODO" "DONE" --all
kimun note replace "notes/log" "v\d+\.\d+" "v2.0" --regex
kimun note replace "notes/log" "(\w+)@(\w+)" "$2.$1" --regex --all
kimun note replace "projects/roadmap" "TODO" "DONE" --all --preview

Delete

Removes a note. Requires --force.

kimun note delete "inbox/stale-idea" --force

Properties

Read and edit frontmatter properties without touching the rest of the note.

kimun note prop list "projects/garden" --format json
kimun note prop get "projects/garden" status
kimun note prop set "projects/garden" status active
kimun note prop set "projects/garden" tags garden spring    # several values → list
kimun note prop set "projects/garden" priority high --type text
kimun note prop remove "projects/garden" status

tags is always a list (comma-separated values become separate items; set n tags with no value clears it). Any other key's value must be exactly a value of the type the key has in other notes; one that doesn't fit (e.g. high, or 02134, where priority is a number elsewhere) is refused with a user error — retry with --type text|number|bool|date|datetime|list, which changes only that note. A key no other note has is typed by its look (5 → number, true → bool, 2026-05-01 → date, 2026-05-01T14:30 → date-time kept local, else text; 02134 stays text). Query properties with kimun search "%status=active" (see the search syntax).

Automatic backups

Every CLI/MCP edit that overwrites or deletes a note's content first copies the old content into a hidden, dated backup inside the vault (excluded from search). Backups are kept for 30 days, then purged automatically. This covers overwrite, replace, delete, prop set/prop remove, and the backlink rewrites done by rename/move. create and append of a new note have nothing to back up. Interactive TUI editing does not back up (the editor has its own history). If a backup can't be written, the edit is aborted (fail-closed) — the note is left untouched.

Errors

Failed operations print a one-line message to stderr and exit non-zero:

• Exit 2 — user/input error you can act on. The message is clean and stable,

e.g. Error: Note not found: inbox/x.md, Error: Note already exists: inbox/x.md, Error: Text to replace is not unique in note: …, Error: Text to replace not found in note: …, Error: Invalid path '…': …. Read it and adjust (fix the path, use --all, etc.) — don't retry unchanged.

• Exit 1 — internal failure (database, filesystem, unexpected). Treat as a

real fault, not something to retry blindly; the full report goes to stderr.

The MCP server returns the same wording as a tool error, so both surfaces report note problems identically.

Journal

kimun journal appends to a journal entry (today by default). kimun journal show displays one.

kimun journal "Captured this finding"             # append to today
kimun journal --date 2024-01-15 "Backdated note"  # append to specific date
echo "$(date +%H:%M) — task complete" | kimun journal
 
kimun journal show                                # show today's entry
kimun journal show --date 2024-01-15             # show specific date
kimun journal show --format json                 # JSON output

• Defaults to today; --date YYYY-MM-DD targets any date
• Creates the entry if it doesn't exist
• show supports --format text (default) and --format json

Reindexing After External Edits

Kimün serves search, listing, labels, backlinks, and forward links from an index, not by reading every file on each query. Every write through the CLI (or MCP, or the TUI) updates that index automatically. But if a note file is changed outside Kimün — edited with sed, vim, another editor, a sync tool, or any direct filesystem write — the index goes stale: search and metadata keep reflecting the old content until you rebuild it.

After any out-of-band change to vault files, reindex:

kimun workspace reindex            # current workspace
kimun workspace reindex myvault    # a named workspace

# Typical pattern: bulk-edit on disk, then reindex
sed -i 's/old-tag/new-tag/g' "$VAULT"/**/*.md
kimun workspace reindex

Until you reindex, results from search, notes, labels, and link filters may be wrong. Stick to the note write commands above and you never need this — they keep the index in sync for you.

Path Rules

• "inbox/note" — relative to the configured quick_note_path (default: vault root)
• "/inbox/note" — absolute from vault root; use a leading / to be explicit
• .md extension is optional in all commands

Searching

kimun search "query"               # Full-text search
kimun search "query" --format json # JSON output
kimun search "query" --format paths # Bare paths, one per line (pipeable)

Query syntax

Free text is case-insensitive, diacritics-ignored. Multiple terms = AND.

Wildcards — * matches any sequence of characters, works in free text and with operators:

kimu*          # starts with "kimu"
*report        # ends with "report"
*meeting*      # contains "meeting" anywhere
=task*         # note name starts with "task"
=*2024*        # note name contains "2024"

Hashtag labels — any #name token in a note body (letters/digits/underscore) is indexed as a label and is case-insensitive. Hashtags inside frontmatter, code spans, fenced blocks, HTML, link bodies, and wikilinks are NOT indexed. Multiple # filters AND together.

Link filters — <note (or lk:note) matches notes that link to note (its backlinks); >note (or fwd:note) matches the notes that note links to (its forward links). Both match by note name (.md optional, case-insensitive); a bare name matches in any folder, <dir/note / >dir/note disambiguates, and * wildcards work (<proj*). Only links to other notes count, not attachments or URLs.

Exclusion composes with all operators — `-` leads, then the operator:

-cancelled           # exclude notes containing "cancelled"
-=temp               # exclude notes with "temp" in the name
-@draft              # exclude notes with "draft" in any section title
-/private            # exclude notes under a "private/" path
-#archived           # exclude notes carrying #archived label
-<draft              # exclude notes that link to "draft"
->draft              # exclude notes that "draft" links to

Combining filters (all terms are ANDed):

meeting -cancelled           # "meeting" but not "cancelled"
=tasks @work report          # name "tasks", has "Work" section, contains "report"
=2024 -@draft                # names from 2024, no "draft" section title
/journal @tasks -done        # in journal/, "tasks" section, excluding "done"
@personal kimun              # "kimun" under a "Personal" section
<spec #urgent                # links to "spec" and labelled "urgent"
<kimun -<draft               # links to "kimun" but not to "draft"
>kimun #urgent               # "kimun" links to these, and labelled "urgent"
#important -#archived        # notes carrying #important but not #archived
meeting #important           # "meeting" in notes also carrying #important

Listing Labels

kimun labels enumerates every distinct hashtag label in the vault with note counts. Three formats:

kimun labels                  # text: `name (N notes)` per line, alphabetical
kimun labels --format paths   # bare label names, one per line (pipeable)
kimun labels --format json    # JSON: { workspace, total, labels: [{name, note_count}] }

When to reach for it