odcli 0.1.2__tar.gz → 0.1.3__tar.gz

{odcli-0.1.2 → odcli-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: odcli
-Version: 0.1.2
+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
@@ -10,6 +10,7 @@ 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
@@ -20,20 +21,22 @@ Description-Content-Type: text/markdown
 
 # odcli
 
-一个基于 Python 的本地 CLI，用来对 Obsidian vault 做读写操作。它直接操作 vault 里的 Markdown 文件，不依赖 Obsidian 的私有接口，因此稳定、可移植，也方便后续扩展。
+`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
 
-- 校验 vault 路径是否有效
-- 列出 vault 中的 Markdown 笔记
-- 读取指定笔记
-- 按指定行区间读取笔记
-- 覆盖写入或自动创建笔记
-- 按指定行区间覆盖写入
-- 追加内容到笔记末尾
-- 在 vault 中全文搜索
+- 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
 
-## 使用 uv
+## Using uv
 
 ```bash
 cd /Users/huchang/agents/obsidian_cli
@@ -41,62 +44,53 @@ 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
 ```
 
-发布到 PyPI 后，安装包名会是 `odcli`。
-安装后可执行命令同时支持 `odcli` 和 `obsidian-cli`。
+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
 ```
 
-如果你更喜欢显式调用 Python：
+If you prefer module execution:
 
 ```bash
 PYTHONPATH=src python3 -m obsidian_cli --help
 ```
 
-## 可选安装
+## Vault Resolution
 
-如果你想安装到虚拟环境中：
-
-```bash
-cd /Users/huchang/agents/obsidian_cli
-uv sync
-```
-
-## 指定 vault
-
-优先级如下：
+Resolution priority:
 
 1. `--vault /path/to/vault`
-2. 环境变量 `OBSIDIAN_VAULT`
-3. Obsidian 本地配置里最近打开的 vault
-4. 常见默认目录
+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`
@@ -104,7 +98,7 @@ uv sync
 - Windows: `%USERPROFILE%\\Documents\\Obsidian Vault`
 - Windows: `%USERPROFILE%\\Documents\\Obsidian`
 
-示例：
+Example:
 
 ```bash
 export OBSIDIAN_VAULT="/Users/your-name/Documents/MyVault"
@@ -118,47 +112,47 @@ export OBSIDIAN_VAULT="/Users/your-name/Documents/MyVault"
 ./odcli search "project alpha"
 ```
 
-## 命令
+## Commands
 
 ### `check`
 
-检查 vault 是否存在，以及是否包含 `.obsidian` 目录。
+Validate that the vault exists and report whether `.obsidian` is present.
 
 ### `list`
 
-列出 vault 中的 Markdown 文件。
+List Markdown notes in the vault.
 
-可选参数：
+Optional arguments:
 
 - `--limit N`
 
 ### `read`
 
-读取笔记内容。
+Read a note.
 
-参数：
+Arguments:
 
-- `note_path`：相对于 vault 根目录的路径
+- `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`：从标准输入读取内容
+- `--stdin`
 
-可选参数：
+Optional arguments:
 
-- `--create-only`：若文件已存在则报错
+- `--create-only`
 
 ### `read-lines`
 
-读取指定行区间，行号从 `1` 开始，区间是闭区间。
+Read a line range. Line numbers are 1-based and inclusive.
 
-参数：
+Arguments:
 
 - `note_path`
 - `start_line`
@@ -166,9 +160,9 @@ export OBSIDIAN_VAULT="/Users/your-name/Documents/MyVault"
 
 ### `write-lines`
 
-用新内容替换指定行区间，行号从 `1` 开始，区间是闭区间。
+Replace a line range. Line numbers are 1-based and inclusive.
 
-参数：
+Arguments:
 
 - `note_path`
 - `start_line`
@@ -178,9 +172,9 @@ export OBSIDIAN_VAULT="/Users/your-name/Documents/MyVault"
 
 ### `append`
 
-追加内容到笔记末尾。
+Append content to the end of a note.
 
-参数：
+Arguments:
 
 - `note_path`
 - `--content TEXT`
@@ -188,14 +182,14 @@ export OBSIDIAN_VAULT="/Users/your-name/Documents/MyVault"
 
 ### `search`
 
-在所有 Markdown 笔记中搜索文本。
+Search across all Markdown notes in the vault.
 
-参数：
+Arguments:
 
 - `query`
 - `--case-sensitive`
 
-## 测试
+## Testing
 
 ```bash
 cd /Users/huchang/agents/obsidian_cli

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.2 → odcli-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "odcli"
-version = "0.1.2"
+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",
@@ -36,6 +37,7 @@ obsidian-cli = "obsidian_cli.cli:main"
 [dependency-groups]
 dev = [
   "build>=1.2.2",
+  "ruff>=0.14.0",
   "twine>=6.1.0",
 ]
 

{odcli-0.1.2 → 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.2 → 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