obsidian-kb-cli

0.4.0 verified Fri May 01 auth: no javascript

A CLI tool for managing Obsidian vaults following the Karpathy-style LLM-wiki workflow. Provides lint, bootstrap, index, and log commands for vaults structured with topic folders containing index.md, CLAUDE.md schemas, and entry notes with YAML frontmatter. Current stable version is 0.4.0 (March 2025). Release cadence is irregular, with major features in recent releases including attachment-aware linting and nested-topic exclusion. Key differentiators: companion to the obsidian-kb LLM skill, designed for cron jobs and git pre-commit hooks, supports wikilinks, stale claims via git history, and machine-readable JSON output.

Common errors

error Error: ENOENT: no such file or directory, open '/path/to/vault/...' ↓

cause Vault path specified incorrectly or does not exist.

fix

Provide an absolute or correct relative path to the Obsidian vault directory.

error Error: Cannot find module 'obsidian-kb-cli' ↓

cause Package not installed globally or locally.

fix

Run 'npm i -g obsidian-kb-cli' to install globally, or use 'npx obsidian-kb-cli'.

error Error: Invalid template 'custom' ↓

cause Bootstrap called with a template name that doesn't exist.

fix

Use one of: generic, projects, papers, books, people.

error Error: --output file exists. Use --force to overwrite. ↓

cause Index or bootstrap command tried to write to an existing file without --force.

fix

Add '--force' flag to overwrite, or specify a different --output path.

Warnings

breaking v0.4.0 changed the vault path resolution to use exact vaultPath, which may cause lints to fail if vault path is specified differently from how Obsidian stores it. ↓

fix Ensure you pass the correct vault path as used by Obsidian (e.g., absolute path, no trailing slash).

breaking v0.4.0 scoped the not-in-index orphan check to direct children only, so deeply nested notes that were previously flagged may no longer be reported. ↓

fix If you rely on flagging nested orphans, adjust your workflow — only direct children of the topic folder are now checked.

breaking v0.4.0 skips entry notes inside sub-folders that have their own index.md, preventing double-flagging against parent topic. This may change existing lint results. ↓

fix Review lint findings after upgrade; some entries may no longer appear in parent topic's checks.

gotcha The watch command requires chokidar (included) and may have higher CPU usage on very large vaults due to watching all .md files. ↓

fix Use --topic to restrict watched folder or increase --debounce to reduce relint frequency.

gotcha The bootstrap command will refuse to overwrite existing files unless --force is used. This can be surprising when re-bootstrapping. ↓

fix Add --force flag if you want to overwrite existing CLAUDE.md, index.md, or log.md.

Install

npm install obsidian-kb-cli

yarn add obsidian-kb-cli

pnpm add obsidian-kb-cli

Imports

default

wrong

obkb lint /path/to/vault (if not installed globally)

correct

npx obsidian-kb-cli lint /path/to/vault

Install globally via npm i -g obsidian-kb-cli, or use npx without install.

lint
```
obkb lint ~/vault --topic Projects --json
```
The lint command walks top-level folders with index.md. Use --json for machine-readable output.

bootstrap

wrong

obkb bootstrap Papers --vault ~/vault (wrong template if non-default)

correct

obkb bootstrap Papers --vault ~/vault --template papers

Template options: generic, projects, papers, books, people. Default is generic.

index

wrong

obkb index Projects --vault ~/vault --output ~/vault/Projects/index.md (without --force, will refuse to overwrite)

correct

obkb index Projects --vault ~/vault --output draft.md

Non-destructive by default. Use --force to overwrite existing index.md, or --output - to stdout.

Quickstart

Shows installation, basic lint, bootstrap, index generation, help, and watch commands.

// Install globally
npm i -g obsidian-kb-cli

// Lint a vault
obkb lint ~/vault

// Bootstrap a new topic with a template
obkb bootstrap Projects --vault ~/vault --template projects

// Generate an index for a topic
obkb index Projects --vault ~/vault --output draft.md

// Show help for a command
obkb help bootstrap

// Watch for changes and re-lint
obkb watch ~/vault --debounce 250