CLI 

Everything Kimün does, scriptable from your shell — quick captures, searches, workspace juggling, and note surgery. Pipe in, pipe out, put it in a cron job.

Global Configuration 

Pass a custom config file to any command:

kimun --config /path/to/config.toml <subcommand>

Without --config, Kimün uses the default location:

• Linux / macOS: ~/.config/kimun/config.toml
• Windows: %USERPROFILE%\kimun\config.toml

Initial Setup 

On first use, choose one of these approaches:

Option A — CLI First:

kimun workspace init --name default /path/to/notes

Option B — TUI First:

kimun

Then configure your workspace through the Preferences screen.

Legacy single-workspace configurations are automatically migrated to multi-workspace format.

Workspaces 

Multi-workspace support allows you to manage separate note directories.

For full workspace management reference, see the Workspaces page.

Quick reference:

kimun workspace init --name work /path/to/work/notes
kimun workspace list
kimun workspace use work
kimun workspace rename old-name new-name
kimun workspace remove work
kimun workspace reindex work

Search 

Search notes in the current workspace:

kimun search "your search query"
kimun search "meeting -cancelled"                # Exclude terms
kimun search "=project -@draft"                  # Combine filters
kimun search "#important"                        # Filter by hashtag label
kimun search "meeting #important -#draft"        # Mix labels with other filters
kimun search "rust" --format json                # JSON output

Flags 

• --format json — Output as JSON. Useful for scripting with jq.
• --format paths — Output bare paths only (one per line). Ideal for piping into kimun note show or fzf.
• --workspace <name> — Search a specific workspace (if applicable).

Query Syntax 

The same query language as the TUI. Quick reminder:

Want	Operator	Example
Free text	(just type)	meeting notes
By note name	= / name:	=tasks
By section	@ / in:	@personal
By path	/ / pt:	/journal
By label	# / lb:	#important
Backlinks	< / lk:	<projects
Forward links	> / fwd:	>projects
Exclude	- prefix	-#draft, -@temp

Space = AND, * = wildcard, case and accents ignored. The full grammar — wildcards per operator, link matching rules, query variables — lives on the Search page.

Examples 

# Find notes about "rust"
kimun search "rust"

# Find notes named "2024" but exclude "draft" in section titles
kimun search "=2024 -@draft"

# Find content under "Personal" section containing "kimun"
kimun search "@personal kimun"

# Find notes labelled #important but not #archived
kimun search "#important -#archived"

# Find notes that link to "projects" (its backlinks)
kimun search "<projects"

# Find notes that "projects" links to (its forward links)
kimun search ">projects"

# Combine with jq for advanced filtering
kimun search "rust" --format json | jq '.notes[] | select(.metadata.tags[] == "rust")'

Labels 

List every hashtag label in your vault with note counts:

kimun labels                  # alphabetical list: `name (N notes)`
kimun labels --format paths   # bare labels, one per line (pipeable)
kimun labels --format json    # JSON with total + per-label note_count

Labels come from in-text #hashtag tokens (see Search for full label rules — note that frontmatter / code / HTML / link bodies / wikilinks are excluded from indexing).

JSON schema 

{
  "workspace": "personal",
  "total": 12,
  "labels": [
    { "name": "idea",     "note_count": 5 },
    { "name": "reading",  "note_count": 4 },
    { "name": "systems",  "note_count": 5 }
  ]
}

Patterns 

# Top 10 most-used labels
kimun labels --format json | jq -r '.labels | sort_by(-.note_count) | .[:10][] | "\(.note_count)\t\(.name)"'

# Labels that appear in only one note (orphans worth reviewing)
kimun labels --format json | jq -r '.labels[] | select(.note_count == 1) | .name'

# Open every note carrying a given label in the TUI editor of your choice
kimun search "#systems" --format paths | xargs -r $EDITOR

# Build a per-label index file
kimun labels --format paths | while read l; do
  echo "## $l"
  kimun search "#$l" --format paths | sed 's/^/- /'
  echo
done > vault-by-label.md

# Cross-tabulate two labels (notes carrying BOTH)
kimun search "#api #perf" --format paths

# Notes labelled #idea but not yet #done
kimun search "#idea -#done" --format paths

Notes 

List all notes in the current workspace:

kimun notes
kimun notes --path "journal/"                    # Filter by path prefix
kimun notes --format json                        # JSON output

Flags 

