# 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: ```bash 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`: ```bash chmod +x onyx mv onyx ~/.local/bin/onyx # or /usr/local/bin/onyx (needs sudo) ``` ## Installation 1. Clone this repository 2. Install dependencies: ```bash pip install -r requirements.txt ``` ## Quick Start Set up your default vault: ```bash onyx set-default "my-vault" --path "/path/to/vault" ``` Then use any command: ```bash onyx open "note-name" onyx daily onyx frontmatter "note-name" --view --key "tags" ``` ## Commands ### Vault Management ```bash # Set default vault (required first time) onyx set-default "vault-name" --path "/path/to/vault" # Print current default vault onyx print-default ``` ### Opening Notes ```bash # Open a note in Obsidian onyx open "note-name" # Open note from specific vault onyx open "note-name" --vault "vault-name" ``` ### Periodic Notes ```bash # 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: ```bash # 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](#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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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. ```bash # Delete from specific vault onyx delete "note-path" --vault "vault-name" ``` ### Frontmatter Management Edit note metadata in YAML frontmatter: ```bash # 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" ``` 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` takes a comma-separated list, written as a block list. Cleared keys become empty (`status:`), cleared tags `tags: []`. ### Version ```bash # 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 See [RELEASING.md](RELEASING.md) for the full version-bump/build/tag/release checklist. ### Running Tests ```bash # 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: ```yaml 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 ```