@creator-notes/cnotes 0.16.11

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 (158) hide show
  1. package/.claude-plugin/plugin.json +14 -0
  2. package/.mcp.json +12 -0
  3. package/LICENSE +21 -0
  4. package/README.md +303 -0
  5. package/dist/cn.d.ts +3 -0
  6. package/dist/cn.d.ts.map +1 -0
  7. package/dist/cn.js +124 -0
  8. package/dist/cn.js.map +1 -0
  9. package/dist/commands/auth.d.ts +10 -0
  10. package/dist/commands/auth.d.ts.map +1 -0
  11. package/dist/commands/auth.js +188 -0
  12. package/dist/commands/auth.js.map +1 -0
  13. package/dist/commands/canvas.d.ts +3 -0
  14. package/dist/commands/canvas.d.ts.map +1 -0
  15. package/dist/commands/canvas.js +1383 -0
  16. package/dist/commands/canvas.js.map +1 -0
  17. package/dist/commands/claude-hook.d.ts +28 -0
  18. package/dist/commands/claude-hook.d.ts.map +1 -0
  19. package/dist/commands/claude-hook.js +59 -0
  20. package/dist/commands/claude-hook.js.map +1 -0
  21. package/dist/commands/config.d.ts +3 -0
  22. package/dist/commands/config.d.ts.map +1 -0
  23. package/dist/commands/config.js +47 -0
  24. package/dist/commands/config.js.map +1 -0
  25. package/dist/commands/files.d.ts +3 -0
  26. package/dist/commands/files.d.ts.map +1 -0
  27. package/dist/commands/files.js +119 -0
  28. package/dist/commands/files.js.map +1 -0
  29. package/dist/commands/init.d.ts +3 -0
  30. package/dist/commands/init.d.ts.map +1 -0
  31. package/dist/commands/init.js +473 -0
  32. package/dist/commands/init.js.map +1 -0
  33. package/dist/commands/mcp.d.ts +15 -0
  34. package/dist/commands/mcp.d.ts.map +1 -0
  35. package/dist/commands/mcp.js +118 -0
  36. package/dist/commands/mcp.js.map +1 -0
  37. package/dist/commands/memory.d.ts +3 -0
  38. package/dist/commands/memory.d.ts.map +1 -0
  39. package/dist/commands/memory.js +150 -0
  40. package/dist/commands/memory.js.map +1 -0
  41. package/dist/commands/notes.d.ts +3 -0
  42. package/dist/commands/notes.d.ts.map +1 -0
  43. package/dist/commands/notes.js +706 -0
  44. package/dist/commands/notes.js.map +1 -0
  45. package/dist/commands/operations.d.ts +18 -0
  46. package/dist/commands/operations.d.ts.map +1 -0
  47. package/dist/commands/operations.js +231 -0
  48. package/dist/commands/operations.js.map +1 -0
  49. package/dist/commands/relationships.d.ts +3 -0
  50. package/dist/commands/relationships.d.ts.map +1 -0
  51. package/dist/commands/relationships.js +94 -0
  52. package/dist/commands/relationships.js.map +1 -0
  53. package/dist/commands/schema.d.ts +12 -0
  54. package/dist/commands/schema.d.ts.map +1 -0
  55. package/dist/commands/schema.js +85 -0
  56. package/dist/commands/schema.js.map +1 -0
  57. package/dist/commands/search.d.ts +3 -0
  58. package/dist/commands/search.d.ts.map +1 -0
  59. package/dist/commands/search.js +57 -0
  60. package/dist/commands/search.js.map +1 -0
  61. package/dist/commands/theme.d.ts +3 -0
  62. package/dist/commands/theme.d.ts.map +1 -0
  63. package/dist/commands/theme.js +184 -0
  64. package/dist/commands/theme.js.map +1 -0
  65. package/dist/commands/timeline.d.ts +3 -0
  66. package/dist/commands/timeline.d.ts.map +1 -0
  67. package/dist/commands/timeline.js +97 -0
  68. package/dist/commands/timeline.js.map +1 -0
  69. package/dist/commands/types.d.ts +3 -0
  70. package/dist/commands/types.d.ts.map +1 -0
  71. package/dist/commands/types.js +139 -0
  72. package/dist/commands/types.js.map +1 -0
  73. package/dist/commands/versions.d.ts +3 -0
  74. package/dist/commands/versions.d.ts.map +1 -0
  75. package/dist/commands/versions.js +120 -0
  76. package/dist/commands/versions.js.map +1 -0
  77. package/dist/commands/workspace.d.ts +13 -0
  78. package/dist/commands/workspace.d.ts.map +1 -0
  79. package/dist/commands/workspace.js +176 -0
  80. package/dist/commands/workspace.js.map +1 -0
  81. package/dist/lib/api-client.d.ts +45 -0
  82. package/dist/lib/api-client.d.ts.map +1 -0
  83. package/dist/lib/api-client.js +198 -0
  84. package/dist/lib/api-client.js.map +1 -0
  85. package/dist/lib/auth-store.d.ts +47 -0
  86. package/dist/lib/auth-store.d.ts.map +1 -0
  87. package/dist/lib/auth-store.js +116 -0
  88. package/dist/lib/auth-store.js.map +1 -0
  89. package/dist/lib/brand.d.ts +32 -0
  90. package/dist/lib/brand.d.ts.map +1 -0
  91. package/dist/lib/brand.js +32 -0
  92. package/dist/lib/brand.js.map +1 -0
  93. package/dist/lib/build-schema.d.ts +97 -0
  94. package/dist/lib/build-schema.d.ts.map +1 -0
  95. package/dist/lib/build-schema.js +139 -0
  96. package/dist/lib/build-schema.js.map +1 -0
  97. package/dist/lib/canvas-read.d.ts +54 -0
  98. package/dist/lib/canvas-read.d.ts.map +1 -0
  99. package/dist/lib/canvas-read.js +145 -0
  100. package/dist/lib/canvas-read.js.map +1 -0
  101. package/dist/lib/claude-session.d.ts +73 -0
  102. package/dist/lib/claude-session.d.ts.map +1 -0
  103. package/dist/lib/claude-session.js +104 -0
  104. package/dist/lib/claude-session.js.map +1 -0
  105. package/dist/lib/config.d.ts +28 -0
  106. package/dist/lib/config.d.ts.map +1 -0
  107. package/dist/lib/config.js +66 -0
  108. package/dist/lib/config.js.map +1 -0
  109. package/dist/lib/env.d.ts +14 -0
  110. package/dist/lib/env.d.ts.map +1 -0
  111. package/dist/lib/env.js +16 -0
  112. package/dist/lib/env.js.map +1 -0
  113. package/dist/lib/errors.d.ts +47 -0
  114. package/dist/lib/errors.d.ts.map +1 -0
  115. package/dist/lib/errors.js +194 -0
  116. package/dist/lib/errors.js.map +1 -0
  117. package/dist/lib/fs-utils.d.ts +2 -0
  118. package/dist/lib/fs-utils.d.ts.map +1 -0
  119. package/dist/lib/fs-utils.js +16 -0
  120. package/dist/lib/fs-utils.js.map +1 -0
  121. package/dist/lib/install-hook.d.ts +86 -0
  122. package/dist/lib/install-hook.d.ts.map +1 -0
  123. package/dist/lib/install-hook.js +168 -0
  124. package/dist/lib/install-hook.js.map +1 -0
  125. package/dist/lib/install-mcp.d.ts +21 -0
  126. package/dist/lib/install-mcp.d.ts.map +1 -0
  127. package/dist/lib/install-mcp.js +133 -0
  128. package/dist/lib/install-mcp.js.map +1 -0
  129. package/dist/lib/install-skill.d.ts +49 -0
  130. package/dist/lib/install-skill.d.ts.map +1 -0
  131. package/dist/lib/install-skill.js +113 -0
  132. package/dist/lib/install-skill.js.map +1 -0
  133. package/dist/lib/output.d.ts +29 -0
  134. package/dist/lib/output.d.ts.map +1 -0
  135. package/dist/lib/output.js +78 -0
  136. package/dist/lib/output.js.map +1 -0
  137. package/dist/lib/resolve-note.d.ts +7 -0
  138. package/dist/lib/resolve-note.d.ts.map +1 -0
  139. package/dist/lib/resolve-note.js +23 -0
  140. package/dist/lib/resolve-note.js.map +1 -0
  141. package/dist/lib/stdin.d.ts +5 -0
  142. package/dist/lib/stdin.d.ts.map +1 -0
  143. package/dist/lib/stdin.js +11 -0
  144. package/dist/lib/stdin.js.map +1 -0
  145. package/dist/lib/style.d.ts +10 -0
  146. package/dist/lib/style.d.ts.map +1 -0
  147. package/dist/lib/style.js +17 -0
  148. package/dist/lib/style.js.map +1 -0
  149. package/dist/lib/themes.d.ts +44 -0
  150. package/dist/lib/themes.d.ts.map +1 -0
  151. package/dist/lib/themes.js +168 -0
  152. package/dist/lib/themes.js.map +1 -0
  153. package/dist/mcp-server.d.ts +3 -0
  154. package/dist/mcp-server.d.ts.map +1 -0
  155. package/dist/mcp-server.js +782 -0
  156. package/dist/mcp-server.js.map +1 -0
  157. package/package.json +66 -0
  158. package/skills/cnotes/SKILL.md +680 -0
