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
```
