vaultctl 0.3.1 → 0.4.0

package/README.md

@@ -0,0 +1,146 @@
+# 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
+vaultctl config set vault ~/path/to/your/vault
+```
+
+That's it. The config is saved to `~/.vaultctlrc` and works everywhere — interactive shells, AI agents, cron jobs, CI.
+
+### From Source
+
+```bash
+git clone https://github.com/testing-in-production/vaultctl.git
+cd vaultctl
+npm install
+npm run build
+alias vaultctl="node $HOME/vaultctl/packages/cli/dist/index.js"
+vaultctl config set vault ~/path/to/your/vault
+```
+
+## 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
+
+### Why `config set` Instead of Environment Variables?
+
+Shell aliases and environment variables from `~/.zshrc` or `~/.bashrc` aren't available in non-interactive shells (AI agents, cron jobs, CI). `vaultctl config set vault` writes to `~/.vaultctlrc`, which is a file read — it works everywhere.
+
+You can still use `VAULTCTL_PATH` or `--vault` if you prefer — they take higher precedence in the discovery chain.
+
+## 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/config.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+export declare function registerConfigCommand(program: Command): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/commands/config.js

@@ -0,0 +1,79 @@
+import { resolve, join } from 'path';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { formatOutput } from '../format.js';
+const RC_PATH = join(homedir(), '.vaultctlrc');
+export function registerConfigCommand(program) {
+    const config = program
+        .command('config')
+        .description('Manage vaultctl configuration');
+    config
+        .command('show')
+        .description('Show current configuration and vault discovery status')
+        .action((_opts, cmd) => {
+        const globalOpts = cmd.parent.parent.opts();
+        const format = (globalOpts.format ?? 'json');
+        const rcExists = existsSync(RC_PATH);
+        const rcValue = rcExists ? readFileSync(RC_PATH, 'utf-8').trim() : null;
+        const envValue = process.env['VAULTCTL_PATH'] ?? null;
+        // Determine which method would resolve
+        let resolvedBy = 'none';
+        let resolvedPath = null;
+        if (globalOpts.vault) {
+            const abs = resolve(globalOpts.vault);
+            if (existsSync(join(abs, '.obsidian'))) {
+                resolvedBy = '--vault flag';
+                resolvedPath = abs;
+            }
+        }
+        if (!resolvedPath && envValue) {
+            const abs = resolve(envValue);
+            if (existsSync(join(abs, '.obsidian'))) {
+                resolvedBy = 'VAULTCTL_PATH env var';
+                resolvedPath = abs;
+            }
+        }
+        if (!resolvedPath && rcValue) {
+            const abs = resolve(rcValue);
+            if (existsSync(join(abs, '.obsidian'))) {
+                resolvedBy = '~/.vaultctlrc';
+                resolvedPath = abs;
+            }
+        }
+        const result = {
+            rc_file: RC_PATH,
+            rc_value: rcValue,
+            env_var: envValue,
+            resolved_by: resolvedBy,
+            resolved_path: resolvedPath,
+        };
+        console.log(formatOutput(result, format));
+    });
+    config
+        .command('set')
+        .description('Set a configuration value')
+        .argument('<key>', 'Configuration key (currently: vault)')
+        .argument('<value>', 'Configuration value')
+        .action((key, value, _opts, cmd) => {
+        const globalOpts = cmd.parent.parent.opts();
+        const format = (globalOpts.format ?? 'json');
+        if (key !== 'vault') {
+            console.error(`Unknown config key: "${key}". Available keys: vault`);
+            process.exit(1);
+        }
+        const abs = resolve(value);
+        if (!existsSync(join(abs, '.obsidian'))) {
+            console.error(`No .obsidian directory found at: ${abs}`);
+            process.exit(1);
+        }
+        writeFileSync(RC_PATH, abs + '\n', 'utf-8');
+        const result = {
+            saved: true,
+            key: 'vault',
+            value: abs,
+            rc_file: RC_PATH,
+        };
+        console.log(formatOutput(result, format));
+    });
+}
+//# sourceMappingURL=config.js.map

package/dist/index.js

@@ -6,11 +6,12 @@ import { registerHealthCommand } from './commands/health.js';
 import { registerCreateCommand } from './commands/create.js';
 import { registerReadCommand } from './commands/read.js';
 import { registerInfoCommand } from './commands/info.js';
+import { registerConfigCommand } from './commands/config.js';
 const program = new Command();
 program
     .name('vaultctl')
     .description('Structured Obsidian vault operations without MCP servers')
-    .version('0.3.1')
+    .version('0.4.0')
     .option('--vault <path>', 'Path to Obsidian vault')
     .option('--format <format>', 'Output format: json or table', 'json');
 registerSearchCommand(program);
@@ -19,5 +20,6 @@ registerHealthCommand(program);
 registerCreateCommand(program);
 registerReadCommand(program);
 registerInfoCommand(program);
+registerConfigCommand(program);
 program.parse();
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vaultctl",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "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.1",
+    "@vaultctl/core": "^0.4.0",
     "chalk": "^5.4.0",
     "commander": "^13.0.0"
   }