obsidian-agent-cli 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- obsidian_agent_cli-0.1.0/PKG-INFO +225 -0
- obsidian_agent_cli-0.1.0/README.md +213 -0
- obsidian_agent_cli-0.1.0/obsidian_agent_cli.egg-info/PKG-INFO +225 -0
- obsidian_agent_cli-0.1.0/obsidian_agent_cli.egg-info/SOURCES.txt +49 -0
- obsidian_agent_cli-0.1.0/obsidian_agent_cli.egg-info/dependency_links.txt +1 -0
- obsidian_agent_cli-0.1.0/obsidian_agent_cli.egg-info/entry_points.txt +2 -0
- obsidian_agent_cli-0.1.0/obsidian_agent_cli.egg-info/requires.txt +3 -0
- obsidian_agent_cli-0.1.0/obsidian_agent_cli.egg-info/top_level.txt +1 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/__init__.py +0 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/canvas_builder.py +127 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/__init__.py +0 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/active.py +74 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/batch_cmd.py +91 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/canvas.py +123 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/config_cmd.py +57 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/core_cmd.py +83 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/excalidraw.py +146 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/export_cmd.py +40 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/git_cmd.py +112 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/kanban.py +113 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/lint_cmd.py +26 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/meta_cmd.py +97 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/mover_cmd.py +78 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/note.py +178 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/periodic.py +127 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/quickadd_cmd.py +76 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/refactor_cmd.py +81 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/run.py +26 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/search.py +44 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/status_cmd.py +13 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/tags_cmd.py +22 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/tasks_cmd.py +125 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/teach.py +43 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/template_cmd.py +45 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/uri.py +59 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/vault_cmd.py +40 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/commands/workspace_cmd.py +67 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/config.py +40 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/excalidraw_builder.py +210 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/kanban_builder.py +60 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/main.py +60 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/registry.py +98 -0
- obsidian_agent_cli-0.1.0/obsidian_cli/transport.py +479 -0
- obsidian_agent_cli-0.1.0/pyproject.toml +25 -0
- obsidian_agent_cli-0.1.0/setup.cfg +4 -0
- obsidian_agent_cli-0.1.0/tests/test_canvas_builder.py +113 -0
- obsidian_agent_cli-0.1.0/tests/test_config.py +56 -0
- obsidian_agent_cli-0.1.0/tests/test_excalidraw_builder.py +109 -0
- obsidian_agent_cli-0.1.0/tests/test_kanban_builder.py +92 -0
- obsidian_agent_cli-0.1.0/tests/test_registry.py +103 -0
- obsidian_agent_cli-0.1.0/tests/test_transport.py +276 -0
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: obsidian-agent-cli
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Full-featured CLI for Obsidian — manage notes, canvases, Excalidraw, Kanban, periodic notes, git, tasks, and more.
|
|
5
|
+
Author-email: ProxyLand <proxylandllc@gmail.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Requires-Python: >=3.10
|
|
8
|
+
Description-Content-Type: text/markdown
|
|
9
|
+
Requires-Dist: click>=8.1
|
|
10
|
+
Requires-Dist: requests>=2.31
|
|
11
|
+
Requires-Dist: python-dotenv>=1.0
|
|
12
|
+
|
|
13
|
+
# obsidian-agent-cli
|
|
14
|
+
|
|
15
|
+
A full-featured command-line interface for [Obsidian](https://obsidian.md/) — manage your vault, capture knowledge, build canvases, and run plugin commands, all from the terminal or from an AI agent.
|
|
16
|
+
|
|
17
|
+
Works with any AI coding assistant (Claude Code, Codex, Gemini CLI, etc.) via the included `obsidian_skill.md`.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## How It Works: Vault Structure
|
|
22
|
+
|
|
23
|
+
The CLI is designed around a clean separation of concerns inside your vault:
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
MyVault/ ← your Obsidian vault root
|
|
27
|
+
├── .obsidian/
|
|
28
|
+
│
|
|
29
|
+
├── AI Workspace/ ← the AI agent's dedicated folder (managed by this CLI)
|
|
30
|
+
│ ├── registry.json # project registry
|
|
31
|
+
│ ├── my-project/ # per-project knowledge
|
|
32
|
+
│ │ └── knowledge-log.md
|
|
33
|
+
│ └── Teaching Notes/ # reference notes written by the agent
|
|
34
|
+
│
|
|
35
|
+
├── Your Notes/ ← your folders — the AI never touches these
|
|
36
|
+
├── Projects/ ← yours
|
|
37
|
+
└── Journal/ ← yours
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
**The AI only operates inside `AI Workspace/`.** Every note, canvas, log, and registry file it creates lives there. Your own folders are completely untouched unless you explicitly pass their paths to a command.
|
|
41
|
+
|
|
42
|
+
> 💡 **Recommended setup:** Create a dedicated Obsidian vault just for this — don't drop it into an existing vault you already use heavily. A fresh vault keeps things clean. Then `AI Workspace/` is one subfolder inside it, and any other top-level folders you create are entirely yours.
|
|
43
|
+
|
|
44
|
+
The `AI Workspace` folder name is just the default — rename it to anything you like:
|
|
45
|
+
```bash
|
|
46
|
+
obsidian config set workspace_path "My AI Zone"
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## Features
|
|
52
|
+
|
|
53
|
+
| Command group | What it does |
|
|
54
|
+
|---------------|-------------|
|
|
55
|
+
| `note` | Create, read, update, patch, delete notes — including surgical heading-level edits |
|
|
56
|
+
| `search` | Full-text search and Dataview DQL queries |
|
|
57
|
+
| `active` | Read/write the note currently open in Obsidian |
|
|
58
|
+
| `periodic` | Daily, weekly, monthly notes — read, write, patch, navigate |
|
|
59
|
+
| `workspace` | AI workspace project registry and knowledge log |
|
|
60
|
+
| `canvas` | Build and manage Obsidian canvas files from JSON specs |
|
|
61
|
+
| `excalidraw` | Build Excalidraw diagrams from JSON specs |
|
|
62
|
+
| `kanban` | Create and manage Kanban boards |
|
|
63
|
+
| `vault` | Find notes by glob pattern, move/rename files |
|
|
64
|
+
| `tags` | Rename tags across the entire vault |
|
|
65
|
+
| `batch` | Bulk frontmatter edits and find-and-replace |
|
|
66
|
+
| `export` | Bundle notes into a single markdown file |
|
|
67
|
+
| `teach` | Write reference/teaching notes into the vault |
|
|
68
|
+
| `git` | Obsidian Git plugin commands |
|
|
69
|
+
| `tasks` | Tasks plugin — add and list tasks with emoji markers |
|
|
70
|
+
| `template` | Templater plugin commands |
|
|
71
|
+
| `lint` | Obsidian Linter commands |
|
|
72
|
+
| `quickadd` | QuickAdd plugin — open modal or run a choice |
|
|
73
|
+
| `refactor` | Rename, extract headings, merge notes |
|
|
74
|
+
| `mover` | Auto Note Mover — check and trigger rules |
|
|
75
|
+
| `meta` | Metadata Menu — get/set frontmatter fields |
|
|
76
|
+
| `core` | Core Obsidian UI — palette, graph, settings, splits |
|
|
77
|
+
| `uri` | Obsidian URI scheme — works without Obsidian open |
|
|
78
|
+
| `status` | REST API health check |
|
|
79
|
+
| `config` | View and update CLI configuration |
|
|
80
|
+
| `commands` | List and run any Obsidian command by ID |
|
|
81
|
+
|
|
82
|
+
**All commands output JSON.** Every command returns a single JSON object — parse it, pipe it, or feed it to an AI agent.
|
|
83
|
+
|
|
84
|
+
**Dual-mode transport.** Commands try the Obsidian REST API first. If Obsidian isn't running, most commands fall back to the vault filesystem directly.
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## Requirements
|
|
89
|
+
|
|
90
|
+
- Python 3.10+
|
|
91
|
+
- [Obsidian](https://obsidian.md/) desktop app
|
|
92
|
+
- [Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) community plugin (installed and enabled inside Obsidian)
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## Installation
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
pip install obsidian-agent-cli
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Then run the setup wizard:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
obsidian config init
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
You'll be prompted for:
|
|
109
|
+
- Your vault path (e.g. `/home/yourname/Documents/MyVault`)
|
|
110
|
+
- Your workspace folder name (default: `AI Workspace`)
|
|
111
|
+
- The REST API URL (default: `http://127.0.0.1:27123`)
|
|
112
|
+
- Your Local REST API key (copy from Obsidian → Settings → Local REST API)
|
|
113
|
+
|
|
114
|
+
### Verify it works
|
|
115
|
+
|
|
116
|
+
With Obsidian open:
|
|
117
|
+
```bash
|
|
118
|
+
obsidian status
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
You should see:
|
|
122
|
+
```json
|
|
123
|
+
{"ok": true, "versions": {"obsidian": "1.x.x"}, "transport": "api"}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## Quick Start
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
# Create a note
|
|
132
|
+
obsidian note create "Projects/my-app/arch.md" --content "# Architecture"
|
|
133
|
+
|
|
134
|
+
# Read it back
|
|
135
|
+
obsidian note read "Projects/my-app/arch.md"
|
|
136
|
+
|
|
137
|
+
# Search across vault
|
|
138
|
+
obsidian search simple "authentication"
|
|
139
|
+
|
|
140
|
+
# Register a project for AI knowledge tracking
|
|
141
|
+
obsidian workspace project register my-app
|
|
142
|
+
|
|
143
|
+
# Log a discovery
|
|
144
|
+
obsidian workspace log my-app "Auth uses RS256 JWTs. Token expiry is 15 min."
|
|
145
|
+
|
|
146
|
+
# Read back everything the agent knows about this project
|
|
147
|
+
obsidian workspace recall my-app
|
|
148
|
+
|
|
149
|
+
# Build a canvas overview
|
|
150
|
+
obsidian canvas build "my-app-overview" --spec '{
|
|
151
|
+
"nodes": [
|
|
152
|
+
{"type": "text", "text": "# My App"},
|
|
153
|
+
{"type": "file", "file": "Projects/my-app/arch.md"}
|
|
154
|
+
],
|
|
155
|
+
"edges": [
|
|
156
|
+
{"from": 0, "to": 1, "label": "documented in", "color": "4"}
|
|
157
|
+
]
|
|
158
|
+
}'
|
|
159
|
+
|
|
160
|
+
# Sync vault with git
|
|
161
|
+
obsidian git sync -m "feat: update project notes"
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## AI Agent Integration
|
|
167
|
+
|
|
168
|
+
Drop `obsidian_skill.md` into any project root. Your AI agent (Claude Code, Codex, Gemini CLI, etc.) will automatically:
|
|
169
|
+
|
|
170
|
+
1. **Register new projects** on first encounter
|
|
171
|
+
2. **Recall prior knowledge** at the start of every session
|
|
172
|
+
3. **Log architectural discoveries** and decisions as they happen
|
|
173
|
+
4. **Build visual canvases** and **write teaching notes** when asked
|
|
174
|
+
|
|
175
|
+
See [docs/SKILL_SETUP.md](docs/SKILL_SETUP.md) for details.
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## Configuration
|
|
180
|
+
|
|
181
|
+
Config is stored in `~/.obsidian-cli/config.json`. You can edit it with `obsidian config`:
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
obsidian config show # view current config
|
|
185
|
+
obsidian config set vault_path /path/to/vault # update vault path
|
|
186
|
+
obsidian config set workspace_path "MyWorkspace" # rename workspace folder
|
|
187
|
+
obsidian config set api_key YOUR_KEY # update API key
|
|
188
|
+
obsidian config init # re-run setup wizard
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
---
|
|
192
|
+
|
|
193
|
+
## Documentation
|
|
194
|
+
|
|
195
|
+
- [Installation Guide](docs/INSTALL.md)
|
|
196
|
+
- [Usage Guide](docs/USAGE.md)
|
|
197
|
+
- [AI Skill Setup](docs/SKILL_SETUP.md)
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## Plugin Commands
|
|
202
|
+
|
|
203
|
+
Many command groups require optional Obsidian plugins:
|
|
204
|
+
|
|
205
|
+
| Plugin | Required by |
|
|
206
|
+
|--------|------------|
|
|
207
|
+
| [Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) | Everything (core dependency) |
|
|
208
|
+
| [Dataview](https://github.com/blacksmithgu/obsidian-dataview) | `search advanced`, `note backlinks`, `note by-tag`, `note recent`, `note orphans`, `note links` |
|
|
209
|
+
| [Obsidian Git](https://github.com/denolehov/obsidian-git) | `git` commands |
|
|
210
|
+
| [Tasks](https://github.com/obsidian-tasks-group/obsidian-tasks) | `tasks ui`, `tasks toggle` |
|
|
211
|
+
| [Templater](https://github.com/SilentVoid13/Templater) | `template` commands |
|
|
212
|
+
| [Linter](https://github.com/platers/obsidian-linter) | `lint` commands |
|
|
213
|
+
| [QuickAdd](https://github.com/chhoumann/quickadd) | `quickadd` commands |
|
|
214
|
+
| [Auto Note Mover](https://github.com/farux/obsidian-auto-note-mover) | `mover` commands |
|
|
215
|
+
| [Metadata Menu](https://github.com/mdelobelle/metadatamenu) | `meta` commands |
|
|
216
|
+
| [Excalidraw](https://github.com/zsviczian/obsidian-excalidraw-plugin) | `excalidraw` commands |
|
|
217
|
+
| [Kanban](https://github.com/mgmeyers/obsidian-kanban) | `kanban archive` |
|
|
218
|
+
|
|
219
|
+
Commands that don't require a plugin work directly on the filesystem and don't need Obsidian to be open.
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
## License
|
|
224
|
+
|
|
225
|
+
MIT
|
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
# obsidian-agent-cli
|
|
2
|
+
|
|
3
|
+
A full-featured command-line interface for [Obsidian](https://obsidian.md/) — manage your vault, capture knowledge, build canvases, and run plugin commands, all from the terminal or from an AI agent.
|
|
4
|
+
|
|
5
|
+
Works with any AI coding assistant (Claude Code, Codex, Gemini CLI, etc.) via the included `obsidian_skill.md`.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## How It Works: Vault Structure
|
|
10
|
+
|
|
11
|
+
The CLI is designed around a clean separation of concerns inside your vault:
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
MyVault/ ← your Obsidian vault root
|
|
15
|
+
├── .obsidian/
|
|
16
|
+
│
|
|
17
|
+
├── AI Workspace/ ← the AI agent's dedicated folder (managed by this CLI)
|
|
18
|
+
│ ├── registry.json # project registry
|
|
19
|
+
│ ├── my-project/ # per-project knowledge
|
|
20
|
+
│ │ └── knowledge-log.md
|
|
21
|
+
│ └── Teaching Notes/ # reference notes written by the agent
|
|
22
|
+
│
|
|
23
|
+
├── Your Notes/ ← your folders — the AI never touches these
|
|
24
|
+
├── Projects/ ← yours
|
|
25
|
+
└── Journal/ ← yours
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
**The AI only operates inside `AI Workspace/`.** Every note, canvas, log, and registry file it creates lives there. Your own folders are completely untouched unless you explicitly pass their paths to a command.
|
|
29
|
+
|
|
30
|
+
> 💡 **Recommended setup:** Create a dedicated Obsidian vault just for this — don't drop it into an existing vault you already use heavily. A fresh vault keeps things clean. Then `AI Workspace/` is one subfolder inside it, and any other top-level folders you create are entirely yours.
|
|
31
|
+
|
|
32
|
+
The `AI Workspace` folder name is just the default — rename it to anything you like:
|
|
33
|
+
```bash
|
|
34
|
+
obsidian config set workspace_path "My AI Zone"
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## Features
|
|
40
|
+
|
|
41
|
+
| Command group | What it does |
|
|
42
|
+
|---------------|-------------|
|
|
43
|
+
| `note` | Create, read, update, patch, delete notes — including surgical heading-level edits |
|
|
44
|
+
| `search` | Full-text search and Dataview DQL queries |
|
|
45
|
+
| `active` | Read/write the note currently open in Obsidian |
|
|
46
|
+
| `periodic` | Daily, weekly, monthly notes — read, write, patch, navigate |
|
|
47
|
+
| `workspace` | AI workspace project registry and knowledge log |
|
|
48
|
+
| `canvas` | Build and manage Obsidian canvas files from JSON specs |
|
|
49
|
+
| `excalidraw` | Build Excalidraw diagrams from JSON specs |
|
|
50
|
+
| `kanban` | Create and manage Kanban boards |
|
|
51
|
+
| `vault` | Find notes by glob pattern, move/rename files |
|
|
52
|
+
| `tags` | Rename tags across the entire vault |
|
|
53
|
+
| `batch` | Bulk frontmatter edits and find-and-replace |
|
|
54
|
+
| `export` | Bundle notes into a single markdown file |
|
|
55
|
+
| `teach` | Write reference/teaching notes into the vault |
|
|
56
|
+
| `git` | Obsidian Git plugin commands |
|
|
57
|
+
| `tasks` | Tasks plugin — add and list tasks with emoji markers |
|
|
58
|
+
| `template` | Templater plugin commands |
|
|
59
|
+
| `lint` | Obsidian Linter commands |
|
|
60
|
+
| `quickadd` | QuickAdd plugin — open modal or run a choice |
|
|
61
|
+
| `refactor` | Rename, extract headings, merge notes |
|
|
62
|
+
| `mover` | Auto Note Mover — check and trigger rules |
|
|
63
|
+
| `meta` | Metadata Menu — get/set frontmatter fields |
|
|
64
|
+
| `core` | Core Obsidian UI — palette, graph, settings, splits |
|
|
65
|
+
| `uri` | Obsidian URI scheme — works without Obsidian open |
|
|
66
|
+
| `status` | REST API health check |
|
|
67
|
+
| `config` | View and update CLI configuration |
|
|
68
|
+
| `commands` | List and run any Obsidian command by ID |
|
|
69
|
+
|
|
70
|
+
**All commands output JSON.** Every command returns a single JSON object — parse it, pipe it, or feed it to an AI agent.
|
|
71
|
+
|
|
72
|
+
**Dual-mode transport.** Commands try the Obsidian REST API first. If Obsidian isn't running, most commands fall back to the vault filesystem directly.
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## Requirements
|
|
77
|
+
|
|
78
|
+
- Python 3.10+
|
|
79
|
+
- [Obsidian](https://obsidian.md/) desktop app
|
|
80
|
+
- [Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) community plugin (installed and enabled inside Obsidian)
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## Installation
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
pip install obsidian-agent-cli
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Then run the setup wizard:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
obsidian config init
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
You'll be prompted for:
|
|
97
|
+
- Your vault path (e.g. `/home/yourname/Documents/MyVault`)
|
|
98
|
+
- Your workspace folder name (default: `AI Workspace`)
|
|
99
|
+
- The REST API URL (default: `http://127.0.0.1:27123`)
|
|
100
|
+
- Your Local REST API key (copy from Obsidian → Settings → Local REST API)
|
|
101
|
+
|
|
102
|
+
### Verify it works
|
|
103
|
+
|
|
104
|
+
With Obsidian open:
|
|
105
|
+
```bash
|
|
106
|
+
obsidian status
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
You should see:
|
|
110
|
+
```json
|
|
111
|
+
{"ok": true, "versions": {"obsidian": "1.x.x"}, "transport": "api"}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## Quick Start
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
# Create a note
|
|
120
|
+
obsidian note create "Projects/my-app/arch.md" --content "# Architecture"
|
|
121
|
+
|
|
122
|
+
# Read it back
|
|
123
|
+
obsidian note read "Projects/my-app/arch.md"
|
|
124
|
+
|
|
125
|
+
# Search across vault
|
|
126
|
+
obsidian search simple "authentication"
|
|
127
|
+
|
|
128
|
+
# Register a project for AI knowledge tracking
|
|
129
|
+
obsidian workspace project register my-app
|
|
130
|
+
|
|
131
|
+
# Log a discovery
|
|
132
|
+
obsidian workspace log my-app "Auth uses RS256 JWTs. Token expiry is 15 min."
|
|
133
|
+
|
|
134
|
+
# Read back everything the agent knows about this project
|
|
135
|
+
obsidian workspace recall my-app
|
|
136
|
+
|
|
137
|
+
# Build a canvas overview
|
|
138
|
+
obsidian canvas build "my-app-overview" --spec '{
|
|
139
|
+
"nodes": [
|
|
140
|
+
{"type": "text", "text": "# My App"},
|
|
141
|
+
{"type": "file", "file": "Projects/my-app/arch.md"}
|
|
142
|
+
],
|
|
143
|
+
"edges": [
|
|
144
|
+
{"from": 0, "to": 1, "label": "documented in", "color": "4"}
|
|
145
|
+
]
|
|
146
|
+
}'
|
|
147
|
+
|
|
148
|
+
# Sync vault with git
|
|
149
|
+
obsidian git sync -m "feat: update project notes"
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## AI Agent Integration
|
|
155
|
+
|
|
156
|
+
Drop `obsidian_skill.md` into any project root. Your AI agent (Claude Code, Codex, Gemini CLI, etc.) will automatically:
|
|
157
|
+
|
|
158
|
+
1. **Register new projects** on first encounter
|
|
159
|
+
2. **Recall prior knowledge** at the start of every session
|
|
160
|
+
3. **Log architectural discoveries** and decisions as they happen
|
|
161
|
+
4. **Build visual canvases** and **write teaching notes** when asked
|
|
162
|
+
|
|
163
|
+
See [docs/SKILL_SETUP.md](docs/SKILL_SETUP.md) for details.
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## Configuration
|
|
168
|
+
|
|
169
|
+
Config is stored in `~/.obsidian-cli/config.json`. You can edit it with `obsidian config`:
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
obsidian config show # view current config
|
|
173
|
+
obsidian config set vault_path /path/to/vault # update vault path
|
|
174
|
+
obsidian config set workspace_path "MyWorkspace" # rename workspace folder
|
|
175
|
+
obsidian config set api_key YOUR_KEY # update API key
|
|
176
|
+
obsidian config init # re-run setup wizard
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
---
|
|
180
|
+
|
|
181
|
+
## Documentation
|
|
182
|
+
|
|
183
|
+
- [Installation Guide](docs/INSTALL.md)
|
|
184
|
+
- [Usage Guide](docs/USAGE.md)
|
|
185
|
+
- [AI Skill Setup](docs/SKILL_SETUP.md)
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
## Plugin Commands
|
|
190
|
+
|
|
191
|
+
Many command groups require optional Obsidian plugins:
|
|
192
|
+
|
|
193
|
+
| Plugin | Required by |
|
|
194
|
+
|--------|------------|
|
|
195
|
+
| [Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) | Everything (core dependency) |
|
|
196
|
+
| [Dataview](https://github.com/blacksmithgu/obsidian-dataview) | `search advanced`, `note backlinks`, `note by-tag`, `note recent`, `note orphans`, `note links` |
|
|
197
|
+
| [Obsidian Git](https://github.com/denolehov/obsidian-git) | `git` commands |
|
|
198
|
+
| [Tasks](https://github.com/obsidian-tasks-group/obsidian-tasks) | `tasks ui`, `tasks toggle` |
|
|
199
|
+
| [Templater](https://github.com/SilentVoid13/Templater) | `template` commands |
|
|
200
|
+
| [Linter](https://github.com/platers/obsidian-linter) | `lint` commands |
|
|
201
|
+
| [QuickAdd](https://github.com/chhoumann/quickadd) | `quickadd` commands |
|
|
202
|
+
| [Auto Note Mover](https://github.com/farux/obsidian-auto-note-mover) | `mover` commands |
|
|
203
|
+
| [Metadata Menu](https://github.com/mdelobelle/metadatamenu) | `meta` commands |
|
|
204
|
+
| [Excalidraw](https://github.com/zsviczian/obsidian-excalidraw-plugin) | `excalidraw` commands |
|
|
205
|
+
| [Kanban](https://github.com/mgmeyers/obsidian-kanban) | `kanban archive` |
|
|
206
|
+
|
|
207
|
+
Commands that don't require a plugin work directly on the filesystem and don't need Obsidian to be open.
|
|
208
|
+
|
|
209
|
+
---
|
|
210
|
+
|
|
211
|
+
## License
|
|
212
|
+
|
|
213
|
+
MIT
|
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: obsidian-agent-cli
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Full-featured CLI for Obsidian — manage notes, canvases, Excalidraw, Kanban, periodic notes, git, tasks, and more.
|
|
5
|
+
Author-email: ProxyLand <proxylandllc@gmail.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Requires-Python: >=3.10
|
|
8
|
+
Description-Content-Type: text/markdown
|
|
9
|
+
Requires-Dist: click>=8.1
|
|
10
|
+
Requires-Dist: requests>=2.31
|
|
11
|
+
Requires-Dist: python-dotenv>=1.0
|
|
12
|
+
|
|
13
|
+
# obsidian-agent-cli
|
|
14
|
+
|
|
15
|
+
A full-featured command-line interface for [Obsidian](https://obsidian.md/) — manage your vault, capture knowledge, build canvases, and run plugin commands, all from the terminal or from an AI agent.
|
|
16
|
+
|
|
17
|
+
Works with any AI coding assistant (Claude Code, Codex, Gemini CLI, etc.) via the included `obsidian_skill.md`.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## How It Works: Vault Structure
|
|
22
|
+
|
|
23
|
+
The CLI is designed around a clean separation of concerns inside your vault:
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
MyVault/ ← your Obsidian vault root
|
|
27
|
+
├── .obsidian/
|
|
28
|
+
│
|
|
29
|
+
├── AI Workspace/ ← the AI agent's dedicated folder (managed by this CLI)
|
|
30
|
+
│ ├── registry.json # project registry
|
|
31
|
+
│ ├── my-project/ # per-project knowledge
|
|
32
|
+
│ │ └── knowledge-log.md
|
|
33
|
+
│ └── Teaching Notes/ # reference notes written by the agent
|
|
34
|
+
│
|
|
35
|
+
├── Your Notes/ ← your folders — the AI never touches these
|
|
36
|
+
├── Projects/ ← yours
|
|
37
|
+
└── Journal/ ← yours
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
**The AI only operates inside `AI Workspace/`.** Every note, canvas, log, and registry file it creates lives there. Your own folders are completely untouched unless you explicitly pass their paths to a command.
|
|
41
|
+
|
|
42
|
+
> 💡 **Recommended setup:** Create a dedicated Obsidian vault just for this — don't drop it into an existing vault you already use heavily. A fresh vault keeps things clean. Then `AI Workspace/` is one subfolder inside it, and any other top-level folders you create are entirely yours.
|
|
43
|
+
|
|
44
|
+
The `AI Workspace` folder name is just the default — rename it to anything you like:
|
|
45
|
+
```bash
|
|
46
|
+
obsidian config set workspace_path "My AI Zone"
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## Features
|
|
52
|
+
|
|
53
|
+
| Command group | What it does |
|
|
54
|
+
|---------------|-------------|
|
|
55
|
+
| `note` | Create, read, update, patch, delete notes — including surgical heading-level edits |
|
|
56
|
+
| `search` | Full-text search and Dataview DQL queries |
|
|
57
|
+
| `active` | Read/write the note currently open in Obsidian |
|
|
58
|
+
| `periodic` | Daily, weekly, monthly notes — read, write, patch, navigate |
|
|
59
|
+
| `workspace` | AI workspace project registry and knowledge log |
|
|
60
|
+
| `canvas` | Build and manage Obsidian canvas files from JSON specs |
|
|
61
|
+
| `excalidraw` | Build Excalidraw diagrams from JSON specs |
|
|
62
|
+
| `kanban` | Create and manage Kanban boards |
|
|
63
|
+
| `vault` | Find notes by glob pattern, move/rename files |
|
|
64
|
+
| `tags` | Rename tags across the entire vault |
|
|
65
|
+
| `batch` | Bulk frontmatter edits and find-and-replace |
|
|
66
|
+
| `export` | Bundle notes into a single markdown file |
|
|
67
|
+
| `teach` | Write reference/teaching notes into the vault |
|
|
68
|
+
| `git` | Obsidian Git plugin commands |
|
|
69
|
+
| `tasks` | Tasks plugin — add and list tasks with emoji markers |
|
|
70
|
+
| `template` | Templater plugin commands |
|
|
71
|
+
| `lint` | Obsidian Linter commands |
|
|
72
|
+
| `quickadd` | QuickAdd plugin — open modal or run a choice |
|
|
73
|
+
| `refactor` | Rename, extract headings, merge notes |
|
|
74
|
+
| `mover` | Auto Note Mover — check and trigger rules |
|
|
75
|
+
| `meta` | Metadata Menu — get/set frontmatter fields |
|
|
76
|
+
| `core` | Core Obsidian UI — palette, graph, settings, splits |
|
|
77
|
+
| `uri` | Obsidian URI scheme — works without Obsidian open |
|
|
78
|
+
| `status` | REST API health check |
|
|
79
|
+
| `config` | View and update CLI configuration |
|
|
80
|
+
| `commands` | List and run any Obsidian command by ID |
|
|
81
|
+
|
|
82
|
+
**All commands output JSON.** Every command returns a single JSON object — parse it, pipe it, or feed it to an AI agent.
|
|
83
|
+
|
|
84
|
+
**Dual-mode transport.** Commands try the Obsidian REST API first. If Obsidian isn't running, most commands fall back to the vault filesystem directly.
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## Requirements
|
|
89
|
+
|
|
90
|
+
- Python 3.10+
|
|
91
|
+
- [Obsidian](https://obsidian.md/) desktop app
|
|
92
|
+
- [Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) community plugin (installed and enabled inside Obsidian)
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## Installation
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
pip install obsidian-agent-cli
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Then run the setup wizard:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
obsidian config init
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
You'll be prompted for:
|
|
109
|
+
- Your vault path (e.g. `/home/yourname/Documents/MyVault`)
|
|
110
|
+
- Your workspace folder name (default: `AI Workspace`)
|
|
111
|
+
- The REST API URL (default: `http://127.0.0.1:27123`)
|
|
112
|
+
- Your Local REST API key (copy from Obsidian → Settings → Local REST API)
|
|
113
|
+
|
|
114
|
+
### Verify it works
|
|
115
|
+
|
|
116
|
+
With Obsidian open:
|
|
117
|
+
```bash
|
|
118
|
+
obsidian status
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
You should see:
|
|
122
|
+
```json
|
|
123
|
+
{"ok": true, "versions": {"obsidian": "1.x.x"}, "transport": "api"}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## Quick Start
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
# Create a note
|
|
132
|
+
obsidian note create "Projects/my-app/arch.md" --content "# Architecture"
|
|
133
|
+
|
|
134
|
+
# Read it back
|
|
135
|
+
obsidian note read "Projects/my-app/arch.md"
|
|
136
|
+
|
|
137
|
+
# Search across vault
|
|
138
|
+
obsidian search simple "authentication"
|
|
139
|
+
|
|
140
|
+
# Register a project for AI knowledge tracking
|
|
141
|
+
obsidian workspace project register my-app
|
|
142
|
+
|
|
143
|
+
# Log a discovery
|
|
144
|
+
obsidian workspace log my-app "Auth uses RS256 JWTs. Token expiry is 15 min."
|
|
145
|
+
|
|
146
|
+
# Read back everything the agent knows about this project
|
|
147
|
+
obsidian workspace recall my-app
|
|
148
|
+
|
|
149
|
+
# Build a canvas overview
|
|
150
|
+
obsidian canvas build "my-app-overview" --spec '{
|
|
151
|
+
"nodes": [
|
|
152
|
+
{"type": "text", "text": "# My App"},
|
|
153
|
+
{"type": "file", "file": "Projects/my-app/arch.md"}
|
|
154
|
+
],
|
|
155
|
+
"edges": [
|
|
156
|
+
{"from": 0, "to": 1, "label": "documented in", "color": "4"}
|
|
157
|
+
]
|
|
158
|
+
}'
|
|
159
|
+
|
|
160
|
+
# Sync vault with git
|
|
161
|
+
obsidian git sync -m "feat: update project notes"
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## AI Agent Integration
|
|
167
|
+
|
|
168
|
+
Drop `obsidian_skill.md` into any project root. Your AI agent (Claude Code, Codex, Gemini CLI, etc.) will automatically:
|
|
169
|
+
|
|
170
|
+
1. **Register new projects** on first encounter
|
|
171
|
+
2. **Recall prior knowledge** at the start of every session
|
|
172
|
+
3. **Log architectural discoveries** and decisions as they happen
|
|
173
|
+
4. **Build visual canvases** and **write teaching notes** when asked
|
|
174
|
+
|
|
175
|
+
See [docs/SKILL_SETUP.md](docs/SKILL_SETUP.md) for details.
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## Configuration
|
|
180
|
+
|
|
181
|
+
Config is stored in `~/.obsidian-cli/config.json`. You can edit it with `obsidian config`:
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
obsidian config show # view current config
|
|
185
|
+
obsidian config set vault_path /path/to/vault # update vault path
|
|
186
|
+
obsidian config set workspace_path "MyWorkspace" # rename workspace folder
|
|
187
|
+
obsidian config set api_key YOUR_KEY # update API key
|
|
188
|
+
obsidian config init # re-run setup wizard
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
---
|
|
192
|
+
|
|
193
|
+
## Documentation
|
|
194
|
+
|
|
195
|
+
- [Installation Guide](docs/INSTALL.md)
|
|
196
|
+
- [Usage Guide](docs/USAGE.md)
|
|
197
|
+
- [AI Skill Setup](docs/SKILL_SETUP.md)
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## Plugin Commands
|
|
202
|
+
|
|
203
|
+
Many command groups require optional Obsidian plugins:
|
|
204
|
+
|
|
205
|
+
| Plugin | Required by |
|
|
206
|
+
|--------|------------|
|
|
207
|
+
| [Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) | Everything (core dependency) |
|
|
208
|
+
| [Dataview](https://github.com/blacksmithgu/obsidian-dataview) | `search advanced`, `note backlinks`, `note by-tag`, `note recent`, `note orphans`, `note links` |
|
|
209
|
+
| [Obsidian Git](https://github.com/denolehov/obsidian-git) | `git` commands |
|
|
210
|
+
| [Tasks](https://github.com/obsidian-tasks-group/obsidian-tasks) | `tasks ui`, `tasks toggle` |
|
|
211
|
+
| [Templater](https://github.com/SilentVoid13/Templater) | `template` commands |
|
|
212
|
+
| [Linter](https://github.com/platers/obsidian-linter) | `lint` commands |
|
|
213
|
+
| [QuickAdd](https://github.com/chhoumann/quickadd) | `quickadd` commands |
|
|
214
|
+
| [Auto Note Mover](https://github.com/farux/obsidian-auto-note-mover) | `mover` commands |
|
|
215
|
+
| [Metadata Menu](https://github.com/mdelobelle/metadatamenu) | `meta` commands |
|
|
216
|
+
| [Excalidraw](https://github.com/zsviczian/obsidian-excalidraw-plugin) | `excalidraw` commands |
|
|
217
|
+
| [Kanban](https://github.com/mgmeyers/obsidian-kanban) | `kanban archive` |
|
|
218
|
+
|
|
219
|
+
Commands that don't require a plugin work directly on the filesystem and don't need Obsidian to be open.
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
## License
|
|
224
|
+
|
|
225
|
+
MIT
|