Files
onyx-cli/README.md
T

12 KiB

Onyx CLI

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

Building a Standalone Executable

The same onyx.spec builds on both Windows and Linux — PyInstaller doesn't cross-compile, so build natively on each platform:

pip install pyinstaller
python -m PyInstaller onyx.spec
  • Windows produces dist/onyx.exe
  • Linux produces dist/onyx (no extension)

Prebuilt binaries for both platforms are also attached to each release: https://gitea.mithrilforge.dev/olivier/onyx-cli/releases

Installing the Linux binary

Drop the binary (built or downloaded) anywhere on your PATH:

chmod +x onyx
mv onyx ~/.local/bin/onyx     # or /usr/local/bin/onyx (needs sudo)

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

# Scripts and agents: create if missing without opening Obsidian, print only the path
onyx daily --date "2025-11-27" --no-open --print-path

Output is UTF-8 with LF line endings on every OS, so p=$(onyx daily --print-path) works in bash on Windows too. With --no-open, a newly created note keeps the template's raw Templater syntax (<% … %>) until Obsidian processes it; when Obsidian is running, Templater's "trigger on new file creation" renders it within seconds.

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; rewrites every wikilink that resolves to it:
# [[name]], [[name|alias]], [[name#heading]], ![[embeds]], [[folder/name]], frontmatter 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"

move refuses to overwrite an existing note. A bare [[name]] link is only rewritten when that name was unique in the vault (otherwise it is reported and left alone); the new link stays bare unless the new name is shared by another note, in which case it becomes a path link. Markdown [text](path.md) links are not rewritten.

# 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"

# Add / remove single items of a list property (repeat --value for several items)
onyx frontmatter "note-name" --add --key "participants" --value "[[Haro]]" --value "[[Jeffrey]]"
onyx frontmatter "note-name" --remove --key "participants" --value "[[Haro]]"

# 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"

Edits only touch the targeted keys: key order, quoting, accents and long values elsewhere in the frontmatter stay byte-for-byte identical. Values are written the way Obsidian stores them: plain when YAML reads them back unchanged (done, 2026-10-19, 3), double-quoted otherwise ("[[Haro]]"). tags, and any key that is already a list in the note, take a comma-separated list with --edit, written as a block list. Cleared keys become empty (status:), cleared tags tags: [].

--add and --remove change one list without rewriting it: items are taken whole (no comma splitting) and matched by wikilink target, so [[Name|Alias]] and [[name]] are the same item. --add skips duplicates, creates the list if the key is missing, and turns a text value into the first item. A list holding unquoted [[links]] (which YAML reads as nested lists) is refused.

Editing One Section

# Append at the end of a section (before the next heading of the same or a higher level)
onyx section "periodic/daily/2026-10-19" --heading "## Journal" --content "### 10:00 - Titre\n- note"
onyx section "periodic/daily/2026-10-19" --heading "### Matin" --content "- [ ] Appeler Haro"

# Replace a section's body; --content - reads stdin; --create adds a missing section at the end
onyx section "periodic/weekly/2026-W43" --heading "## Weekly review" --replace --create --content - < review.md

--heading "## Journal" matches that level only; --heading Journal matches any level (case-insensitive). Appended text gets a blank line before it, except between two list items, so a list stays one list. Headings in the frontmatter or in code blocks are ignored, and everything outside the section is left byte-for-byte. A missing heading is an error (listing the note's headings) unless --create.

Finding Notes

# By filename or alias: exact, ignoring case and accents; exit code 1 when nothing matches
onyx resolve "Stéphane" --folder entities --link   # [[Stéphane Charbonneau|Stéphane]], one line per match
onyx resolve "METC"                                # entities/businesses/Mousquetons et Cie

# By frontmatter (repeatable --where = AND): key=value, key!=value, key, !key
onyx list --folder projects --where type=project --where status=active
onyx list --where client=Symbolitech --where "status!=done" --json

--where values compare without case or accents, a [[link]] compares by its target, and a list matches when any item does. resolve --link uses a path link when the filename is shared by several notes.

Tasks

# Open and in-progress tasks of a week's daily notes, minus the template's recurring ones
onyx tasks --folder periodic/daily --from 2026-10-12 --to 2026-10-18 --status open,doing \
  --ignore-from resources/template/daily-note
onyx tasks --folder projects --status open --json    # path, line, date, status, heading, text

Statuses: - [ ] open, - [/] doing, - [x] done, - [-] cancelled. With --from/--to, a note's date is the YYYY-MM-DD at the start of its filename, else its date property; undated notes are skipped. Output is path:line: - [ ] text, like grep.

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
  • Sections: Append to or replace one section of a note
  • Queries: Resolve notes by name/alias, list notes by frontmatter, list tasks by date and status
  • Cross-Platform: Works on macOS, Windows, and Linux

Requirements

  • Python 3.9+ (only to run from source; the release binaries bundle Python)
  • click
  • pyyaml

Development

See RELEASING.md for the full version-bump/build/tag/release checklist.

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