@@ -0,0 +1,14 @@
1
+ {
2
+ "name": "creator-notes-cli",
3
+ "version": "0.8.0",
4
+ "description": "CreatorNotes CLI — create notes, build canvases, search knowledge from the terminal",
5
+ "author": {
6
+ "name": "CreatorNotes",
7
+ "url": "https://creatornotes.app"
8
+ },
9
+ "repository": "https://github.com/creatornotes/pm-notes",
10
+ "license": "MIT",
11
+ "keywords": ["cli", "notes", "productivity", "pm", "canvas", "knowledge-management"],
12
+ "skills": "./skills/",
13
+ "mcpServers": "./.mcp.json"
14
+ }
package/.mcp.json ADDED
@@ -0,0 +1,12 @@
1
+ {
2
+ "servers": {
3
+ "cnotes": {
4
+ "command": "cnotes-mcp",
5
+ "env": {
6
+ "CN_SERVER": "${input:cnServer}",
7
+ "CN_TOKEN": "${input:cnToken}",
8
+ "CN_WORKSPACE": "${input:cnWorkspace}"
9
+ }
10
+ }
11
+ }
12
+ }
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 CreatorNotes
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,303 @@
1
+ # @creator-notes/cnotes
2
+
3
+ CLI for [CreatorNotes](https://creatornotes.app) — create notes, build canvases, search knowledge, and manage workspaces from the terminal.
4
+
5
+ Works as a standalone CLI (`cnotes`) and as an MCP server (`cnotes-mcp`) for AI assistants like Claude.
6
+
7
+ ## Quick Start
8
+
9
+ One command sets everything up — auth, workspace, Claude Code skill, and (optionally) a global `cnotes` shortcut:
10
+
11
+ ```bash
12
+ npx @creator-notes/cnotes@latest init
13
+ ```
14
+
15
+ The wizard opens your browser to sign in (the only manual step), then offers to install the Claude Code skill and `cnotes` globally so future calls are instant.
16
+
17
+ After init:
18
+
19
+ ```bash
20
+ cnotes notes list # Browse your notes
21
+ cnotes notes create --notes '{"key":"A","type":"Meeting","markdown":"# Standup\nAgenda…"}'
22
+ cnotes search semantic "onboarding flow"
23
+ ```
24
+
25
+ > Prefer to install globally up front? `npm install -g @creator-notes/cnotes && cnotes init` works too.
26
+
27
+ ## Commands
28
+
29
+ | Command | Alias | Description |
30
+ |---------|-------|-------------|
31
+ | `cnotes init` | | Interactive setup wizard |
32
+ | `cnotes auth login` | | Authenticate via browser or API token |
33
+ | `cnotes notes list\|get\|create\|update\|delete` | `cnotes n` | Manage notes (create accepts one or many items) |
34
+ | `cnotes notes bulk-retype` | | Retype multiple notes to a new type |
35
+ | `cnotes notes move` | | Move a note to another workspace (copies content, archives source, cross-links) |
36
+ | `cnotes versions list\|create` | `cnotes v` | Note version history |
37
+ | `cnotes canvas list\|get\|create\|delete` | `cnotes c` | Manage canvases |
38
+ | `cnotes canvas place` | | Declarative layout — server packs items with no overlap |
39
+ | `cnotes canvas add-node\|add-text\|add-richtext\|add-list\|add-link` | | Add a single node at explicit `--x`/`--y` |
40
+ | `cnotes canvas bulk-add\|bulk-move\|bulk-remove` | | Bulk canvas operations — requires explicit coordinates |
41
+ | `cnotes canvas from-template` | | Create canvas from template |
42
+ | `cnotes search semantic` | `cnotes s` | Semantic search across notes |
43
+ | `cnotes timeline` | `cnotes tl` | Recent activity feed |
44
+ | `cnotes relationships list` | `cnotes rel` | Note relationships |
45
+ | `cnotes types list\|create\|update` | `cnotes t` | Manage note types (supertags) |
46
+ | `cnotes memory query\|facts\|entities` | `cnotes mem` | Query workspace knowledge |
47
+ | `cnotes workspace list\|select\|current` | | Workspace management |
48
+ | `cnotes config get-server\|set-server` | | CLI configuration |
49
+ | `cnotes mcp setup` | | Print MCP server config for Claude |
50
+
51
+ ## Global Flags
52
+
53
+ ```
54
+ --json Output raw JSON (for piping / scripting)
55
+ -q, --quiet Minimal output (IDs only)
56
+ -w, --workspace <id> Override active workspace
57
+ --server <url> Override server URL
58
+ ```
59
+
60
+ ## Output Contract
61
+
62
+ One contract across every command:
63
+
64
+ - **Success is the exit code, not a body field.** Exit `0` is success; never look for an `ok` key. Failures use a typed table: `2` auth, `3` validation, `4` not found, `5` conflict, `6` rate limit, `7` permission. Re-running a write because a key looked empty will duplicate it.
65
+ - **Reads return a bare array; writes return an envelope.** `notes list/get/search --json` pipe to `jq '.[0]'`. `notes create --json` returns `{ results, relationshipsCreated, relationshipTypesCreated }`; read created notes from `.results` (not `notes`/`ok`).
66
+ - **Errors teach.** A `--json` failure prints `{ error, code, exitCode, hint }` to stderr, where `hint` names the command that fixes it (a bad workspace id returns a 404 with `resource: "workspace"` and a `cnotes workspace list` hint, not a bare 500).
67
+
68
+ ## Authentication
69
+
70
+ ```bash
71
+ # Browser-based OAuth (recommended)
72
+ cnotes auth login
73
+
74
+ # API token (CI / non-interactive)
75
+ cnotes auth login --token <key>
76
+
77
+ # Check session
78
+ cnotes auth status
79
+ ```
80
+
81
+ ## Notes
82
+
83
+ `cnotes notes create` accepts one item or many — pass `--notes` either as a single
84
+ JSON object or an array of objects. Use `[@key: Title](relationship:references)`
85
+ inside markdown to cross-reference another item in the same batch — `@key` is
86
+ replaced with the new note's display ID after creation.
87
+
88
+ ```bash
89
+ # Single note (object form)
90
+ cnotes notes create --notes '{"key":"A","type":"Insight","markdown":"# Quick idea","tags":["ux","onboarding"]}'
91
+
92
+ # Multiple interlinked notes (array form)
93
+ cnotes notes create --notes '[
94
+ {"key":"A","type":"PainPoint","markdownFile":"./problem.md"},
95
+ {"key":"B","type":"Insight","markdown":"# Solution\nFixes [@A: Problem](relationship:references)."}
96
+ ]'
97
+
98
+ # List with filters
99
+ cnotes notes list --type Meeting --pinned --limit 10
100
+
101
+ # Get one or many by display ID (single round-trip, always returns array in input order)
102
+ cnotes notes get MEETING-42
103
+ cnotes notes get MEETING-42 PRD-3 IDEA-7
104
+
105
+ # Update metadata
106
+ cnotes notes update MEETING-42 --pin --tags "important,q2"
107
+ ```
108
+
109
+ If any item is malformed, the command exits non-zero and lists every bad item
110
+ together — `item <index> (<key>): <field>: <reason>` — so you can fix the whole
111
+ batch in one shot. With `--json`, the same per-item errors come back under
112
+ `details.items` for programmatic parsing.
113
+
114
+ ### Bulk Retype
115
+
116
+ Change the type of multiple notes at once:
117
+
118
+ ```bash
119
+ cnotes notes bulk-retype --ids '["NOTE-1","NOTE-3","NOTE-5"]' --type Insight --json
120
+ ```
121
+
122
+ ### Content Updates
123
+
124
+ Content and metadata are separate operations:
125
+
126
+ ```bash
127
+ # Update content -> create a new version
128
+ cnotes versions create MEETING-42 --description "Added action items" --markdown-file ./updated.md
129
+
130
+ # Update metadata (type, tags, pin, archive). Title is read-only —
131
+ # change it by creating a new version with a different # h1 heading.
132
+ cnotes notes update MEETING-42 --type Insight --tags "auth,security" --pin
133
+ ```
134
+
135
+ ## Canvas
136
+
137
+ Values in `<angle-brackets>` are placeholders — replace them with real IDs from your workspace.
138
+
139
+ ```bash
140
+ # Create a canvas
141
+ cnotes canvas create "Sprint Review"
142
+
143
+ # Read every note on a canvas as one concatenated markdown document, in
144
+ # display order — for thinking across a canvas in a single round-trip
145
+ cnotes canvas read <canvasId>
146
+
147
+ # Recent activity on a canvas: edits, agent runs, gestures, restores —
148
+ # newest first. Use this to see what changed (and who changed it) before
149
+ # editing, or to confirm a previous agent run actually applied.
150
+ cnotes canvas activity <canvasId> [--limit 50]
151
+
152
+ # Place items with a declarative layout (preferred — no x/y math)
153
+ cnotes canvas place <canvasId> --spec ./layout.json
154
+
155
+ # Add nodes with explicit coordinates (escape hatch — pixel-perfect templates only)
156
+ cnotes canvas bulk-add <canvasId> --notes '[{"noteId":"NOTE-1","x":100,"y":100},{"noteId":"NOTE-2","x":500,"y":100}]'
157
+ cnotes canvas add-edge <canvasId> --source <nodeId> --target <nodeId> --label "blocks"
158
+
159
+ # Create from template
160
+ cnotes canvas from-template sprint-retrospective --populate
161
+ ```
162
+
163
+ Available templates: `sprint-retrospective`, `swot-analysis`, `kanban-board`, `feature-prioritization`, `meeting-notes`, `product-roadmap`
164
+
165
+ ### Agent-run lifecycle
166
+
167
+ When an AI agent makes multiple canvas changes for a single user request, wrap the whole sequence in `cnotes canvas agent-run wrap`. The server captures auto-checkpoints around the work, clusters every mutation into a single revertable operation, and attaches the prompt as intent metadata.
168
+
169
+ ```bash
170
+ cnotes canvas agent-run wrap \
171
+ --canvas <canvasId> \
172
+ --prompt "Reorganize roadmap into Q1/Q2 clusters" \
173
+ -- bash -c '
174
+ cnotes canvas add-text "$CANVAS" --text "Q1" --x 100 --y 100
175
+ cnotes canvas add-edge "$CANVAS" --source <id1> --target <id2>
176
+ '
177
+ ```
178
+
179
+ The wrap form does begin → run-your-command → end automatically, even if your command fails. For details on the underlying `agent-run begin` / `end` pattern (used when shell-wrapping isn't possible) see `SKILL.md`.
180
+
181
+ ### Declarative layout (`cnotes canvas place`)
182
+
183
+ Most of the time you shouldn't be computing pixel coordinates by hand — agents and humans alike are bad at it. `cnotes canvas place` takes a layout document that describes **structure** (rows, columns, what's anchored to what) and the server measures every item, packs them with no overlaps, and inserts them in a single batch. The call is best-effort: per-item failures are reported in the response (HTTP 207) but successful items stay on the canvas.
184
+
185
+ Four building blocks:
186
+
187
+ - **`stack`** — items flow along one axis (`vertical` or `horizontal`), like CSS flexbox
188
+ - **`grid`** — N columns, items wrap to new rows, like CSS grid auto-flow
189
+ - **`anchor`** — place a sub-tree relative to an existing canvas node
190
+ - **`item`** — a leaf: `note`, `text`, `richtext`, `list`, or `canvas` (link)
191
+
192
+ Example — a richtext header above a 3-column grid of notes:
193
+
194
+ ```json
195
+ {
196
+ "root": {
197
+ "kind": "stack", "axis": "vertical", "gap": "medium",
198
+ "items": [
199
+ { "kind": "item", "type": "richtext",
200
+ "content": "# Goals\nQ2 commitments.", "size": "medium" },
201
+ { "kind": "grid", "columns": 3, "gap": "tight",
202
+ "items": [
203
+ { "kind": "item", "type": "note", "noteId": "GOAL-1" },
204
+ { "kind": "item", "type": "note", "noteId": "GOAL-2" },
205
+ { "kind": "item", "type": "note", "noteId": "GOAL-3" }
206
+ ] }
207
+ ]
208
+ }
209
+ }
210
+ ```
211
+
212
+ ```bash
213
+ cnotes canvas place <canvasId> --spec ./goals.json --json
214
+ ```
215
+
216
+ `gap` accepts `"tight"`, `"medium"`, `"spacious"`, or a raw pixel number. Edges between items can be added with a top-level `"edges"` array referencing item `key` fields. See [skills/cnotes/SKILL.md](skills/cnotes/SKILL.md) for the full DSL reference and more examples.
217
+
218
+ ## AI Integration
219
+
220
+ ### Claude Code (recommended)
221
+
222
+ The simplest path: run `npx @creator-notes/cnotes@latest init` and accept the "Install the Claude Code skill?" prompt. The wizard copies the skill into `~/.claude/skills/cnotes/SKILL.md` so every Claude Code session learns the full `cnotes` command reference automatically.
223
+
224
+ After that, Claude will use `cnotes` whenever you ask about notes, canvases, or workspace tasks — no further setup.
225
+
226
+ ### Claude Desktop (MCP Server)
227
+
228
+ Add CreatorNotes as a tool server so Claude Desktop can read and write your notes directly.
229
+
230
+ **1. Authenticate and select a workspace:**
231
+
232
+ ```bash
233
+ cnotes init
234
+ ```
235
+
236
+ **2. Generate the MCP config:**
237
+
238
+ ```bash
239
+ cnotes mcp setup --json
240
+ ```
241
+
242
+ **3. Copy the output into your Claude Desktop config file:**
243
+
244
+ | OS | Config path |
245
+ |----|-------------|
246
+ | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
247
+ | Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
248
+ | Linux | `~/.config/Claude/claude_desktop_config.json` |
249
+
250
+ The output looks like this — merge it into your existing config:
251
+
252
+ ```json
253
+ {
254
+ "mcpServers": {
255
+ "cnotes": {
256
+ "command": "node",
257
+ "args": ["/path/to/dist/mcp-server.js"],
258
+ "env": {
259
+ "CN_SERVER": "https://creatornotes.app",
260
+ "CN_TOKEN": "<your-token>",
261
+ "CN_WORKSPACE": "<your-workspace-id>"
262
+ }
263
+ }
264
+ }
265
+ }
266
+ ```
267
+
268
+ **4. Restart Claude Desktop.** The CreatorNotes MCP tools will appear in the tool picker.
269
+
270
+ ### Manual Skill Install
271
+
272
+ `cnotes init` installs the user-level skill (`~/.claude/skills/cnotes/SKILL.md`) for you. If you want to scope the skill to a single project instead:
273
+
274
+ ```bash
275
+ mkdir -p .claude/skills/cnotes
276
+ cp $(npm root -g)/@creator-notes/cnotes/skills/cnotes/SKILL.md .claude/skills/cnotes/SKILL.md
277
+ ```
278
+
279
+ ## Scripting
280
+
281
+ ```bash
282
+ # Chain commands with quiet mode (--quiet emits one display ID per line)
283
+ NOTE_ID=$(cnotes notes create --notes '{"key":"A","type":"Note","markdown":"# Quick note"}' -q)
284
+ cnotes canvas add-node <canvasId> --note "$NOTE_ID"
285
+
286
+ # JSON output for parsing
287
+ cnotes notes list --json | jq '.[0].displayId'
288
+
289
+ # Several interlinked notes with @key placeholders
290
+ cnotes notes create --json --notes '[
291
+ {"key":"A","type":"PainPoint","markdownFile":"./problem.md"},
292
+ {"key":"B","type":"Insight","markdown":"# Solution\nFixes [@A: Problem](relationship:references)."}
293
+ ]'
294
+ ```
295
+
296
+ ## Requirements
297
+
298
+ - Node.js >= 18
299
+ - A [CreatorNotes](https://creatornotes.app) account
300
+
301
+ ## License
302
+
303
+ MIT
package/dist/cn.d.ts ADDED
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export {};
3
+ //# sourceMappingURL=cn.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cn.d.ts","sourceRoot":"","sources":["../src/cn.ts"],"names":[],"mappings":""}
package/dist/cn.js ADDED
@@ -0,0 +1,124 @@
1
+ #!/usr/bin/env node
2
+ import { createRequire } from "node:module";
3
+ import { Command } from "commander";
4
+ const require = createRequire(import.meta.url);
5
+ const pkg = require("../package.json");
6
+ const CLI_VERSION = pkg.version;
7
+ import updateNotifier from "update-notifier";
8
+ import { refreshInstalledSkills } from "./lib/install-skill.js";
9
+ import { cnotesEnv } from "./lib/env.js";
10
+ import { registerAuthCommands } from "./commands/auth.js";
11
+ import { registerConfigCommands } from "./commands/config.js";
12
+ import { registerWorkspaceCommands } from "./commands/workspace.js";
13
+ import { registerNotesCommands } from "./commands/notes.js";
14
+ import { registerVersionsCommands } from "./commands/versions.js";
15
+ import { registerCanvasCommands } from "./commands/canvas.js";
16
+ import { registerRelationshipsCommands } from "./commands/relationships.js";
17
+ import { registerSearchCommands } from "./commands/search.js";
18
+ import { registerTimelineCommands } from "./commands/timeline.js";
19
+ import { registerTypesCommands } from "./commands/types.js";
20
+ import { registerMemoryCommands } from "./commands/memory.js";
21
+ import { registerFilesCommands } from "./commands/files.js";
22
+ import { registerMcpCommands } from "./commands/mcp.js";
23
+ import { registerInitCommand } from "./commands/init.js";
24
+ import { registerSchemaCommand } from "./commands/schema.js";
25
+ import { registerThemeCommands } from "./commands/theme.js";
26
+ import { registerOperationsCommands } from "./commands/operations.js";
27
+ import { registerClaudeHookCommand } from "./commands/claude-hook.js";
28
+ import { loadConfig, getServerConfig } from "./lib/auth-store.js";
29
+ const program = new Command();
30
+ program
31
+ .name("cnotes")
32
+ .description("CreatorNotes CLI — manage notes, canvases, and knowledge from the terminal")
33
+ .version(CLI_VERSION)
34
+ .option("--json", "Output raw JSON")
35
+ .option("-q, --quiet", "Minimal output (IDs only)")
36
+ .option("--fields <list>", "Project JSON output to these comma-separated top-level fields (e.g. displayId,title)")
37
+ .option("-w, --workspace <id>", "Override active workspace ID")
38
+ .option("--server <url>", "Override server URL");
39
+ program.addHelpText("after", `
40
+ Examples:
41
+ $ cnotes notes list --type Insight --json
42
+ $ cnotes notes get MEETING-12 PRD-3 IDEA-7
43
+ $ cnotes search semantic "user retention" --limit 5
44
+ $ cnotes canvas place <canvasId> --spec ./layout.json
45
+ $ cnotes notes list --fields displayId,title,type # trim output to chosen keys
46
+ $ cnotes schema --json # describe types, relationships, exit codes
47
+
48
+ Exit codes:
49
+ 0 ok 1 generic 2 auth 3 validation
50
+ 4 not-found 5 conflict 6 rate-limit 7 permission
51
+
52
+ Env vars:
53
+ CN_SERVER, CN_TOKEN, CN_WORKSPACE, CN_JSON=1
54
+ `);
55
+ // Register all command groups
56
+ registerInitCommand(program);
57
+ registerAuthCommands(program);
58
+ registerConfigCommands(program);
59
+ registerWorkspaceCommands(program);
60
+ registerNotesCommands(program);
61
+ registerVersionsCommands(program);
62
+ registerCanvasCommands(program);
63
+ registerRelationshipsCommands(program);
64
+ registerSearchCommands(program);
65
+ registerTimelineCommands(program);
66
+ registerTypesCommands(program);
67
+ registerMemoryCommands(program);
68
+ registerFilesCommands(program);
69
+ registerMcpCommands(program);
70
+ registerSchemaCommand(program);
71
+ registerThemeCommands(program);
72
+ registerOperationsCommands(program);
73
+ registerClaudeHookCommand(program);
74
+ // Default action: show help + first-run hint when invoked with no arguments
75
+ program.action(() => {
76
+ const config = loadConfig();
77
+ const sc = getServerConfig(config, config.currentServer);
78
+ if (!sc?.token) {
79
+ console.log('Tip: Run "cnotes init" to get started.\n');
80
+ }
81
+ program.help();
82
+ });
83
+ // ── Background maintenance (best-effort; never blocks or breaks a command) ──
84
+ // Skipped for the MCP server subcommand, which speaks JSON-RPC and must stay
85
+ // silent. Writes only to stderr so stdout stays clean for --json / piping.
86
+ const isMcpRun = process.argv.includes("mcp");
87
+ // Interactive humans get update notices and skill-refresh chatter; agents,
88
+ // pipes, and JSON consumers get silence. An update-check failure (e.g. an
89
+ // unwritable configstore dir) must never leak into a parsed stream, so we
90
+ // gate the whole maintenance block — not just its output — on this.
91
+ const isInteractive = process.stdout.isTTY &&
92
+ !process.argv.includes("--json") &&
93
+ cnotesEnv("JSON") !== "1" &&
94
+ !process.env.CI &&
95
+ !cnotesEnv("NO_UPDATE_CHECK") &&
96
+ !process.env.NO_UPDATE_NOTIFIER;
97
+ if (!isMcpRun) {
98
+ // Keep already-installed skills (Claude and/or Codex) in sync with the
99
+ // running CLI, so a plain `npm update` refreshes them without re-running
100
+ // `cnotes init`. The compare runs for everyone (it's cheap and silent); only the
101
+ // notice is interactive-only.
102
+ try {
103
+ const refreshed = refreshInstalledSkills();
104
+ if (refreshed.some((r) => r.installed) && isInteractive) {
105
+ process.stderr.write(`cnotes: refreshed the installed skill(s) to match CLI v${CLI_VERSION}.\n`);
106
+ }
107
+ }
108
+ catch {
109
+ /* ignore — never break a command over skill maintenance */
110
+ }
111
+ // Tell the user when a newer published version exists. Only on an
112
+ // interactive TTY: agent/JSON/CI runs must not see update chatter, and the
113
+ // npm check itself is skipped there so a configstore error can't surface.
114
+ if (isInteractive) {
115
+ try {
116
+ updateNotifier({ pkg }).notify({ isGlobal: true });
117
+ }
118
+ catch {
119
+ /* ignore — update checks are advisory */
120
+ }
121
+ }
122
+ }
123
+ program.parse();
124
+ //# sourceMappingURL=cn.js.map
package/dist/cn.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cn.js","sourceRoot":"","sources":["../src/cn.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,10 @@
1
+ import { Command } from "commander";
2
+ export declare function registerAuthCommands(program: Command): void;
3
+ export interface LoginResult {
4
+ email: string;
5
+ serverUrl: string;
6
+ }
7
+ export declare function browserLogin(serverUrl: string, json: boolean, options?: {
8
+ quiet?: boolean;
9
+ }): Promise<LoginResult>;
10
+ //# sourceMappingURL=auth.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAapC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyG3D;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5B,OAAO,CAAC,WAAW,CAAC,CA4FtB"}