Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
d77fac61c8 | ||
|
|
466fef3c23 | ||
|
|
6eb27b7cd6 | ||
|
|
43c50a889d |
No files matched your search
@@ -2,16 +2,30 @@
|
|||||||
|
|
||||||
A Python-based command-line interface for interacting with Obsidian vaults. Manage notes directly from the terminal without opening Obsidian.
|
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)
|
## Building a Standalone Executable
|
||||||
|
|
||||||
You can build a standalone Windows executable using PyInstaller:
|
The same `onyx.spec` builds on both Windows and Linux — PyInstaller doesn't
|
||||||
|
cross-compile, so build natively on each platform:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
pip install pyinstaller
|
pip install pyinstaller
|
||||||
python -m PyInstaller onyx.spec
|
python -m PyInstaller onyx.spec
|
||||||
```
|
```
|
||||||
|
|
||||||
The resulting `onyx.exe` will be found in the `dist` folder.
|
- 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
|
## Installation
|
||||||
|
|
||||||
@@ -236,6 +250,8 @@ onyx --version
|
|||||||
|
|
||||||
## Development
|
## Development
|
||||||
|
|
||||||
|
See [RELEASING.md](RELEASING.md) for the full version-bump/build/tag/release checklist.
|
||||||
|
|
||||||
### Running Tests
|
### Running Tests
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
|||||||
+177
@@ -0,0 +1,177 @@
|
|||||||
|
# Release procedure
|
||||||
|
|
||||||
|
Onyx ships as two standalone binaries (Windows `.exe`, Linux ELF) attached to a
|
||||||
|
Gitea release — no PyPI package, no installer. This document is the checklist
|
||||||
|
for cutting a new version.
|
||||||
|
|
||||||
|
## 1. Land the change
|
||||||
|
|
||||||
|
Implement, then verify:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python -m pytest tests/ -q
|
||||||
|
```
|
||||||
|
|
||||||
|
All tests must pass (skips are fine) before bumping anything.
|
||||||
|
|
||||||
|
## 2. Bump the version
|
||||||
|
|
||||||
|
The version string lives in exactly one place: the `@click.version_option`
|
||||||
|
decorator on the `cli` group in `src/onyx.py`.
|
||||||
|
|
||||||
|
```python
|
||||||
|
@click.version_option(version='X.Y.Z', prog_name='onyx')
|
||||||
|
```
|
||||||
|
|
||||||
|
Use semver: patch for fixes only, minor for new commands/flags, major for
|
||||||
|
breaking changes (removed/renamed commands, changed config schema).
|
||||||
|
|
||||||
|
## 3. Build both platform binaries
|
||||||
|
|
||||||
|
PyInstaller does **not** cross-compile — each binary must be built natively
|
||||||
|
on its target platform.
|
||||||
|
|
||||||
|
**Windows** (run directly on this machine):
|
||||||
|
```bash
|
||||||
|
rm -rf build dist
|
||||||
|
python -m PyInstaller onyx.spec
|
||||||
|
# -> dist/onyx.exe
|
||||||
|
```
|
||||||
|
|
||||||
|
**Linux** (via WSL, since this machine is Windows): build on WSL's native
|
||||||
|
ext4 filesystem, not `/mnt/c/...` — PyInstaller/venvs are unreliable over
|
||||||
|
the drvfs 9p mount.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
wsl -d Ubuntu-24.04 -- bash -lc '
|
||||||
|
set -e
|
||||||
|
rm -rf ~/onyx-build && mkdir -p ~/onyx-build
|
||||||
|
cp -r "/mnt/c/Users/oli/Documents/o/Resources/repos/Onyx - obsidian cli tool/src" ~/onyx-build/
|
||||||
|
cp "/mnt/c/Users/oli/Documents/o/Resources/repos/Onyx - obsidian cli tool/onyx.spec" ~/onyx-build/
|
||||||
|
cp "/mnt/c/Users/oli/Documents/o/Resources/repos/Onyx - obsidian cli tool/requirements.txt" ~/onyx-build/
|
||||||
|
cd ~/onyx-build
|
||||||
|
python3 -m venv .venv
|
||||||
|
.venv/bin/pip install -q --upgrade pip
|
||||||
|
.venv/bin/pip install -q -r requirements.txt pyinstaller
|
||||||
|
rm -rf build dist
|
||||||
|
.venv/bin/pyinstaller onyx.spec
|
||||||
|
'
|
||||||
|
```
|
||||||
|
|
||||||
|
Copy the result out and rename it (Windows already produced `dist/onyx.exe`
|
||||||
|
in the same folder, and Linux's output has no extension — rename to avoid
|
||||||
|
any ambiguity):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
wsl -d Ubuntu-24.04 -- bash -lc "cp /home/oli/onyx-build/dist/onyx '/mnt/c/Users/oli/Documents/o/Resources/repos/Onyx - obsidian cli tool/dist/onyx-linux'"
|
||||||
|
```
|
||||||
|
|
||||||
|
> Passing multi-line scripts to `wsl.exe` through a shell tool can mangle
|
||||||
|
> line endings (CRLF) and silently break variable assignments. If a WSL
|
||||||
|
> command behaves inexplicably (e.g. `command not found` for something
|
||||||
|
> that should be a variable), write the script to a file and run that file
|
||||||
|
> instead of an inline heredoc.
|
||||||
|
|
||||||
|
## 4. Verify both binaries
|
||||||
|
|
||||||
|
```bash
|
||||||
|
dist/onyx.exe --version # Windows, via cmd.exe (see gotcha below)
|
||||||
|
wsl -d Ubuntu-24.04 -- ~/onyx-build/dist/onyx --version
|
||||||
|
```
|
||||||
|
|
||||||
|
Confirm the printed version matches step 2. Smoke-test at least one command
|
||||||
|
end to end (e.g. `periodic --view`, `weekly --date 2025-11-27`) against a
|
||||||
|
scratch vault/config — never against the real `~/.onyx-cli/config.yaml`.
|
||||||
|
|
||||||
|
> **Windows gotcha**: the plain bash tool can't execute a freshly built
|
||||||
|
> `.exe` directly (`command not found`) — always invoke it through
|
||||||
|
> `cmd.exe /c "onyx.exe ..."`.
|
||||||
|
|
||||||
|
## 5. Deploy locally (optional)
|
||||||
|
|
||||||
|
Copy the Windows build to the installed location so `onyx` on this machine
|
||||||
|
picks up the new version immediately:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp dist/onyx.exe "/c/Users/oli/Documents/o/Resources/app back up/bin/onyx.exe"
|
||||||
|
```
|
||||||
|
|
||||||
|
## 6. Commit, tag, push
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add -A
|
||||||
|
git commit -m "chore: bump to vX.Y.Z"
|
||||||
|
|
||||||
|
git fetch origin # someone may have committed via the Gitea web UI
|
||||||
|
git log --oneline origin/main -3
|
||||||
|
```
|
||||||
|
|
||||||
|
If `origin/main` has commits you don't have locally, **rebase, don't
|
||||||
|
merge** (this repo's history is linear):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git rebase origin/main
|
||||||
|
```
|
||||||
|
|
||||||
|
Then tag (annotated, with a real changelog since the last tag) and push:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git tag -a vX.Y.Z -m "vX.Y.Z
|
||||||
|
|
||||||
|
- ..."
|
||||||
|
git push origin main
|
||||||
|
git push origin vX.Y.Z
|
||||||
|
```
|
||||||
|
|
||||||
|
> If you rebased *after* creating the tag, the tag still points at the
|
||||||
|
> pre-rebase (now orphaned) commit. Delete and recreate it:
|
||||||
|
> `git tag -d vX.Y.Z && git tag -a vX.Y.Z -m "..."` before pushing.
|
||||||
|
|
||||||
|
## 7. Create the Gitea release
|
||||||
|
|
||||||
|
`tea` hangs indefinitely under a plain non-interactive shell call, for
|
||||||
|
*any* subcommand, including fully local ones. Always launch it as a
|
||||||
|
supervised process (hub `start`/`wait`/`logs`), never via the bash tool
|
||||||
|
directly.
|
||||||
|
|
||||||
|
Write release notes to a scratch file, then create the release with both
|
||||||
|
assets in one call:
|
||||||
|
|
||||||
|
```
|
||||||
|
tea releases create --repo olivier/onyx-cli --tag vX.Y.Z --title vX.Y.Z \
|
||||||
|
--note-file release-notes-vX.Y.Z.md -a dist/onyx.exe -a dist/onyx-linux
|
||||||
|
```
|
||||||
|
|
||||||
|
If the release already exists and you're adding a platform binary later
|
||||||
|
(e.g. the Linux build wasn't ready yet), attach it separately instead:
|
||||||
|
|
||||||
|
```
|
||||||
|
tea releases assets create --repo olivier/onyx-cli vX.Y.Z dist/<file>
|
||||||
|
```
|
||||||
|
|
||||||
|
Delete the scratch release-notes file afterward — it's not a repo
|
||||||
|
convention file.
|
||||||
|
|
||||||
|
> `tea repos create --owner olivier` fails with `GetOrgByName` — `--owner`
|
||||||
|
> targets an organization, not your personal account. Omit it entirely
|
||||||
|
> when creating a repo under your own user.
|
||||||
|
|
||||||
|
## 8. Verify the release
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -s https://gitea.mithrilforge.dev/api/v1/repos/olivier/onyx-cli/releases/tags/vX.Y.Z \
|
||||||
|
| python -c "import json,sys; d=json.load(sys.stdin); [print(a['name'], a['size']) for a in d['assets']]"
|
||||||
|
```
|
||||||
|
|
||||||
|
Confirm both `onyx.exe` and `onyx-linux` are listed with nonzero, distinct
|
||||||
|
sizes.
|
||||||
|
|
||||||
|
## 9. Clean up
|
||||||
|
|
||||||
|
```bash
|
||||||
|
wsl -d Ubuntu-24.04 -- bash -lc "rm -rf ~/onyx-build"
|
||||||
|
rm -f release-notes-vX.Y.Z.md
|
||||||
|
```
|
||||||
|
|
||||||
|
`dist/` and `build/` are gitignored — the binaries never get committed,
|
||||||
|
only attached to the release.
|
||||||
@@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
|
|
||||||
a = Analysis(
|
a = Analysis(
|
||||||
['src\\onyx.py'],
|
['src/onyx.py'],
|
||||||
pathex=[],
|
pathex=[],
|
||||||
binaries=[],
|
binaries=[],
|
||||||
datas=[],
|
datas=[],
|
||||||
|
|||||||
+22
-11
@@ -12,6 +12,18 @@ import re
|
|||||||
from typing import List, Union, Optional, Dict, Any
|
from typing import List, Union, Optional, Dict, Any
|
||||||
from urllib.parse import quote
|
from urllib.parse import quote
|
||||||
|
|
||||||
|
|
||||||
|
def _write_text(path: Path, text: str, mode: str = 'w') -> None:
|
||||||
|
"""Write UTF-8 without BOM and with LF line endings on every OS.
|
||||||
|
|
||||||
|
Python's text mode would otherwise translate '\\n' to os.linesep (CRLF on
|
||||||
|
Windows), and 'utf-8-sig' would prepend a BOM before the frontmatter.
|
||||||
|
Reads keep 'utf-8-sig' so files that already carry a BOM still parse.
|
||||||
|
"""
|
||||||
|
with path.open(mode, encoding='utf-8', newline='\n') as f:
|
||||||
|
f.write(text)
|
||||||
|
|
||||||
|
|
||||||
class OnyxCLI:
|
class OnyxCLI:
|
||||||
_PERIODIC_DEFAULTS: Dict[str, Dict[str, str]] = {
|
_PERIODIC_DEFAULTS: Dict[str, Dict[str, str]] = {
|
||||||
'daily': {'format': 'YYYY-MM-DD', 'folder': '', 'template': ''},
|
'daily': {'format': 'YYYY-MM-DD', 'folder': '', 'template': ''},
|
||||||
@@ -37,7 +49,7 @@ class OnyxCLI:
|
|||||||
def _ensure_config_exists(self):
|
def _ensure_config_exists(self):
|
||||||
self.config_file.parent.mkdir(parents=True, exist_ok=True)
|
self.config_file.parent.mkdir(parents=True, exist_ok=True)
|
||||||
if not self.config_file.exists():
|
if not self.config_file.exists():
|
||||||
self.config_file.write_text(yaml.dump({'default_vault': None, 'vaults': {}}), encoding='utf-8-sig')
|
_write_text(self.config_file, yaml.dump({'default_vault': None, 'vaults': {}}))
|
||||||
|
|
||||||
def _load_default_vault(self):
|
def _load_default_vault(self):
|
||||||
if self.config_file.exists():
|
if self.config_file.exists():
|
||||||
@@ -117,7 +129,7 @@ class OnyxCLI:
|
|||||||
config['vaults'][vault_name] = vault_config
|
config['vaults'][vault_name] = vault_config
|
||||||
|
|
||||||
# Write updated config
|
# Write updated config
|
||||||
self.config_file.write_text(yaml.dump(config, default_flow_style=False), encoding='utf-8-sig')
|
_write_text(self.config_file, yaml.dump(config, default_flow_style=False))
|
||||||
|
|
||||||
# Update instance variables
|
# Update instance variables
|
||||||
self.default_vault = vault_name
|
self.default_vault = vault_name
|
||||||
@@ -209,10 +221,9 @@ class OnyxCLI:
|
|||||||
else:
|
else:
|
||||||
mode = 'w'
|
mode = 'w'
|
||||||
|
|
||||||
with note_path.open(mode, encoding='utf-8-sig') as f:
|
if mode == 'a':
|
||||||
if append and note_path.exists():
|
content = '\n' + content
|
||||||
f.write('\n')
|
_write_text(note_path, content, mode)
|
||||||
f.write(content)
|
|
||||||
|
|
||||||
click.echo(f"Note {'updated' if note_path.exists() else 'created'}: {note_path}")
|
click.echo(f"Note {'updated' if note_path.exists() else 'created'}: {note_path}")
|
||||||
|
|
||||||
@@ -485,7 +496,7 @@ class OnyxCLI:
|
|||||||
content = md_file.read_text(encoding='utf-8-sig')
|
content = md_file.read_text(encoding='utf-8-sig')
|
||||||
updated_content = re.sub(old_link_pattern, new_link, content)
|
updated_content = re.sub(old_link_pattern, new_link, content)
|
||||||
if updated_content != content:
|
if updated_content != content:
|
||||||
md_file.write_text(updated_content, encoding='utf-8-sig')
|
_write_text(md_file, updated_content)
|
||||||
|
|
||||||
click.echo(f"Moved {current_path} to {new_path}")
|
click.echo(f"Moved {current_path} to {new_path}")
|
||||||
|
|
||||||
@@ -529,7 +540,7 @@ class OnyxCLI:
|
|||||||
new_content += '---\n'
|
new_content += '---\n'
|
||||||
new_content += rest_content if fm_length else content
|
new_content += rest_content if fm_length else content
|
||||||
|
|
||||||
note_path.write_text(new_content, encoding='utf-8-sig')
|
_write_text(note_path, new_content)
|
||||||
|
|
||||||
def frontmatter_edit(self, note_name: str, keys: tuple, values: tuple = None, vault: str = None):
|
def frontmatter_edit(self, note_name: str, keys: tuple, values: tuple = None, vault: str = None):
|
||||||
vault_name, vault_path = self._get_vault_and_path(vault)
|
vault_name, vault_path = self._get_vault_and_path(vault)
|
||||||
@@ -711,7 +722,7 @@ class OnyxCLI:
|
|||||||
else:
|
else:
|
||||||
new_content = rest_content
|
new_content = rest_content
|
||||||
|
|
||||||
note_path.write_text(new_content, encoding='utf-8-sig')
|
_write_text(note_path, new_content)
|
||||||
click.echo(f"Deleted frontmatter keys from {note_name}")
|
click.echo(f"Deleted frontmatter keys from {note_name}")
|
||||||
else:
|
else:
|
||||||
click.echo("No matching keys found in frontmatter")
|
click.echo("No matching keys found in frontmatter")
|
||||||
@@ -837,7 +848,7 @@ class OnyxCLI:
|
|||||||
|
|
||||||
vaults[vault_name] = vault_entry
|
vaults[vault_name] = vault_entry
|
||||||
config['vaults'] = vaults
|
config['vaults'] = vaults
|
||||||
self.config_file.write_text(yaml.dump(config, default_flow_style=False), encoding='utf-8-sig')
|
_write_text(self.config_file, yaml.dump(config, default_flow_style=False))
|
||||||
click.echo(f"Updated {note_type} note settings for vault '{vault_name}'")
|
click.echo(f"Updated {note_type} note settings for vault '{vault_name}'")
|
||||||
|
|
||||||
def print_periodic_config(self, note_type: str, vault: str = None):
|
def print_periodic_config(self, note_type: str, vault: str = None):
|
||||||
@@ -851,7 +862,7 @@ class OnyxCLI:
|
|||||||
|
|
||||||
# CLI Commands
|
# CLI Commands
|
||||||
|
|
||||||
@click.version_option(version='0.1.0', prog_name='onyx')
|
@click.version_option(version='0.1.1', prog_name='onyx')
|
||||||
@click.group(name='onyx')
|
@click.group(name='onyx')
|
||||||
def cli():
|
def cli():
|
||||||
"""Onyx - Interact with Obsidian vaults from the command line
|
"""Onyx - Interact with Obsidian vaults from the command line
|
||||||
|
|||||||
@@ -51,6 +51,20 @@ class TestOnyxCLI(unittest.TestCase):
|
|||||||
note_path = self.test_dir / 'test.md'
|
note_path = self.test_dir / 'test.md'
|
||||||
self.assertTrue(note_path.exists())
|
self.assertTrue(note_path.exists())
|
||||||
|
|
||||||
|
def test_writes_keep_lf_without_bom(self):
|
||||||
|
"""Append and frontmatter edits write LF, no BOM, even on Windows"""
|
||||||
|
note_path = self.test_dir / 'lf.md'
|
||||||
|
note_path.write_bytes(b'---\nstatus: draft\n---\n# Journal\n')
|
||||||
|
|
||||||
|
self.cli.create_note('lf.md', '### 10:00 - Entry\nline', append=True)
|
||||||
|
self.cli.frontmatter_edit('lf', ('status',), ('done',))
|
||||||
|
|
||||||
|
data = note_path.read_bytes()
|
||||||
|
self.assertNotIn(b'\r', data)
|
||||||
|
self.assertFalse(data.startswith(b'\xef\xbb\xbf'))
|
||||||
|
self.assertIn(b'status: done', data)
|
||||||
|
self.assertTrue(data.endswith(b'# Journal\n\n### 10:00 - Entry\nline'))
|
||||||
|
|
||||||
@unittest.skip("Method export_to_csv not implemented")
|
@unittest.skip("Method export_to_csv not implemented")
|
||||||
def test_export_to_csv(self):
|
def test_export_to_csv(self):
|
||||||
"""Test exporting note frontmatter to CSV"""
|
"""Test exporting note frontmatter to CSV"""
|
||||||
|
|||||||
Reference in new issue
Block a user