obsidian-cli

A command-line interface for managing Obsidian vaults via the Local REST API plugin.

Features

• Note Management: List, read, write, append, and delete notes
• Search: Simple text search and Omnisearch integration
• Dataview Queries: Execute TABLE queries against your vault
• Command Execution: List and run Obsidian commands
• Frontmatter Access: Read and extract YAML frontmatter
• Tag Aggregation: List all tags with usage counts
• Multiple Output Formats: JSON, JSONL, text, and markdown
• Shell Completions: Bash, Zsh, Fish, and PowerShell
• Profile Support: Multiple vault configurations

Requirements

• Obsidian with the Local REST API plugin installed and enabled
• Go 1.24+ (for building from source)

Installation

Pre-built Binaries

Download the latest release for your platform from the Releases page.

Linux/macOS:

# Set version and platform
VERSION=1.0.0
# Options: linux_amd64, linux_arm64, darwin_amd64, darwin_arm64
PLATFORM=linux_amd64

curl -LO "https://github.com/n0vsec/obsidian-cli/releases/download/v${VERSION}/obsidian-cli_${VERSION}_${PLATFORM}.tar.gz"
tar xzf obsidian-cli_${VERSION}_${PLATFORM}.tar.gz
sudo mv obsidian-cli /usr/local/bin/

Windows:

Download the appropriate .zip from the Releases page and add to your PATH.

From Source

git clone https://github.com/n0vsec/obsidian-cli.git
cd obsidian-cli
go build -o obsidian-cli .

Go Install

go install github.com/n0vsec/obsidian-cli@latest

Configuration

Quick Setup

# Initialize configuration (prompts for API key)
obsidian-cli config init

# Or use environment variable
export OBSIDIAN_API_KEY="your-api-key-here"

Getting Your API Key

1. Open Obsidian
2. Go to Settings > Community Plugins > Local REST API
3. Copy the API key shown in the plugin settings

Configuration File

Configuration is stored at ~/.config/obsidian-cli/config.yaml:

default:
  api_key: "your-api-key"
  api:
    host: "127.0.0.1"
    port: 27124
    protocol: "https"
    verify_ssl: false
  output:
    format: "text"
    color: true

# Additional profiles for multiple vaults
work:
  api_key: "different-key"
  api:
    port: 27125

Use profiles with --profile:

obsidian-cli --profile work note list

Environment Variables

• OBSIDIAN_API_KEY - API key for authentication
• OBSIDIAN_API_HOST - API host (default: 127.0.0.1)
• OBSIDIAN_API_PORT - API port (default: 27124)

Usage

Global Flags

These flags work with any command:

Flag	Short	Description
--format	-f	Output format: json, jsonl, text, markdown (default: text)
--profile	-p	Config profile to use (default: default)
--verbose	-v	Verbose output
--api-key		API key (overrides config/env)
--host		API host (default: 127.0.0.1)
--port		API port (default: 27124)
--protocol		API protocol: http or https (default: https)
--verify-ssl		Verify SSL certificate (default: false)
--config		Config file path
--version		Show version

Note Operations

# List all notes
obsidian-cli note list

# List notes in a specific folder
obsidian-cli note list "Daily/"

# Read a note
obsidian-cli note read "Daily/2025-12-03.md"

# Read raw content (no frontmatter parsing)
obsidian-cli note read "Daily/2025-12-03.md" --raw

# Create or replace a note
obsidian-cli note write "Inbox/new-note.md" --content "# My Note\n\nContent here"

# Write from stdin
echo "# Note from pipe" | obsidian-cli note write "Inbox/piped.md" --stdin

# Append to a note
obsidian-cli note append "Daily/2025-12-03.md" --content "\n## Evening Update\nMore content"

# Delete a note (requires --force)
obsidian-cli note delete "Inbox/old-note.md" --force

Search

# Simple text search
obsidian-cli search simple "meeting notes"

# With context lines
obsidian-cli search simple "TODO" --context 3

# Omnisearch (requires Omnisearch plugin with HTTP server enabled)
obsidian-cli search omnisearch "project ideas"

Dataview Queries

# Execute a TABLE query
obsidian-cli query dataview 'TABLE file.ctime, file.mtime FROM "Daily" LIMIT 10'

# JSON output for processing
obsidian-cli --format json query dataview 'TABLE tags FROM "" WHERE tags' | jq '.[]'

Commands

# List all available commands
obsidian-cli command list

# Filter commands
obsidian-cli command list --filter "daily"

# Execute a command
obsidian-cli command run "daily-notes"
obsidian-cli command run "editor:save-file"

Frontmatter

# Get all frontmatter from a note
obsidian-cli frontmatter get "Projects/my-project.md"

# Get specific key
obsidian-cli frontmatter get "Projects/my-project.md" --key tags

# JSON output
obsidian-cli --format json frontmatter get "Projects/my-project.md"

Tags

# List all tags with counts
obsidian-cli tags list

# Sort by count (most used first)
obsidian-cli tags list --sort count

# Sort alphabetically
obsidian-cli tags list --sort alpha

Configuration Management

# Show current configuration
obsidian-cli config show

# Show with API key visible
obsidian-cli config show --show-secrets

# Initialize new config file
obsidian-cli config init

# Force overwrite existing config
obsidian-cli config init --force --api-key "new-key"

Output Formats

All commands support multiple output formats via --format:

# JSON (structured, good for jq)
obsidian-cli --format json note list

# JSONL (one JSON object per line, good for streaming)
obsidian-cli --format jsonl note list

# Text (default, human-readable)
obsidian-cli --format text note list

# Markdown (tables and code blocks)
obsidian-cli --format markdown tags list

Shell Completions

Bash

# Add to ~/.bashrc
source <(obsidian-cli completion bash)

Zsh

# Add to ~/.zshrc
source <(obsidian-cli completion zsh)

Fish

obsidian-cli completion fish > ~/.config/fish/completions/obsidian-cli.fish

PowerShell

obsidian-cli completion powershell | Out-String | Invoke-Expression

Exit Codes

Code	Meaning
0	Success
1	General error
2	Not found
3	Configuration error
4	API error

Tips

Shell Quoting

• Single quotes are recommended for paths with special characters (!, #, &, etc.)
• The ! character triggers bash history expansion in double quotes

# Good: single quotes
obsidian-cli note read '2025 Winter Prep!.md'

# May cause issues: double quotes with !
obsidian-cli note read "2025 Winter Prep!.md"

Searching for Special Patterns

Use -- to separate flags from arguments starting with -:

# Search for checkbox patterns
obsidian-cli search simple -- '- [ ]'

# Without --, the leading dash is interpreted as a flag

Man Pages

Generate man pages for all commands:

obsidian-cli man /usr/local/share/man/man1/

Limitations

• Dataview: Only TABLE queries are supported (not LIST or TASK)
• Omnisearch: Requires the Omnisearch plugin with HTTP server enabled (port 51736)
• SSL: Uses self-signed certificate by default (verify_ssl: false)

License

MIT