odcli 0.1.5__tar.gz → 0.1.7__tar.gz

{odcli-0.1.5 → odcli-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: odcli
-Version: 0.1.5
+Version: 0.1.7
 Summary: A small CLI for reading and writing notes in a local Obsidian vault.
 Author: odcli contributors
 Keywords: obsidian,cli,markdown,notes,vault
@@ -18,68 +18,160 @@ Description-Content-Type: text/markdown
 
 # odcli
 
-`odcli` is a local Python CLI for reading and writing notes in an Obsidian vault.
-It works directly on Markdown files inside the vault, so it does not depend on private Obsidian APIs and remains portable and easy to extend.
+`odcli` is a command-line tool for reading and writing notes in a local Obsidian vault.
 
-## Features
+It works directly on Markdown files inside the vault, so you can use it without any private Obsidian API.
 
-- Validate whether a vault path is available
-- List Markdown notes in the vault
-- Read a specific note
-- Read a specific line range from a note
-- Overwrite a note or create it automatically
-- Replace a specific line range in a note
-- Append content to a note
-- Full-text search across the vault
-- Auto-discover the default vault from Obsidian config or common macOS and Windows locations
-- Install odcli helper skills into Codex or Claude Code skill directories
+## Install
 
-## Using uv
+From PyPI:
 
 ```bash
-cd path/to/obsidian_cli
-uv sync
-uv run odcli --help
+pip install odcli
 ```
 
-Run tests:
+Or with `uv`:
 
 ```bash
-cd path/to/obsidian_cli
-uv run python -m unittest discover -s tests
+uv tool install odcli
 ```
 
-Build distributions:
+After installation, both command names are available:
 
 ```bash
-cd path/to/obsidian_cli
-uv build
+odcli --help
+obsidian-cli --help
 ```
 
-The published package name on PyPI is `odcli`.
-After installation, both `odcli` and `obsidian-cli` are available as command names.
+## Quickstart
 
-## Run Locally
+If your vault is already in a common location, `odcli` can usually find it automatically:
 
 ```bash
-cd path/to/obsidian_cli
-./odcli --help
+odcli check
+odcli list
 ```
 
-The compatibility entry point is still available:
+If you want to set the vault explicitly:
 
 ```bash
-cd path/to/obsidian_cli
-./obsidian-cli --help
+export OBSIDIAN_VAULT="/path/to/MyVault"
+odcli check
+```
+
+You can also override the vault per command:
+
+```bash
+odcli --vault "/path/to/MyVault" list
+```
+
+## Remote Vault over SSH
+
+You can operate on an Obsidian vault stored on another machine over SSH.
+
+Example:
+
+```bash
+odcli \
+  --ssh-host your-server \
+  --ssh-user your-user \
+  --vault /path/to/ObsidianVault \
+  list
+```
+
+Read a remote note:
+
+```bash
+odcli \
+  --ssh-host your-server \
+  --ssh-user your-user \
+  --vault /path/to/ObsidianVault \
+  read Inbox/today.md
+```
+
+Write a remote note:
+
+```bash
+odcli \
+  --ssh-host your-server \
+  --ssh-user your-user \
+  --vault /path/to/ObsidianVault \
+  write Inbox/today.md --content "# Remote note"
+```
+
+Optional SSH flags:
+
+- `--ssh-port`
+- `--ssh-identity`
+
+In SSH mode, `--vault` or `OBSIDIAN_VAULT` should point to the remote vault path.
+
+## Common Commands
+
+Read a note:
+
+```bash
+odcli read Inbox/today.md
+```
+
+Read specific lines:
+
+```bash
+odcli read-lines Inbox/today.md 3 8
+```
+
+Create or overwrite a note:
+
+```bash
+odcli write Inbox/today.md --content "# Today"
 ```
 
-If you prefer module execution:
+Replace a line range:
 
 ```bash
-PYTHONPATH=src python3 -m obsidian_cli --help
+odcli write-lines Inbox/today.md 3 4 --content "- replaced\n- lines\n"
 ```
 
-## Vault Resolution
+Append content:
+
+```bash
+odcli append Inbox/today.md --content "\n- new item"
+```
+
+Search across the vault:
+
+```bash
+odcli search "project alpha"
+```
+
+## Skill Install
+
+`odcli` can install helper skills for local coding tools.
+
+Install into Codex:
+
+```bash
+odcli plugin install codex-skill
+```
+
+Install into Claude Code:
+
+```bash
+odcli plugin install claude-skill
+```
+
+Install both:
+
+```bash
+odcli plugin install all-skills
+```
+
+Installed paths:
+
+- Codex: `~/.codex/skills/odcli/SKILL.md`
+- Claude Code: `~/.claude/skills/odcli/SKILL.md`
+
+## Vault Discovery
 
 Resolution priority:
 
@@ -96,21 +188,7 @@ Built-in default locations:
 - Windows: `%USERPROFILE%\\Documents\\Obsidian Vault`
 - Windows: `%USERPROFILE%\\Documents\\Obsidian`
 
-Example:
-
-```bash
-export OBSIDIAN_VAULT="/path/to/MyVault"
-./odcli check
-./odcli list
-./odcli read Inbox/today.md
-./odcli read-lines Inbox/today.md 3 8
-./odcli write Inbox/today.md --content "# Today"
-./odcli write-lines Inbox/today.md 3 4 --content "- replaced\n- lines\n"
-./odcli append Inbox/today.md --content "\n- new item"
-./odcli search "project alpha"
-```
-
-## Commands
+## Command Summary
 
 ### `check`
 
@@ -187,27 +265,34 @@ Arguments:
 - `query`
 - `--case-sensitive`
 
-### `plugin install`
-
-Install odcli helper skills for local coding tools.
+## Global Options
 
-Targets:
+- `--vault`
+- `--ssh-host`
+- `--ssh-user`
+- `--ssh-port`
+- `--ssh-identity`
 
-- `codex-skill`: installs to `~/.codex/skills/odcli/SKILL.md`
-- `claude-skill`: installs to `~/.claude/skills/odcli/SKILL.md`
-- `all-skills`: installs both
+## For Developers
 
-Examples:
+Run from source:
 
 ```bash
-odcli plugin install codex-skill
-odcli plugin install claude-skill
-odcli plugin install all-skills
+cd path/to/obsidian_cli
+uv sync
+uv run odcli --help
 ```
 
-## Testing
+Run tests:
 
 ```bash
 cd path/to/obsidian_cli
 uv run python -m unittest discover -s tests
 ```
+
+Build distributions:
+
+```bash
+cd path/to/obsidian_cli
+uv build
+```

odcli-0.1.7/README.md

@@ -0,0 +1,280 @@
+# odcli
+
+`odcli` is a command-line tool for reading and writing notes in a local Obsidian vault.
+
+It works directly on Markdown files inside the vault, so you can use it without any private Obsidian API.
+
+## Install
+
+From PyPI:
+
+```bash
+pip install odcli
+```
+
+Or with `uv`:
+
+```bash
+uv tool install odcli
+```
+
+After installation, both command names are available:
+
+```bash
+odcli --help
+obsidian-cli --help
+```
+
+## Quickstart
+
+If your vault is already in a common location, `odcli` can usually find it automatically:
+
+```bash
+odcli check
+odcli list
+```
+
+If you want to set the vault explicitly:
+
+```bash
+export OBSIDIAN_VAULT="/path/to/MyVault"
+odcli check
+```
+
+You can also override the vault per command:
+
+```bash
+odcli --vault "/path/to/MyVault" list
+```
+
+## Remote Vault over SSH
+
+You can operate on an Obsidian vault stored on another machine over SSH.
+
+Example:
+
+```bash
+odcli \
+  --ssh-host your-server \
+  --ssh-user your-user \
+  --vault /path/to/ObsidianVault \
+  list
+```
+
+Read a remote note:
+
+```bash
+odcli \
+  --ssh-host your-server \
+  --ssh-user your-user \
+  --vault /path/to/ObsidianVault \
+  read Inbox/today.md
+```
+
+Write a remote note:
+
+```bash
+odcli \
+  --ssh-host your-server \
+  --ssh-user your-user \
+  --vault /path/to/ObsidianVault \
+  write Inbox/today.md --content "# Remote note"
+```
+
+Optional SSH flags:
+
+- `--ssh-port`
+- `--ssh-identity`
+
+In SSH mode, `--vault` or `OBSIDIAN_VAULT` should point to the remote vault path.
+
+## Common Commands
+
+Read a note:
+
+```bash
+odcli read Inbox/today.md
+```
+
+Read specific lines:
+
+```bash
+odcli read-lines Inbox/today.md 3 8
+```
+
+Create or overwrite a note:
+
+```bash
+odcli write Inbox/today.md --content "# Today"
+```
+
+Replace a line range:
+
+```bash
+odcli write-lines Inbox/today.md 3 4 --content "- replaced\n- lines\n"
+```
+
+Append content:
+
+```bash
+odcli append Inbox/today.md --content "\n- new item"
+```
+
+Search across the vault:
+
+```bash
+odcli search "project alpha"
+```
+
+## Skill Install
+
+`odcli` can install helper skills for local coding tools.
+
+Install into Codex:
+
+```bash
+odcli plugin install codex-skill
+```
+
+Install into Claude Code:
+
+```bash
+odcli plugin install claude-skill
+```
+
+Install both:
+
+```bash
+odcli plugin install all-skills
+```
+
+Installed paths:
+
+- Codex: `~/.codex/skills/odcli/SKILL.md`
+- Claude Code: `~/.claude/skills/odcli/SKILL.md`
+
+## Vault Discovery
+
+Resolution priority:
+
+1. `--vault /path/to/vault`
+2. `OBSIDIAN_VAULT`
+3. The most recently opened vault recorded by local Obsidian config
+4. Common default directories
+
+Built-in default locations:
+
+- macOS: `~/Documents/Obsidian Vault`
+- macOS: `~/Documents/Obsidian`
+- macOS iCloud: `~/Library/Mobile Documents/iCloud~md~obsidian/Documents`
+- Windows: `%USERPROFILE%\\Documents\\Obsidian Vault`
+- Windows: `%USERPROFILE%\\Documents\\Obsidian`
+
+## Command Summary
+
+### `check`
+
+Validate that the vault exists and report whether `.obsidian` is present.
+
+### `list`
+
+List Markdown notes in the vault.
+
+Optional arguments:
+
+- `--limit N`
+
+### `read`
+
+Read a note.
+
+Arguments:
+
+- `note_path`: path relative to the vault root
+
+### `write`
+
+Overwrite a note. Parent directories are created automatically if needed.
+
+Arguments:
+
+- `note_path`
+- `--content TEXT`
+- `--stdin`
+
+Optional arguments:
+
+- `--create-only`
+
+### `read-lines`
+
+Read a line range. Line numbers are 1-based and inclusive.
+
+Arguments:
+
+- `note_path`
+- `start_line`
+- `end_line`
+
+### `write-lines`
+
+Replace a line range. Line numbers are 1-based and inclusive.
+
+Arguments:
+
+- `note_path`
+- `start_line`
+- `end_line`
+- `--content TEXT`
+- `--stdin`
+
+### `append`
+
+Append content to the end of a note.
+
+Arguments:
+
+- `note_path`
+- `--content TEXT`
+- `--stdin`
+
+### `search`
+
+Search across all Markdown notes in the vault.
+
+Arguments:
+
+- `query`
+- `--case-sensitive`
+
+## Global Options
+
+- `--vault`
+- `--ssh-host`
+- `--ssh-user`
+- `--ssh-port`
+- `--ssh-identity`
+
+## For Developers
+
+Run from source:
+
+```bash
+cd path/to/obsidian_cli
+uv sync
+uv run odcli --help
+```
+
+Run tests:
+
+```bash
+cd path/to/obsidian_cli
+uv run python -m unittest discover -s tests
+```
+
+Build distributions:
+
+```bash
+cd path/to/obsidian_cli
+uv build
+```

{odcli-0.1.5 → odcli-0.1.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "odcli"
-version = "0.1.5"
+version = "0.1.7"
 description = "A small CLI for reading and writing notes in a local Obsidian vault."
 readme = "README.md"
 requires-python = ">=3.11"

{odcli-0.1.5 → odcli-0.1.7}/src/obsidian_cli/__init__.py

@@ -1,3 +1,3 @@
 __all__ = ["__version__"]
 
-__version__ = "0.1.5"
+__version__ = "0.1.7"

{odcli-0.1.5 → odcli-0.1.7}/src/obsidian_cli/cli.py

@@ -6,7 +6,13 @@ import sys
 from obsidian_cli.commands import CommandRunner
 from obsidian_cli.discovery import VaultLocator
 from obsidian_cli.plugins import SkillInstaller
-from obsidian_cli.vault import ObsidianVault, VaultError
+from obsidian_cli.vault import (
+    ObsidianVault,
+    SshConfig,
+    SshObsidianVault,
+    VaultBackend,
+    VaultError,
+)
 
 
 class ObsidianCLI:
@@ -22,9 +28,7 @@ class ObsidianCLI:
             if args.command == "plugin":
                 return self._run_plugin_command(args)
 
-            runner = CommandRunner(
-                ObsidianVault(self._vault_locator.resolve(args.vault))
-            )
+            runner = CommandRunner(self._build_vault(args))
 
             if args.command == "check":
                 return runner.check()
@@ -72,6 +76,13 @@ class ObsidianCLI:
             "--vault",
             help="Path to the Obsidian vault. Falls back to OBSIDIAN_VAULT.",
         )
+        parser.add_argument("--ssh-host", help="SSH host for a remote vault.")
+        parser.add_argument("--ssh-user", help="SSH username for a remote vault.")
+        parser.add_argument("--ssh-port", type=int, help="SSH port for a remote vault.")
+        parser.add_argument(
+            "--ssh-identity",
+            help="SSH identity file used when connecting to a remote vault.",
+        )
 
         subparsers = parser.add_subparsers(dest="command", required=True)
         subparsers.add_parser("check", help="Validate the vault path.")
@@ -175,6 +186,20 @@ class ObsidianCLI:
         self._parser.error(f"unsupported plugin command: {args.plugin_command}")
         return 2
 
+    def _build_vault(self, args: argparse.Namespace) -> VaultBackend:
+        if args.ssh_host:
+            ssh_root = self._vault_locator.resolve_configured(args.vault)
+            return SshObsidianVault(
+                str(ssh_root),
+                SshConfig(
+                    host=args.ssh_host,
+                    user=args.ssh_user,
+                    port=args.ssh_port,
+                    identity_file=args.ssh_identity,
+                ),
+            )
+        return ObsidianVault(self._vault_locator.resolve(args.vault))
+
     @staticmethod
     def _read_content_arg(content: str | None, use_stdin: bool) -> str:
         if content is not None and use_stdin:

{odcli-0.1.5 → odcli-0.1.7}/src/obsidian_cli/commands.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
-from obsidian_cli.vault import ObsidianVault, VaultError
+from obsidian_cli.vault import VaultBackend, VaultError
 
 
 class CommandRunner:
-    def __init__(self, vault: ObsidianVault) -> None:
+    def __init__(self, vault: VaultBackend) -> None:
         self._vault = vault
 
     def check(self) -> int:

{odcli-0.1.5 → odcli-0.1.7}/src/obsidian_cli/discovery.py

@@ -18,7 +18,7 @@ class VaultLocator:
     def __init__(
         self, env: dict[str, str] | None = None, home: Path | None = None
     ) -> None:
-        self._env = dict(env or os.environ)
+        self._env = dict(os.environ if env is None else env)
         self._home = (home or Path.home()).expanduser()
 
     def resolve(self, cli_value: str | None) -> Path:
@@ -38,6 +38,19 @@ class VaultLocator:
             "vault path is required; use --vault, OBSIDIAN_VAULT, or place your vault in a default Obsidian location"
         )
 
+    def resolve_configured(self, cli_value: str | None) -> Path:
+        cli_path = self._path_from_string(cli_value)
+        if cli_path is not None:
+            return cli_path
+
+        env_path = self._path_from_string(self._env.get("OBSIDIAN_VAULT"))
+        if env_path is not None:
+            return env_path
+
+        raise VaultError(
+            "vault path is required for SSH mode; use --vault or OBSIDIAN_VAULT"
+        )
+
     def discover_default_vault(self) -> VaultCandidate | None:
         config_candidate = self._discover_from_obsidian_config()
         if config_candidate is not None:

{odcli-0.1.5 → odcli-0.1.7}/src/obsidian_cli/plugins.py

@@ -4,7 +4,12 @@ from dataclasses import dataclass
 from pathlib import Path
 
 
-SKILL_BODY = """# odcli
+SKILL_BODY = """---
+name: "odcli"
+description: "Use odcli to read, write, append, search, and patch notes inside a local Obsidian vault."
+---
+
+# odcli
 
 Use `odcli` when you need to read or write notes inside a local Obsidian vault.