# 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: ```bash 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: ```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 ``` **Filename formats:** - 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` The correct filename is always generated automatically, regardless of your plugin settings. ### 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 (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: ```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" ``` ### 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 ### 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: ```yaml default_vault: my-vault vaults: my-vault: /path/to/vault work: /path/to/work/vault ```