CLI 

Kimün provides a powerful command-line interface for quick operations, multi-workspace management, and scripting. All CLI commands support both the TUI and background use.

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 Settings 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 

Searches support free text, filters, and operators:

• Free text: Case-insensitive, diacritics ignored, * wildcard supported
• Filter by filename: @tasks or at:tasks
• Filter by section: <personal or in:personal (Markdown headers)
• Filter by label (hashtag): #important or lb:important — matches notes carrying that #tag in their body
• Exclusion: - prefix leads, then the operator follows
  • Content: meeting -cancelled
  • Title: -<draft or -in:draft
  • Filename: -@temp or -at:temp
  • Label: -#draft or -lb:draft

For comprehensive search documentation, see the Search page.

Examples 

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

# Find in files matching "2024" but exclude "draft" in title
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"

# 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"

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.