odcli 0.1.0__tar.gz → 0.1.3__tar.gz

odcli-0.1.3/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: odcli
+Version: 0.1.3
+Summary: A small CLI for reading and writing notes in a local Obsidian vault.
+Author: Chang LeHung
+Project-URL: Homepage, https://github.com/Chang-LeHung/obsidian-cli
+Project-URL: Repository, https://github.com/Chang-LeHung/obsidian-cli
+Project-URL: Issues, https://github.com/Chang-LeHung/obsidian-cli/issues
+Keywords: obsidian,cli,markdown,notes,vault
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Classifier: Environment :: Console
+Requires-Python: >=3.11
+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.
+
+## Features
+
+- 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
+
+## Using uv
+
+```bash
+cd /Users/huchang/agents/obsidian_cli
+uv sync
+uv run odcli --help
+```
+
+Run tests:
+
+```bash
+cd /Users/huchang/agents/obsidian_cli
+uv run python -m unittest discover -s tests
+```
+
+Build distributions:
+
+```bash
+cd /Users/huchang/agents/obsidian_cli
+uv build
+```
+
+The published package name on PyPI is `odcli`.
+After installation, both `odcli` and `obsidian-cli` are available as command names.
+
+## Run Locally
+
+```bash
+cd /Users/huchang/agents/obsidian_cli
+./odcli --help
+```
+
+The compatibility entry point is still available:
+
+```bash
+cd /Users/huchang/agents/obsidian_cli
+./obsidian-cli --help
+```
+
+If you prefer module execution:
+
+```bash
+PYTHONPATH=src python3 -m obsidian_cli --help
+```
+
+## Vault Resolution
+
+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`
+
+Example:
+
+```bash
+export OBSIDIAN_VAULT="/Users/your-name/Documents/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
+
+### `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`
+
+## Testing
+
+```bash
+cd /Users/huchang/agents/obsidian_cli
+uv run python -m unittest discover -s tests
+```

odcli-0.1.3/README.md

@@ -0,0 +1,176 @@
+# 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.
+
+## Features
+
+- 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
+
+## Using uv
+
+```bash
+cd /Users/huchang/agents/obsidian_cli
+uv sync
+uv run odcli --help
+```
+
+Run tests:
+
+```bash
+cd /Users/huchang/agents/obsidian_cli
+uv run python -m unittest discover -s tests
+```
+
+Build distributions:
+
+```bash
+cd /Users/huchang/agents/obsidian_cli
+uv build
+```
+
+The published package name on PyPI is `odcli`.
+After installation, both `odcli` and `obsidian-cli` are available as command names.
+
+## Run Locally
+
+```bash
+cd /Users/huchang/agents/obsidian_cli
+./odcli --help
+```
+
+The compatibility entry point is still available:
+
+```bash
+cd /Users/huchang/agents/obsidian_cli
+./obsidian-cli --help
+```
+
+If you prefer module execution:
+
+```bash
+PYTHONPATH=src python3 -m obsidian_cli --help
+```
+
+## Vault Resolution
+
+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`
+
+Example:
+
+```bash
+export OBSIDIAN_VAULT="/Users/your-name/Documents/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
+
+### `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`
+
+## Testing
+
+```bash
+cd /Users/huchang/agents/obsidian_cli
+uv run python -m unittest discover -s tests
+```

