vault-cli

README

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.

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"
  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 and assign to current user

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

vault-cli vision list                      # List vision items
vault-cli vision lint                      # Detect frontmatter issues
vault-cli vision search "long-term growth" # Semantic search in vision

decision

vault-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 override

search

vault-cli search "improve performance"          # Search entire vault semantically
vault-cli search "improve performance" --top-k 10  # Return more results

config

vault-cli config list          # List configured vaults
vault-cli config current-user  # Print the current user

Shell Completion

# Zsh
source <(vault-cli completion zsh)

# Bash
source <(vault-cli completion bash)

# Fish
vault-cli completion fish | source

Development

make test      # Run tests
make check     # Linting and checks
make precommit # Full development workflow

License

BSD-2-Clause