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/kimun_config.toml
• Windows: %USERPROFILE%\kimun\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 "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)
• Exclusion: -term to exclude from results
  • Content: meeting -cancelled
  • Title: >-draft or in:-draft
  • Filename: @-temp or at:-temp

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"

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

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"

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.