• --path <prefix> — Filter notes by path prefix (e.g., journal/, projects/).
• --format json — Output as JSON. Useful for scripting with jq.
• --format paths — Output bare paths only (one per line). Ideal for piping into kimun note show or fzf.

Examples 

# List all notes
kimun notes

# List only journal entries
kimun notes --path "journal/"

# Get titles and paths as JSON
kimun notes --format json | jq '.notes[] | {title, path}'

# Count notes by workspace
kimun notes --format json | jq '.metadata | {workspace, total_results}'

Show 

Display note content and metadata in the terminal:

kimun note show "path/to/note"
kimun note show "path/to/note" "another/note"   # Multiple notes

Flags 

• --format json — Output as JSON (default: text).

Features 

• Accepts note paths relative to workspace root
• Paths work with or without .md extension
• Reads from stdin for batch processing
• Displays content, title, tags, links, and backlinks

Examples 

# Show a single note
kimun note show "inbox/meeting-notes"

# Show multiple notes
kimun note show "projects/foo" "inbox/bar"

# Read paths from stdin (one per line)
echo "journal/2024-01-01" | kimun note show

# Pipe paths from search results
kimun search "rust" --format paths | kimun note show

# Show as JSON
kimun note show "inbox/meeting" --format json

Note Operations 

Create 

Create a new note. Fails with an error if the note already exists.

kimun note create "path/to/note" "Initial content"
echo "My content" | kimun note create "path/to/note"

Features 

• Accepts content as a second argument or from stdin (when stdin is not a TTY)
• Paths are relative to the configured quick_note_path, or absolute from the vault root when prefixed with /
• Prints Note saved: <path> on success

Examples 

# Create a note with inline content
kimun note create "inbox/idea" "Use kimun for daily notes"

# Create a note at an absolute vault path
kimun note create "/projects/roadmap" "Q3 goals"

# Pipe content from a command
date | kimun note create "inbox/timestamp"

# Capture command output into a new note
curl -s https://example.com/api/status | kimun note create "inbox/status-check"

# Create from a here-string
kimun note create "inbox/snippet" <<'EOF'
## Snippet

Some important code or text to save.
EOF

Append 

Append text to an existing note. Creates the note if it does not exist.

kimun note append "path/to/note" "Appended text"
echo "New line" | kimun note append "path/to/note"

Features 

• Accepts content as a second argument or from stdin (when stdin is not a TTY)
• If the note does not exist, it is created automatically
• New content is joined with a newline after the existing content
• Prints Note saved: <path> on success

Examples 

# Append a quick thought to an existing note
kimun note append "inbox/ideas" "Another idea just came to me"

# Log the output of a command to a running log note
date >> /dev/null; echo "$(date): build succeeded" | kimun note append "logs/build-log"

# Accumulate cron job output
0 * * * * kimun note append "logs/hourly" "$(date): checked in"

# Append multiline content
kimun note append "inbox/research" <<'EOF'

## New finding

Something worth noting from today's reading.
EOF

# Use with search results: append a summary of found notes to a log
kimun search "rust" --format paths | kimun note append "inbox/rust-refs"

Overwrite 

Replace a note's entire body with new content. Because it discards the old body, it requires --force.

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

Features 

• Accepts content as a second argument or from stdin (when stdin is not a TTY)
• Requires --force; without it the command refuses to run (there is no interactive prompt — the CLI is built for automation)
• Backs up the previous content first (see Backups)

Replace 

Swap text for new text, leaving the rest of the note intact. The find text is a literal substring by default, or a regular expression with --regex.

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

Features 

• 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 place
• --all replaces every occurrence on purpose
• --regex treats the find text as a regular expression; the replacement may then reference capture groups ($1, ${name}; use $$ for a literal $, and ${1}/${name} when the next character is alphanumeric, e.g. ${1}_). Use inline flags for line/case behaviour — (?m), (?s), (?i). An invalid pattern errors without touching the note.
• --preview is a dry run: it prints the resulting note content to stdout (the match count goes to stderr) and writes nothing. Pipe it to compare, e.g. kimun note replace … --preview | diff <(kimun note show "…") -
• No --force needed — it is a targeted, scriptable edit
• Backs up the previous content first (see Backups)

Delete 

Remove a note. Requires --force.

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

Features 

• Requires --force; without it the command refuses to run
• Removes the note from the index as well as from disk
• Backs up the deleted content first (see Backups)

Backups 

Every CLI (and MCP) edit that overwrites or deletes a note's content copies the old content into a hidden, dated directory inside the vault before changing it. These backups are excluded from indexing and search, kept for 30 days, then purged automatically.

