Registry / devops / obsidian-kb-cli

obsidian-kb-cli

library0.4.0jsnpmunverified

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.

devops workflow

npm install obsidian-kb-cli

github ↗package ↗

INSTALL

IMPORT

SIG · OBSIDIAN-KB-CLI

obsidian-kb-cli

devopsjavascriptv0.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

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

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

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

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

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

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

index

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

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

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

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

obsidian-kb --version

Debug

Known issues

breakingv0.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).

affects: >=0.4.0

breakingv0.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.

affects: >=0.4.0

breakingv0.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.

affects: >=0.4.0

gotchaThe 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.

affects: >=0.3.0

gotchaThe 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.

affects: >=0.1.0

Errors

Common errors & fixes

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

Vault path specified incorrectly or does not exist.

fix

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

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

Package not installed globally or locally.

fix

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

Error: Invalid template 'custom'

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

fix

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

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

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.

Upgrade

Version history

0.4.0latest on npm

Audit

Dependencies

chokidarrequiredUsed by watch command for reliable file watching across platforms

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Amazon

Resources

githubhttps://github.com/ab2891/obsidian-kb-cli ↗

packagehttps://www.npmjs.com/package/obsidian-kb-cli ↗