Files
onyx-cli/README.md
T
olivier 0dddb57d76 Add per-vault periodic notes config, fix version/print-default bugs, stop tracking build artifacts
- onyx periodic --view/--edit: configure folder/format/template per note type,
  independent of Obsidian's Daily Notes / Periodic Notes plugin state
- fix: weekly/monthly/quarterly/yearly notes no longer silently inherit the
  daily note's folder/template when no plugin config exists
- fix: quarterly notes now resolve the real quarter number instead of a
  literal 'Q'
- fix: onyx --version now works at the root command group; remove the
  redundant no-op 'version' subcommand
- fix: print-default no longer dumps the raw vault config dict for
  long-form vault entries
- expand --help text across periodic/create/set-default commands
- add .gitignore; stop tracking build/, dist/, __pycache__/, .idea/, .vscode/
2026-09-24 17:11:43 -04:00

271 lines
7.0 KiB
Markdown

# 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
```
**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 (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, 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
```