# 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" # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```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 - **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.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 ```