372 lines
12 KiB
Markdown
372 lines
12 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 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"
|
|
```
|
|
|
|
`open`, `print-note`, `section` and `frontmatter` find a note by its exact
|
|
vault-relative path, otherwise by filename or `aliases` entry (case and accents
|
|
ignored; a filename beats an alias) or by a partial path such as
|
|
`people/Haro`. When several notes match, nothing is opened and the candidate
|
|
paths are listed; when none match, close filenames are suggested. There is no
|
|
fuzzy opening. `move` and `delete` still require the exact path.
|
|
|
|
### 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.9+ (only to run from source; the release binaries bundle Python)
|
|
- 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
|
|
```
|