{odcli-0.1.0 → odcli-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "odcli"
-version = "0.1.0"
+version = "0.1.3"
 description = "A small CLI for reading and writing notes in a local Obsidian vault."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -17,6 +17,7 @@ classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",
   "Operating System :: MacOS",
+  "Operating System :: Microsoft :: Windows",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
@@ -30,11 +31,13 @@ Repository = "https://github.com/Chang-LeHung/obsidian-cli"
 Issues = "https://github.com/Chang-LeHung/obsidian-cli/issues"
 
 [project.scripts]
+odcli = "obsidian_cli.cli:main"
 obsidian-cli = "obsidian_cli.cli:main"
 
 [dependency-groups]
 dev = [
   "build>=1.2.2",
+  "ruff>=0.14.0",
   "twine>=6.1.0",
 ]
 

{odcli-0.1.0 → odcli-0.1.3}/src/obsidian_cli/__init__.py

@@ -1,4 +1,3 @@
 __all__ = ["__version__"]
 
-__version__ = "0.1.0"
-
+__version__ = "0.1.3"

{odcli-0.1.0 → odcli-0.1.3}/src/obsidian_cli/__main__.py

@@ -3,4 +3,3 @@ from obsidian_cli.cli import main
 
 if __name__ == "__main__":
     raise SystemExit(main())
-

odcli-0.1.3/src/obsidian_cli/cli.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from obsidian_cli.commands import CommandRunner
+from obsidian_cli.discovery import VaultLocator
+from obsidian_cli.vault import ObsidianVault, VaultError
+
+
+class ObsidianCLI:
+    def __init__(self, vault_locator: VaultLocator | None = None) -> None:
+        self._vault_locator = vault_locator or VaultLocator()
+        self._parser = self._build_parser()
+
+    def run(self, argv: list[str] | None = None) -> int:
+        args = self._parser.parse_args(argv)
+
+        try:
+            runner = CommandRunner(
+                ObsidianVault(self._vault_locator.resolve(args.vault))
+            )
+
+            if args.command == "check":
+                return runner.check()
+            if args.command == "list":
+                return runner.list_notes(args.limit)
+            if args.command == "read":
+                return runner.read_note(args.note_path)
+            if args.command == "read-lines":
+                return runner.read_note_lines(
+                    args.note_path, args.start_line, args.end_line
+                )
+            if args.command == "write":
+                return runner.write_note(
+                    args.note_path,
+                    self._read_content_arg(args.content, args.stdin),
+                    args.create_only,
+                )
+            if args.command == "append":
+                return runner.append_note(
+                    args.note_path,
+                    self._read_content_arg(args.content, args.stdin),
+                )
+            if args.command == "write-lines":
+                return runner.write_note_lines(
+                    args.note_path,
+                    args.start_line,
+                    args.end_line,
+                    self._read_content_arg(args.content, args.stdin),
+                )
+            if args.command == "search":
+                return runner.search(args.query, args.case_sensitive)
+        except VaultError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+
+        self._parser.error(f"unsupported command: {args.command}")
+        return 2
+
+    def _build_parser(self) -> argparse.ArgumentParser:
+        parser = argparse.ArgumentParser(
+            prog="obsidian-cli",
+            description="Read and write notes inside a local Obsidian vault.",
+        )
+        parser.add_argument(
+            "--vault",
+            help="Path to the Obsidian vault. Falls back to OBSIDIAN_VAULT.",
+        )
+
+        subparsers = parser.add_subparsers(dest="command", required=True)
+        subparsers.add_parser("check", help="Validate the vault path.")
+
+        list_parser = subparsers.add_parser("list", help="List markdown notes.")
+        list_parser.add_argument(
+            "--limit", type=int, default=0, help="Maximum number of notes to show."
+        )
+
+        read_parser = subparsers.add_parser("read", help="Read a note.")
+        read_parser.add_argument(
+            "note_path", help="Path to the note relative to the vault root."
+        )
+
+        read_lines_parser = subparsers.add_parser(
+            "read-lines", help="Read a line range from a note."
+        )
+        read_lines_parser.add_argument(
+            "note_path", help="Path to the note relative to the vault root."
+        )
+        read_lines_parser.add_argument(
+            "start_line", type=int, help="1-based start line, inclusive."
+        )
+        read_lines_parser.add_argument(
+            "end_line", type=int, help="1-based end line, inclusive."
+        )
+
+        write_parser = subparsers.add_parser("write", help="Write a note.")
+        write_parser.add_argument(
+            "note_path", help="Path to the note relative to the vault root."
+        )
+        write_parser.add_argument("--content", help="Text content to write.")
+        write_parser.add_argument(
+            "--stdin", action="store_true", help="Read note content from stdin."
+        )
+        write_parser.add_argument(
+            "--create-only",
+            action="store_true",
+            help="Fail if the note already exists.",
+        )
+
+        append_parser = subparsers.add_parser("append", help="Append to a note.")
+        append_parser.add_argument(
+            "note_path", help="Path to the note relative to the vault root."
+        )
+        append_parser.add_argument("--content", help="Text content to append.")
+        append_parser.add_argument(
+            "--stdin", action="store_true", help="Read appended content from stdin."
+        )
+
+        write_lines_parser = subparsers.add_parser(
+            "write-lines",
+            help="Replace a line range inside a note.",
+        )
+        write_lines_parser.add_argument(
+            "note_path", help="Path to the note relative to the vault root."
+        )
+        write_lines_parser.add_argument(
+            "start_line", type=int, help="1-based start line, inclusive."
+        )
+        write_lines_parser.add_argument(
+            "end_line", type=int, help="1-based end line, inclusive."
+        )
+        write_lines_parser.add_argument(
+            "--content", help="Replacement text for the selected lines."
+        )
+        write_lines_parser.add_argument(
+            "--stdin", action="store_true", help="Read replacement text from stdin."
+        )
+
+        search_parser = subparsers.add_parser("search", help="Search text in notes.")
+        search_parser.add_argument("query", help="Text to search for.")
+        search_parser.add_argument(
+            "--case-sensitive",
+            action="store_true",
+            help="Use case-sensitive matching.",
+        )
+
+        return parser
+
+    @staticmethod
+    def _read_content_arg(content: str | None, use_stdin: bool) -> str:
+        if content is not None and use_stdin:
+            raise VaultError("use either --content or --stdin, not both")
+        if content is not None:
+            return content
+        if use_stdin:
+            return sys.stdin.read()
+        raise VaultError("content is required; provide --content or --stdin")
+
+
+def main(argv: list[str] | None = None) -> int:
+    return ObsidianCLI().run(argv)

odcli-0.1.3/src/obsidian_cli/commands.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from obsidian_cli.vault import ObsidianVault, VaultError
+
+
+class CommandRunner:
+    def __init__(self, vault: ObsidianVault) -> None:
+        self._vault = vault
+
+    def check(self) -> int:
+        if not self._vault.exists():
+            raise VaultError(f"vault does not exist: {self._vault.root}")
+        print(f"vault: {self._vault.root}")
+        if self._vault.is_obsidian_vault():
+            print("status: ok (.obsidian found)")
+        else:
+            print("status: warning (.obsidian not found)")
+        return 0
+
+    def list_notes(self, limit: int) -> int:
+        notes = self._vault.list_notes()
+        if limit > 0:
+            notes = notes[:limit]
+        for note in notes:
+            print(note)
+        return 0
+
+    def read_note(self, note_path: str) -> int:
+        print(self._vault.read_note(note_path), end="")
+        return 0
+
+    def read_note_lines(self, note_path: str, start_line: int, end_line: int) -> int:
+        print(self._vault.read_note_lines(note_path, start_line, end_line), end="")
+        return 0
+
+    def write_note(self, note_path: str, content: str, create_only: bool) -> int:
+        print(self._vault.write_note(note_path, content, create_only=create_only))
+        return 0
+
+    def append_note(self, note_path: str, content: str) -> int:
+        print(self._vault.append_note(note_path, content))
+        return 0
+
+    def write_note_lines(
+        self,
+        note_path: str,
+        start_line: int,
+        end_line: int,
+        content: str,
+    ) -> int:
+        print(self._vault.write_note_lines(note_path, start_line, end_line, content))
+        return 0
+
+    def search(self, query: str, case_sensitive: bool) -> int:
+        matches = self._vault.search(query, case_sensitive=case_sensitive)
+        for match in matches:
+            print(f"{match.note_path}:{match.line_number}: {match.line_text}")
+        return 0 if matches else 1