Files
onyx-cli/README.md
T

4.1 KiB

Onyx CLI

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

Building the Windows Executable (.exe)

You can build a standalone Windows executable using PyInstaller:

pip install pyinstaller
pyinstaller --onefile --name onyx src/onyx.py

The resulting onyx.exe will be found in the dist folder.

Installation

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

Quick Start

Set up your default vault:

onyx set-default "my-vault" --path "/path/to/vault"

Then use any command:

onyx open "note-name"
onyx daily
onyx frontmatter "note-name" --view --key "tags"

Commands

Vault Management

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

# Print current default vault
onyx print-default

Opening Notes

# Open a note in Obsidian
onyx open "note-name"

# Open note from specific vault
onyx open "note-name" --vault "vault-name"

Periodic Notes

# Create or open today's daily note
onyx daily

# Create or open this week's note
onyx weekly

# Create or open this month's note
onyx monthly

# Create or open this quarter's note
onyx quarterly

# Create or open this year's note
onyx yearly

Creating & Editing Notes

# Create a new note
onyx create "note-name"

# Create with content
onyx create "note-name" --content "Your content here"

# Create in specific vault
onyx create "note-name" --vault "vault-name"

# Overwrite existing note
onyx create "note-name" --content "New content" --overwrite

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

# Create and open
onyx create "note-name" --content "content" --open

Viewing Notes

# Print note contents to terminal
onyx print-note "note-name"

# Print from specific vault
onyx print-note "note-name" --vault "vault-name"

Moving & Deleting Notes

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

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

# Move and open
onyx move "old-path" "new-path" --open

# Delete a note
onyx delete "note-path"

# Delete from specific vault
onyx delete "note-path" --vault "vault-name"

Frontmatter Management

Edit note metadata in YAML frontmatter:

# View a frontmatter key
onyx frontmatter "note-name" --view --key "tags"

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

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

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

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

Version

# Display version
onyx --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