vault-cli

vault-cli

Go CLI tool for managing Obsidian vault tasks, goals, themes, objectives, visions, and decisions.

Overview

Fast CRUD operations for Obsidian markdown files (tasks, goals, themes, objectives, visions, decisions) without spawning full Claude Code sessions.

Standalone-usable — pure local filesystem I/O against an Obsidian vault. No Kafka, no Kubernetes, no cluster. Works against any Obsidian vault that follows the bborbe frontmatter conventions.

Where this fits in the bigger picture

vault-cli is the operator-side surface for the bborbe task / agent system:

• Humans use it to CRUD vault tasks directly (/vault-cli:create-task, /vault-cli:work-on-task, /vault-cli:sync-progress, …)
• task-orchestrator wraps it as the backend of a Kanban / session-launcher UI
• The reference AI agents in bborbe/agent import vault-cli/pkg/domain for the shared vault types
• Manual /vault-cli:create-task is one of the ways a task enters the broader Kafka task pipeline

vault-cli itself is not a pipeline participant: it never produces or consumes Kafka events. It reads and mutates the vault that the pipeline materializes.

Full system map: recurring-task-creator/docs/system-map.md.

Installation

go install github.com/bborbe/vault-cli@latest

Configuration

Create ~/.vault-cli/config.yaml:

default_vault: personal
vaults:
  personal:
    name: personal
    path: ~/Documents/Obsidian/Personal
    tasks_dir: "24 Tasks"
    goals_dir: "23 Goals"
    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"

Usage

Global Flags

--vault <name>       # Use a specific vault (default vault if omitted)
--output plain|json  # Output format (default: plain)
--config <path>      # Custom config file path

task

vault-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"  # 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    # Set a frontmatter field
vault-cli task clear "Build vault-cli Go Tool" assignee     # Clear a frontmatter field

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 watch                               # Stream file-change events as JSON
vault-cli task search "improve CLI performance"    # Semantic search in tasks

goal

vault-cli goal list                        # List goals
vault-cli goal lint                        # Detect frontmatter issues
vault-cli goal search "team productivity"  # Semantic search in goals

theme

vault-cli theme list                       # List themes
vault-cli theme lint                       # Detect frontmatter issues
vault-cli theme search "engineering culture"  # Semantic search in themes

objective

vault-cli objective list                   # List objectives
vault-cli objective lint                   # Detect frontmatter issues
vault-cli objective search "Q2 goals"      # Semantic search in objectives

vision