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.
Files changed (51) hide show
  1. obsidian_agent_cli-0.1.0/PKG-INFO +225 -0
  2. obsidian_agent_cli-0.1.0/README.md +213 -0
  3. obsidian_agent_cli-0.1.0/obsidian_agent_cli.egg-info/PKG-INFO +225 -0
  4. obsidian_agent_cli-0.1.0/obsidian_agent_cli.egg-info/SOURCES.txt +49 -0
  5. obsidian_agent_cli-0.1.0/obsidian_agent_cli.egg-info/dependency_links.txt +1 -0
  6. obsidian_agent_cli-0.1.0/obsidian_agent_cli.egg-info/entry_points.txt +2 -0
  7. obsidian_agent_cli-0.1.0/obsidian_agent_cli.egg-info/requires.txt +3 -0
  8. obsidian_agent_cli-0.1.0/obsidian_agent_cli.egg-info/top_level.txt +1 -0
  9. obsidian_agent_cli-0.1.0/obsidian_cli/__init__.py +0 -0
  10. obsidian_agent_cli-0.1.0/obsidian_cli/canvas_builder.py +127 -0
  11. obsidian_agent_cli-0.1.0/obsidian_cli/commands/__init__.py +0 -0
  12. obsidian_agent_cli-0.1.0/obsidian_cli/commands/active.py +74 -0
  13. obsidian_agent_cli-0.1.0/obsidian_cli/commands/batch_cmd.py +91 -0
  14. obsidian_agent_cli-0.1.0/obsidian_cli/commands/canvas.py +123 -0
  15. obsidian_agent_cli-0.1.0/obsidian_cli/commands/config_cmd.py +57 -0
  16. obsidian_agent_cli-0.1.0/obsidian_cli/commands/core_cmd.py +83 -0
  17. obsidian_agent_cli-0.1.0/obsidian_cli/commands/excalidraw.py +146 -0
  18. obsidian_agent_cli-0.1.0/obsidian_cli/commands/export_cmd.py +40 -0
  19. obsidian_agent_cli-0.1.0/obsidian_cli/commands/git_cmd.py +112 -0
  20. obsidian_agent_cli-0.1.0/obsidian_cli/commands/kanban.py +113 -0
  21. obsidian_agent_cli-0.1.0/obsidian_cli/commands/lint_cmd.py +26 -0
  22. obsidian_agent_cli-0.1.0/obsidian_cli/commands/meta_cmd.py +97 -0
  23. obsidian_agent_cli-0.1.0/obsidian_cli/commands/mover_cmd.py +78 -0
  24. obsidian_agent_cli-0.1.0/obsidian_cli/commands/note.py +178 -0
  25. obsidian_agent_cli-0.1.0/obsidian_cli/commands/periodic.py +127 -0
  26. obsidian_agent_cli-0.1.0/obsidian_cli/commands/quickadd_cmd.py +76 -0
  27. obsidian_agent_cli-0.1.0/obsidian_cli/commands/refactor_cmd.py +81 -0
  28. obsidian_agent_cli-0.1.0/obsidian_cli/commands/run.py +26 -0
  29. obsidian_agent_cli-0.1.0/obsidian_cli/commands/search.py +44 -0
  30. obsidian_agent_cli-0.1.0/obsidian_cli/commands/status_cmd.py +13 -0
  31. obsidian_agent_cli-0.1.0/obsidian_cli/commands/tags_cmd.py +22 -0
  32. obsidian_agent_cli-0.1.0/obsidian_cli/commands/tasks_cmd.py +125 -0
  33. obsidian_agent_cli-0.1.0/obsidian_cli/commands/teach.py +43 -0
  34. obsidian_agent_cli-0.1.0/obsidian_cli/commands/template_cmd.py +45 -0
  35. obsidian_agent_cli-0.1.0/obsidian_cli/commands/uri.py +59 -0
  36. obsidian_agent_cli-0.1.0/obsidian_cli/commands/vault_cmd.py +40 -0
  37. obsidian_agent_cli-0.1.0/obsidian_cli/commands/workspace_cmd.py +67 -0
  38. obsidian_agent_cli-0.1.0/obsidian_cli/config.py +40 -0
  39. obsidian_agent_cli-0.1.0/obsidian_cli/excalidraw_builder.py +210 -0
  40. obsidian_agent_cli-0.1.0/obsidian_cli/kanban_builder.py +60 -0
  41. obsidian_agent_cli-0.1.0/obsidian_cli/main.py +60 -0
  42. obsidian_agent_cli-0.1.0/obsidian_cli/registry.py +98 -0
  43. obsidian_agent_cli-0.1.0/obsidian_cli/transport.py +479 -0
  44. obsidian_agent_cli-0.1.0/pyproject.toml +25 -0
  45. obsidian_agent_cli-0.1.0/setup.cfg +4 -0
  46. obsidian_agent_cli-0.1.0/tests/test_canvas_builder.py +113 -0
  47. obsidian_agent_cli-0.1.0/tests/test_config.py +56 -0
  48. obsidian_agent_cli-0.1.0/tests/test_excalidraw_builder.py +109 -0
  49. obsidian_agent_cli-0.1.0/tests/test_kanban_builder.py +92 -0
  50. obsidian_agent_cli-0.1.0/tests/test_registry.py +103 -0
  51. 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