kcli

Personal CLI utilities — Obsidian vault manager, built-in text editor, and more.

Features

• Obsidian Vault Manager — Create notes from templates with field validation, smart folder routing, and git integration
• Built-in Text Editor — nano-style terminal editor with selection, copy/paste, and line numbers. Works on Windows, Mac, and Linux with no external tools
• Catppuccin-themed UI — Polished interface with colors, spinners, and previews throughout

Installation

npm install -g kcli

Quick Start

# Configure your Obsidian vault
kcli init /path/to/your/vault

# Create a new note interactively
kcli new

# Create a file with the built-in editor
kcli newfile notes.md --editor

# List all notes in your vault
kcli list

Commands

| Command | Alias | Description | |---------|-------|-------------| | kcli init [path] | — | Configure the Obsidian vault path | | kcli config | — | Show current configuration | | kcli new [template] | kcli n | Create a new vault note from a template | | kcli newfile <path> [content] | kcli nf | Create a file (inline content or editor) | | kcli list | kcli ls | Show vault overview by type and status | | kcli templates | kcli t | List available templates and their fields |

Vault Manager

Templates

Six built-in templates, each with typed fields, validation, and automatic folder placement:

| Template | Tags | Required Fields | Status Routing | |----------|------|-----------------|----------------| | Game | games | status, platform, rating, progress, started_date | Playing / Backlog / Completed | | Movie | media | status, platform, genre, year, rating | To Watch / Watching / Watched | | Series | media | status, platform, total_seasons, current_season, started_date | To Watch / Watching / Watched | | Dance | dance | status, artist, song, scope, difficulty | Learning / Recorded / Taught | | Dev Project | project | status, priority, stack, repo_link, started_date | Active / Ideas / Portfolio / Archive | | Certificate | certificate | source, status, skills, credential_id, credential_url, issued_date | In Progress / Completed |

Conditional Fields

Fields appear only when relevant:

• completed_date — only when Game status is "Completed"
• watched_date — only when Movie status is "Watched"
• finished_date — only when Series status is "Watched" or Dev Project status is "Completed"/"Dropped"
• taught_date / recorded_date — only when Dance status matches

Git Integration

After creating a note, kcli asks whether to commit it:

? Commit this note to git? (Y/n)
✓ Committed to git

File Creator

Create files from the terminal with three modes:

# Empty file (auto-creates directories)
kcli newfile path/to/file.txt

# Inline content (supports \n and \t escapes)
kcli newfile notes.md "# Title\nSome content"

# Open the built-in editor
kcli newfile notes.md --editor

Options

| Flag | Description | |------|-------------| | -e, --editor | Open the built-in terminal editor | | -f, --force | Overwrite without confirmation |

Built-in Editor

A nano-style text editor that runs entirely in the terminal. No external tools required — works on Windows, Mac, and Linux.

 myfile.md [modified]
  1 # Hello World
  2 
  3 Some content here.
  4 
  ~
  ~
                                    Ln 3, Col 19  4 lines
 ^S Save  ^Q Quit  ^X Cancel  ^C Copy  ^V Paste  ^A Select All  ^L Cut Line

Keybinds

| Key | Action | |-----|--------| | Arrow keys | Move cursor | | Home / End | Jump to start / end of line | | PgUp / PgDn | Scroll by page | | Shift + Arrow | Select text | | Shift + Home / End | Select to start / end of line | | Ctrl+A | Select all | | Ctrl+C | Copy selection (or current line) | | Ctrl+V | Paste from clipboard | | Ctrl+L | Cut current line | | Ctrl+S | Save and exit | | Ctrl+Q | Quit (saves if modified) | | Ctrl+X | Cancel without saving | | Tab | Insert 2 spaces |

Editor Features

• Line numbers in the gutter
• Scroll viewport for large files
• [modified] indicator in the title bar
• SEL indicator in the status bar during selection
• Selected text highlighted with a distinct background
• Typing, backspace, or delete replaces the active selection
• Multi-line paste support
• Cross-platform clipboard (powershell on Windows, pbcopy/pbpaste on Mac, xclip on Linux)

Configuration

Config is stored at ~/.config/kcli/config.json.

{
  "vaultPath": "/path/to/your/obsidian/vault"
}

Requirements

• Node.js >= 18.0.0
• An Obsidian vault (for vault commands)

License

MIT

Author

Kelvin Klein