• Covers overwrite, replace, delete, and the backlink rewrites performed by rename/move. create and a first-time append have nothing to back up.
• Interactive TUI editing does not create backups (the editor has its own history).
• If a backup cannot be written, the operation is aborted and the note is left untouched (fail-closed).

Quick Note 

Capture a thought instantly. The note is saved in the inbox directory with a timestamp-based filename.

kimun note quick "My quick thought"
echo "Piped idea" | kimun note quick

Features 

• Saves to the configured inbox directory (default: /inbox)
• Filename is generated from the current UTC time (YYYY-MM-DDTHH-MM-SS.md)
• Handles timestamp collisions by appending -2, -3, etc.
• Accepts content as an argument or from stdin
• Empty content is silently ignored (no note created)

Examples 

# Capture a quick thought
kimun note quick "Look into async trait patterns"

# Pipe in command output
echo "$(date +%H:%M) — deploy completed" | kimun note quick

# Capture a snippet from clipboard (macOS)
pbpaste | kimun note quick

Inbox Triage 

List notes in the inbox for review:

kimun note triage

Prints each inbox note's path and title. Use this to see what has accumulated before organizing with the MCP triage prompt.

Journal 

Append to or show journal entries. Journal entries are stored as YYYY-MM-DD.md files in the vault's configured journal directory.

kimun journal "Today's entry"
kimun journal --date 2024-01-15 "Retroactive entry"
kimun journal show
kimun journal show --date 2024-01-15

Append 

Appends text to a journal entry. Creates the entry if it does not exist.

kimun journal [--date YYYY-MM-DD] [content]

Features 

• Defaults to today's date; use --date to target a specific entry
• Accepts content as an argument or from stdin (when stdin is not a TTY)
• New content is joined with a newline after any existing content
• Prints Note saved: <path> on success

Examples 

# Capture a quick thought
kimun journal "Had a good retro today"

# Pipe in a timestamped log line
echo "$(date +%H:%M) — finished the auth refactor" | kimun journal

# Record the result of a script
./run-tests.sh | tail -1 | kimun journal

# Append to a specific date's entry
kimun journal --date 2024-01-15 "Retroactive note"

# Append a longer entry with a here-string
kimun journal <<'EOF'

## Evening review

- Completed the CLI documentation
- Reviewed two PRs
- TODO: follow up with team on deploy schedule
EOF

# Use in a cron job to log system info daily
@daily kimun journal "$(hostname): $(uptime)"

# Chain with other commands — log search activity
kimun search "todo" --format paths | xargs -I{} echo "open: {}" | kimun journal

Show 

Displays a journal entry's content and metadata.

kimun journal show [--date YYYY-MM-DD] [--format text|json]

Flags 

• --date <YYYY-MM-DD> — Show a specific date's entry (defaults to today).
• --format json — Output as JSON. Useful for scripting with jq.

Examples 

# Show today's journal entry
kimun journal show

# Show a specific date
kimun journal show --date 2024-01-15

# Output as JSON for scripting
kimun journal show --format json | jq '.notes[0].metadata.headers'

# Get today's headings
kimun journal show --format json | jq '.notes[0].metadata.headers[].text'

JSON Output 

Both search and notes support JSON output for scripting and automation.

Output Structure 

{
  "metadata": {
    "workspace": "default",
    "workspace_path": "/home/user/notes",
    "total_results": 5,
    "query": "rust",
    "is_listing": false,
    "generated_at": "2024-03-27T10:30:00Z"
  },
  "notes": [
    {
      "path": "projects/rust-cli.md",
      "title": "Rust CLI Project",
      "content": "...",
      "size": 1024,
      "modified": 1711525800,
      "created": 1711525800,
      "hash": "abc123def",
      "journal_date": null,
      "metadata": {
        "tags": ["rust", "cli"],
        "links": ["projects/parser", "projects/lexer"],
        "headers": ["Overview", "Architecture", "TODO"]
      },
      "backlinks": ["blog/rust-post.md"]
    }
  ]
}

Processing with jq 

# Extract all tags from search results
kimun search "project" --format json | jq '.notes[].metadata.tags[]'

# Find notes modified in the last 7 days
kimun notes --format json | jq '.notes[] | select(.modified > now - 604800)'

# Get path and title only
kimun notes --format json | jq '.notes[] | {path, title}'

# Count total notes
kimun notes --format json | jq '.metadata.total_results'

For scripting guides, see Scripting.