npm package: @kevihq/kcli
Description: Personal CLI utilities - Obsidian vault manager, file editor, and more
Author: Kelvin Klein
Latest version: 1.2.0

# 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

```bash
npm install -g kcli
```

## Quick Start

```bash
# 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:

```bash
# 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`.

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

## Requirements

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

## License

MIT

## Author

Kelvin Klein