203 lines
4.2 KiB
Markdown
203 lines
4.2 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
|
|
```
|
|
|
|
### 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
|