Go CLI tool for managing Obsidian vault tasks, goals, themes, objectives, visions, and decisions.
Fast CRUD operations for Obsidian markdown files (tasks, goals, themes, objectives, visions, decisions) without spawning full Claude Code sessions.
Standalone-usable — local filesystem I/O against an Obsidian vault. No Kubernetes, no cluster. Works against any Obsidian vault that follows the bborbe frontmatter conventions. It opens a Kafka broker connection only when the optional notification section of the config file names brokers; with no brokers configured it publishes nothing and connects nowhere.
vault-cli is the operator-side surface for the bborbe task / agent system:
- Humans use it to CRUD vault tasks directly through the phase-gated lifecycle (
/vault-cli:create-task→/vault-cli:work-on-task→/vault-cli:plan-task→/vault-cli:execute-task→ work —/vault-cli:update-task//vault-cli:task-status//vault-cli:next-steps→/vault-cli:sync-progress→/vault-cli:complete-task→/vault-cli:session-close) - task-orchestrator wraps it as the backend of a Kanban / session-launcher UI
- The reference AI agents in bborbe/agent import
vault-cli/pkg/domainfor the shared vault types - Manual
/vault-cli:create-taskis one of the ways a task enters the broader Kafka task pipeline
vault-cli reads and mutates the vault that the pipeline materializes. Its only pipeline write is opt-in and narrow: when the config file names brokers, clearing a task's assignee publishes one agent-escalation notification into the shared notification core, so a park performed by hand tells the agent side what happened.
Full system map: recurring-task-creator/docs/system-map.md.
go install github.com/bborbe/vault-cli@latestCreate ~/.config/vault-cli/config.yaml (XDG-first location; the legacy path ~/.vault-cli/config.yaml is still read as a fallback when the XDG file is absent):
default_vault: personal
vaults:
personal:
name: personal
path: ~/Documents/Obsidian/Personal
tasks_dir: "25 Tasks"
goals_dir: "24 Goals"
topics_dir: "23 Topics"
daily_dir: "60 Periodic Notes/Daily"
excludes:
- "90 Templates"
- ".obsidian"
brogrammers:
name: brogrammers
path: ~/Documents/Obsidian/Brogrammers
tasks_dir: "40 Tasks"
daily_dir: "60 Periodic Notes/Daily"Clearing a task's assignee — vault-cli task set "<task>" assignee "" or vault-cli task clear "<task>" assignee — publishes one agent-escalation notification into the shared notification core, so a park performed by hand reaches the operator's chat. This is opt-in and off by default: omit the section and vault-cli never opens a broker connection.
notification:
brokers: "broker-1:9092,broker-2:9092"
topic_prefix: "master"brokers— comma-separated broker addresses. Empty or absent means no publish and no connection attempt.topic_prefix— the deployment's Kafka topic prefix, the same value the consuming services derive from their branch (masterin prod,developin dev). A producer that omits it publishes into a topic nothing consumes.
The publish is bounded to a single attempt of five seconds. A failure or an unreachable broker is logged, never fails the command, never changes its exit code or output, and never delays it past that bound.
--vault <name> # Use a specific vault (default vault if omitted)
--output plain|json # Output format (default: plain)
--config <path> # Custom config file pathvault-cli task list # List active tasks (todo + in_progress)
vault-cli task list --status deferred # Filter by status
vault-cli task list --all # Show all tasks
vault-cli task list --assignee alice # Filter by assignee
vault-cli task show "Build vault-cli Go Tool" # Show full task detail
vault-cli task complete "Build vault-cli Go Tool" --reason "..." --gate-successor none # Mark task as complete
vault-cli task defer "Migrate TaskOrchestrator" +7d # Defer by relative days
vault-cli task defer "Migrate TaskOrchestrator" monday # Defer to next weekday
vault-cli task defer "Migrate TaskOrchestrator" 2026-03-01 # Defer to ISO date
vault-cli task update "Build vault-cli Go Tool" # Update progress from checkboxes
vault-cli task work-on "Build vault-cli Go Tool" # Mark in_progress; assignee: blank→current_user, equal→no-op, other→preserved+⚠️
vault-cli task get "Build vault-cli Go Tool" status # Get a frontmatter field
vault-cli task set "Build vault-cli Go Tool" status done --reason "..." --gate-successor none # Set a frontmatter field
vault-cli task clear "Build vault-cli Go Tool" assignee # Clear a frontmatter field
vault-cli task append-metrics-session "Build vault-cli Go Tool" <session-id> # Append one metrics_sessions entry (use this, not set/add/remove)
vault-cli task lint # Detect frontmatter issues
vault-cli task lint --fix # Auto-fix frontmatter issues
vault-cli task validate "Build vault-cli Go Tool" # Validate a single task
vault-cli task backfill-identifiers # Assign task_identifier to tasks missing one
vault-cli task watch # Stream file-change events as JSON
vault-cli task search "improve CLI performance" # Semantic search in tasksvault-cli goal list # List goals
vault-cli goal lint # Detect frontmatter issues
vault-cli goal search "team productivity" # Semantic search in goalsvault-cli theme list # List themes
vault-cli theme lint # Detect frontmatter issues
vault-cli theme search "engineering culture" # Semantic search in themesvault-cli objective list # List objectives
vault-cli objective lint # Detect frontmatter issues
vault-cli objective search "Q2 goals" # Semantic search in objectivesvault-cli vision list # List vision items
vault-cli vision lint # Detect frontmatter issues
vault-cli vision search "long-term growth" # Semantic search in visionvault-cli topic list # List topics
vault-cli topic lint # Detect frontmatter issues
vault-cli topic search "attention routing" # Semantic search in topics
vault-cli topic show "Attention Routing" # Show full topic detail
vault-cli topic get "Attention Routing" phase # Get a frontmatter field
vault-cli topic set "Attention Routing" owner alice # Set a frontmatter field
vault-cli topic clear "Attention Routing" owner # Clear a frontmatter field
vault-cli topic add "Attention Routing" tags focus # Add a value to a list field
vault-cli topic remove "Attention Routing" tags focus # Remove a value from a list field
vault-cli topic complete "Attention Routing" # Mark a topic as complete
vault-cli topic defer "Attention Routing" +7d # Defer a topic to a specific date
vault-cli topic work-on "Attention Routing" # Mark in_progress and start a Claude sessionvault-cli decision list # List decisions pending review
vault-cli decision list --reviewed # Show only reviewed decisions
vault-cli decision list --all # Show all decisions
vault-cli decision ack "Use PostgreSQL" # Acknowledge (mark as reviewed)
vault-cli decision ack "Use PostgreSQL" --status accepted # Ack with status overridevault-cli search "improve performance" # Search entire vault semantically
vault-cli search "improve performance" --top-k 10 # Return more resultsvault-cli config list # List configured vaults
vault-cli config current-user # Print the current user
vault-cli config set-baseline personal "60 Baseline.md" # Point a vault at its baseline fileThe path passed to config set-baseline is vault-relative — an absolute path, or
one whose cleaned form escapes the vault root, is refused. The value is written
to the named vault's entry in the config file under the key baseline;
docs/baseline-file.md documents the file's frontmatter contract.
vault-cli rollup weekly # Last complete ISO week, plain report
vault-cli rollup weekly --week 2026-W37 # A named ISO week
vault-cli rollup weekly --vault personal # A named vault (default_vault when omitted)
vault-cli rollup weekly --output json # The same figures as JSONrollup weekly reports three figures for one ISO week: the week's human
interactions (the sum of metrics_interaction_count over the tasks completed
in that week), its unattended deliveries (completed tasks whose recorded
interaction count is exactly zero), and the median interactions of a recurring
task family — the headline median of the per-family medians, with each family
listed beneath it.
The command reads only task frontmatter from one vault — the vault named by
--vault, or the config's default_vault when the flag is omitted, never every
configured vault at once — and writes nothing. A figure with no measurement
behind it reads undefined or no data in both plain and JSON output, never a
zero.
A vault whose config entry names a baseline file has that file's stored figures
printed above the computed ones under a Baseline (captured <date>) header, and
the movement from each computed figure to its baseline analogue printed last,
after the rule lines, under a Delta (vs baseline captured <date>) header. The
stored figures are echoed exactly as the file holds them — never recomputed,
rounded or rewritten — and a figure with no analogue (the unattended-delivery
count, the stored total, the stored agent coverage) gets no delta row. A vault
with no baseline configured prints exactly what it printed before.
docs/baseline-file.md carries the frontmatter contract
and the analogue mapping; vault-cli config set-baseline <vault> <path> records
the vault-relative path of the file the rollup reads.
vault-cli includes a Claude Code plugin for task management commands.
# Install
claude plugin marketplace add bborbe/vault-cli
claude plugin install vault-cli
# Update
claude plugin marketplace update vault-cli
claude plugin update vault-cli@vault-cli| Command | Description |
|---|---|
/vault-cli:complete-task |
Mark task as complete (normal or recurring) |
/vault-cli:defer-task |
Defer task to specific date |
/vault-cli:task-status |
Show task progress and next step |
/vault-cli:verify-task |
Quick task validation (status, goals, DoD) |
/vault-cli:audit-task |
Full task audit against Task Writing Guide |
/vault-cli:plan-task |
Validate Success Criteria + subtasks via task-auditor; conversationally fill gaps; leaves phase: planning and hands off to /execute-task (never flips phase itself) |
/vault-cli:execute-task |
Hard gate phase: planning → execution — re-runs plan-task's 4 hard non-negotiables, on pass flips phase + prints first unchecked subtask + DoD reminder. Idempotent on phase: execution |
/vault-cli:verify-goal |
Quick goal validation (status, subtasks) |
/vault-cli:audit-goal |
Full goal audit against Goal Writing Guide |
/vault-cli:plan-goal |
Validate required sections + that every # Tasks wikilink resolves to an existing task file, via goal-auditor; conversationally fill gaps; leaves phase: planning and hands off to /execute-goal (never flips phase itself) |
/vault-cli:execute-goal |
Gate phase: planning → execution — re-runs plan-goal's 3 hard checks, on pass flips phase + recommends the next open task one at a time until the goal drains, then points to /verify-goal → /complete-goal. Recommends only, never runs the task |
/vault-cli:verify-theme |
Quick theme validation (structure, sections) |
/vault-cli:audit-theme |
Full theme audit against Theme Writing Guide |
/vault-cli:audit-objective |
Full objective audit against Objective Writing Guide |
/vault-cli:sync-progress |
Sync conversation progress to daily note + task pages (mid-session checkpoint) |
/vault-cli:session-close |
End-of-session safety check — sync, git state, worktrees, reflect signals |
/vault-cli:post-compact |
Post-compaction verification — read the session checkpoint, verify carry-over items, re-arm watchers, surface next actions |
# Zsh
source <(vault-cli completion zsh)
# Bash
source <(vault-cli completion bash)
# Fish
vault-cli completion fish | sourcemake test # Run tests
make check # Linting and checks
make precommit # Full development workflowBSD-2-Clause