vaultctl 0.3.0 → 0.3.2

package/README.md

@@ -0,0 +1,148 @@
+# vaultctl
+
+Structured Obsidian vault operations without MCP servers.
+
+`vaultctl` is a CLI tool that gives [Claude Code](https://claude.com/claude-code) and other AI agents structured access to Obsidian vaults — search, tag management, health checks, and template-based note creation — without running a persistent MCP server process.
+
+## Why?
+
+MCP servers for Obsidian + Claude Code CLI are [fundamentally broken](https://github.com/anthropics/claude-code/issues/9176). Claude Code's stdio pipe lifecycle management kills server connections before they initialise, causing `BrokenPipeError` on every session. Meanwhile, Obsidian vaults are just directories of markdown files — there's no reason to run a persistent server process to read them.
+
+`vaultctl` replaces MCP with stateless CLI commands. Every invocation reads the filesystem, does its thing, and exits. No pipes, no zombie processes, no lifecycle bugs.
+
+## Install
+
+```bash
+npm install -g vaultctl
+```
+
+Then set your vault path in `~/.zshrc` or `~/.bashrc`:
+
+```bash
+export VAULTCTL_PATH="$HOME/path/to/your/vault"
+```
+
+### From Source
+
+```bash
+git clone https://github.com/testing-in-production/vaultctl.git
+cd vaultctl
+npm install
+npm run build
+```
+
+Then add to your shell profile:
+
+```bash
+export VAULTCTL_PATH="$HOME/path/to/your/vault"
+alias vaultctl="node $HOME/vaultctl/packages/cli/dist/index.js"
+```
+
+## Usage
+
+### Search
+
+```bash
+# Full-text content search
+vaultctl search "meeting notes"
+
+# Filter by frontmatter fields
+vaultctl search --type project --status active
+
+# Filter by tag
+vaultctl search --tag "status/active"
+
+# Combine filters
+vaultctl search "quarterly" --type project --status active
+```
+
+### Tags
+
+```bash
+# List all tags with counts
+vaultctl tags list
+
+# Find notes with a specific tag
+vaultctl tags find status/active
+
+# Add/remove tags
+vaultctl tags add 01_Projects/my-project.md priority/high
+vaultctl tags remove 01_Projects/my-project.md priority/high
+
+# Rename a tag across the entire vault (dry-run first)
+vaultctl tags rename status/active status/in-progress
+vaultctl tags rename status/active status/in-progress --yes
+```
+
+### Health
+
+```bash
+# Run all health checks
+vaultctl health
+
+# Run specific checks
+vaultctl health --check broken-links
+vaultctl health --check orphans
+vaultctl health --check stale --days 90
+vaultctl health --check frontmatter
+```
+
+### Create
+
+```bash
+# Create a note from a template
+vaultctl create --template project "My New Project"
+vaultctl create --template daily
+
+# Specify target folder
+vaultctl create --template concept --folder 03_Resources/concepts "Zettelkasten"
+
+# List available templates
+vaultctl create --list
+```
+
+### Read & Info
+
+```bash
+# Read a note (parsed with frontmatter, wikilinks, tags)
+vaultctl read 01_Projects/my-project.md
+
+# Vault overview statistics
+vaultctl info
+```
+
+## Output
+
+JSON by default (designed for AI agent consumption). Add `--format table` for human-readable output.
+
+Exit codes: `0` = success, `1` = error, `2` = no results found.
+
+## Vault Discovery
+
+`vaultctl` finds your vault in this order:
+
+1. `--vault /path/to/vault` flag
+2. `VAULTCTL_PATH` environment variable
+3. Walk up from current directory looking for `.obsidian/`
+4. `~/.vaultctlrc` config file
+
+## Features
+
+- **Search** — Full-text content search with type, status, and tag filters
+- **Tags** — List, find, add, remove, and rename tags (frontmatter + inline `#tags` unified)
+- **Health** — Broken `[[wikilinks]]`, orphaned notes, stale notes, missing frontmatter
+- **Templates** — Create notes from `_templates/tpl-*.md` with date/title substitution
+- **Wikilink resolution** — All `[[links]]` resolved to file paths or flagged as broken
+- **Path traversal protection** — All write operations validated against vault root
+
+## Architecture
+
+This is the CLI wrapper package. The core logic lives in [`@vaultctl/core`](https://www.npmjs.com/package/@vaultctl/core) — a pure TypeScript library with zero CLI dependencies that can be imported by other tools.
+
+## Blog Post
+
+Read the full story: [I Replaced My Obsidian MCP Server With a CLI](https://www.testinginproduction.co/blog/i-replaced-mcp-with-a-cli)
+
+## License
+
+MIT

package/dist/commands/search.js

@@ -23,7 +23,7 @@ export function registerSearchCommand(program) {
                 console.log(formatOutput([], format));
                 process.exit(2);
             }
-            const output = results.map(n => formatNoteRow(n, format));
+            const output = results.map(n => formatNoteRow(n));
             console.log(formatOutput(output, format));
         }
         catch (err) {

package/dist/commands/tags.js

@@ -39,7 +39,7 @@ export function registerTagsCommand(program) {
                 console.log(formatOutput([], format));
                 process.exit(2);
             }
-            const output = results.map(n => formatNoteRow(n, format));
+            const output = results.map(n => formatNoteRow(n));
             console.log(formatOutput(output, format));
         }
         catch (err) {

package/dist/format.d.ts

@@ -3,5 +3,5 @@ export declare function formatOutput(data: unknown, format: OutputFormat): strin
 export declare function formatNoteRow(note: {
     path: string;
     frontmatter: Record<string, unknown>;
-}, format: OutputFormat): Record<string, unknown>;
+}): Record<string, unknown>;
 //# sourceMappingURL=format.d.ts.map

package/dist/format.js

@@ -26,7 +26,7 @@ function formatTableRow(obj) {
     })
         .join('\n');
 }
-export function formatNoteRow(note, format) {
+export function formatNoteRow(note) {
     return {
         path: note.path,
         type: note.frontmatter.type ?? '',

package/dist/index.js

@@ -10,7 +10,7 @@ const program = new Command();
 program
     .name('vaultctl')
     .description('Structured Obsidian vault operations without MCP servers')
-    .version('0.3.0')
+    .version('0.3.2')
     .option('--vault <path>', 'Path to Obsidian vault')
     .option('--format <format>', 'Output format: json or table', 'json');
 registerSearchCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vaultctl",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "CLI for structured Obsidian vault operations — search, tags, health checks, templates — without MCP servers",
   "type": "module",
   "license": "MIT",
@@ -25,7 +25,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@vaultctl/core": "^0.3.0",
+    "@vaultctl/core": "^0.3.2",
     "chalk": "^5.4.0",
     "commander": "^13.0.0"
   }