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
python -m PyInstaller onyx.spec

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

Periodic Notes Navigation

You can open, create, or navigate to specific daily, weekly, monthly, quarterly, or yearly notes using:

# Open a note for a specific date
onyx daily --date "2025-11-27"      # opens daily note for Nov 27, 2025
onyx weekly --date "2025-11-27"     # opens weekly note for the week containing Nov 27, 2025
onyx monthly --date "2025-11-27"    # opens monthly note for Nov 2025
onyx quarterly --date "2025-11-27"  # opens quarterly note for Q4 2025
onyx yearly --date "2025-11-27"     # opens yearly note for 2025

# Navigate to next or previous period
onyx daily --next        # opens tomorrow's note
onyx weekly --previous   # opens last week's note
onyx monthly --next      # opens next month's note
onyx quarterly --next    # opens next quarter's note
onyx yearly --previous   # opens last year's note

Default filename formats (used when nothing else is configured):

  • Daily: YYYY-MM-DD.md
  • Weekly: YYYY-WWW.md (ISO week, e.g. 2025-W48.md)
  • Monthly: YYYY-MM.md
  • Quarterly: YYYY-QX.md (e.g. 2025-Q4.md)
  • Yearly: YYYY.md

Folder, filename format, and template for each note type are resolved in this order:

  1. onyx's own config, set via onyx periodic (see below)
  2. Obsidian's Periodic Notes plugin, or the core Daily Notes plugin for daily notes
  3. The built-in defaults above

Each note type is resolved independently — configuring (or not configuring) one type never affects another. See Configuring Periodic Notes to set your own folders/formats/templates, especially for vaults without the Periodic Notes plugin installed (daily/weekly/monthly/quarterly/yearly notes not stored in the vault root).

Configuring Periodic Notes

# View the resolved settings for a note type
onyx periodic --type weekly --view

# Set your own folder / format / template for a note type
onyx periodic --type weekly --edit --folder "periodic/weekly" --format "YYYY-[W]WW" --template "resources/template/weekly-note.md"

# Any subset of --folder / --format / --template can be set at once
onyx periodic --type monthly --edit --folder "periodic/monthly"

# Configure a specific vault
onyx periodic --type weekly --edit --folder "periodic/weekly" --vault "work"

--format uses moment.js-style tokens (YYYY, MM, DD, [W]WW, [Q]Q, ...), matching what Obsidian's own daily-notes/periodic-notes settings use. --folder and --template are paths relative to the vault root.

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
  • Templates: Support for Core Templates and Templater
  • 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, or use onyx set-default and onyx periodic to edit it for you:

default_vault: my-vault
vaults:
  my-vault: /path/to/vault    # short form: just a path
  work:                       # long form: path plus optional settings
    path: /path/to/work/vault
    path_prefix: /path/to/prefix
    periodic_notes:
      weekly:
        folder: periodic/weekly
        format: YYYY-[W]WW
        template: resources/template/weekly-note.md
      monthly:
        folder: periodic/monthly
S
Description
CLI for interacting with Obsidian vaults from the terminal
Readme
19 MiB
0 Stars 1 Watchers 0 Forks
v0.4.3
Latest
2026-11-05 17:22:25 +01:00
Languages
Python 100%