Files
onyx-cli/README.md
T
2025-10-28 21:52:04 -04:00

4.0 KiB

Onyx CLI - Obsidian Command Line Tool

A Python-based command-line interface for interacting with Obsidian vaults. Manage notes directly from the terminal without opening Obsidian.

Installation

  1. Clone this repository
  2. Install dependencies:
pip install -r requirements.txt

Quick Start

Set up your default vault:

ob-cli set-default "my-vault" --path "/path/to/vault"

Then use any command:

ob-cli open "note-name"
ob-cli daily
ob-cli frontmatter "note-name" --view --key "tags"

Commands

Vault Management

# Set default vault (required first time)
ob-cli set-default "vault-name" --path "/path/to/vault"

# Print current default vault
ob-cli print-default

Opening Notes

# Open a note in Obsidian
ob-cli open "note-name"

# Open note from specific vault
ob-cli open "note-name" --vault "vault-name"

Periodic Notes

# Create or open today's daily note
ob-cli daily

# Create or open this week's note
ob-cli weekly

# Create or open this month's note
ob-cli monthly

# Create or open this quarter's note
ob-cli quarterly

# Create or open this year's note
ob-cli yearly

Creating & Editing Notes

# Create a new note
ob-cli create "note-name"

# Create with content
ob-cli create "note-name" --content "Your content here"

# Create in specific vault
ob-cli create "note-name" --vault "vault-name"

# Overwrite existing note
ob-cli create "note-name" --content "New content" --overwrite

# Append to existing note
ob-cli create "note-name" --content "Additional content" --append

# Create and open
ob-cli create "note-name" --content "content" --open

Viewing Notes

# Print note contents to terminal
ob-cli print-note "note-name"

# Print from specific vault
ob-cli print-note "note-name" --vault "vault-name"

Moving & Deleting Notes

# Move or rename a note (auto-updates internal links)
ob-cli move "old-path" "new-path"

# Move in specific vault
ob-cli move "old-path" "new-path" --vault "vault-name"

# Move and open
ob-cli move "old-path" "new-path" --open

# Delete a note
ob-cli delete "note-path"

# Delete from specific vault
ob-cli delete "note-path" --vault "vault-name"

Frontmatter Management

Edit note metadata in YAML frontmatter:

# View a frontmatter key
ob-cli frontmatter "note-name" --view --key "tags"

# Check if a value exists in frontmatter
ob-cli frontmatter "note-name" --view --key "tags" --value "project"

# Edit frontmatter (add or update key)
ob-cli frontmatter "note-name" --edit --key "tags" --value "project"
ob-cli frontmatter "note-name" --edit --key "tags" --value "project,urgent"
ob-cli frontmatter "note-name" --edit --key "status" --value "in-progress"

# Clear frontmatter values
ob-cli frontmatter "note-name" --clear --key "tags"
ob-cli frontmatter "note-name" --clear --key "date,status,tags"

# Delete frontmatter keys
ob-cli frontmatter "note-name" --delete --key "tags"
ob-cli frontmatter "note-name" --delete --key "date,status,tags"

Version

# Display version
ob-cli --version

Features

  • Vault Management: Set and switch between multiple Obsidian vaults
  • Note Operations: Create, open, move, rename, and delete notes
  • Recursive Search: Find notes in nested directories
  • Periodic Notes: Support for daily, weekly, monthly, quarterly, and yearly notes
  • Frontmatter Management: Edit, view, clear, and delete YAML frontmatter
  • Link Updates: Automatically update internal links when moving notes
  • Cross-Platform: Works on macOS, Windows, and Linux

Requirements

  • Python 3.7+
  • click
  • pyyaml

Development

Running Tests

# Install test dependencies
pip install -r requirements.txt

# Run tests
python -m pytest

# Run with coverage
python -m pytest --cov=src tests/

Configuration

The CLI stores vault configuration in ~/.onyx-cli/config.yaml. You can manually edit this file to manage vaults:

default_vault: my-vault
vaults:
  my-vault: /path/to/vault
  work: /path/to/work/vault