@clarionstack/notesia 0.1.0 → 0.2.0

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.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Notesia CLI
2
2
 
3
- Local CLI for reading, updating, and bulk-importing notes in Notesia through the desktop app bridge.
3
+ Local CLI for reading, searching, tagging, and bulk-importing notes in Notesia through the desktop app bridge. Includes AI knowledge base queries, quick capture to Inbox, and deep link navigation.
4
4
 
5
5
  ## Requirements
6
6
 
@@ -19,14 +19,53 @@ npm install -g @clarionstack/notesia
19
19
  ### Notes
20
20
 
21
21
  - `notesia get --id <id>|--supabase-id <uuid>|--title "<title>" [--json] [--with-meta]`
22
- - `notesia list [--limit <count>] [--format table|json]`
22
+ - `notesia list [--limit <count>] [--offset <n>] [--folder-id <id>] [--tag <tag>] [--format table|json]` *(use `--folder-id 0` for unfoldered root notes)*
23
23
  - `notesia store --title "<title>" [--tag <tag>]... [--folder-id <id>] [--content <text>]`
24
- - `notesia update --id <id>|... [--content <text>] [--title "<new title>"]`
25
- - `notesia append --id <id>|... [--content <text>]`
26
- - `notesia trash --id <id>|...`
24
+ - `notesia update --id <id>|--supabase-id <uuid>|--match-title "<title>" [--content <text>] [--title "<new title>"]`
25
+ - `notesia append --id <id>|--supabase-id <uuid>|--match-title "<title>" [--content <text>]`
26
+ - `notesia prepend --id <id>|--supabase-id <uuid>|--match-title "<title>" [--content <text>]`
27
+ - `notesia move --id <id>|--supabase-id <uuid>|--match-title "<title>" --folder-id <id>` *(use 0 for root)*
28
+ - `notesia trash --id <id>|--supabase-id <uuid>|--match-title "<title>"`
29
+ - `notesia capture --title "<title>" [--content <text>] [--tag <tag>]...`
30
+ - `notesia open --id <id>|--title "<title>"`
27
31
  - `notesia sync`
28
32
  - `notesia auth status [--format text|json]`
29
33
 
34
+ ### Folders
35
+
36
+ - `notesia folder list [--format table|json]`
37
+ - `notesia folder create --name "<name>" [--parent-id <id>] [--icon <icon>] [--format text|json]`
38
+ - `notesia folder rename --id <id> --name "<new>" [--format text|json]`
39
+ - `notesia folder move --id <id> --parent-id <id> [--format text|json]` *(use 0 for root)*
40
+ - `notesia folder delete --id <id> [--format text|json]` *(empty non-system folders only)*
41
+
42
+ ### MCP Server (External AI Apps)
43
+
44
+ - `notesia mcp` — Start a local stdio Model Context Protocol (MCP) server exposing note, folder, tag, search, and sync tools over the running desktop bridge:
45
+
46
+ ```json
47
+ {
48
+ "mcpServers": {
49
+ "notesia": {
50
+ "command": "notesia",
51
+ "args": ["mcp"]
52
+ }
53
+ }
54
+ }
55
+ ```
56
+
57
+ ### Search
58
+
59
+ - `notesia search <query> [--limit <n>] [--format text|json]`
60
+
61
+ Alias for `notesia kb search`. Full-text search across all notes by title and content.
62
+
63
+ ### Tags
64
+
65
+ - `notesia tags [--format text|json]` — List all tags with note counts
66
+ - `notesia tag add --id <id>|--supabase-id <uuid>|--match-title "<title>" --tag <tag> [--tag <tag>]...` — Add tags to a note
67
+ - `notesia tag remove --id <id>|--supabase-id <uuid>|--match-title "<title>" --tag <tag> [--tag <tag>]...` — Remove tags from a note
68
+
30
69
  ### Bulk Import
31
70
 
32
71
  ```
@@ -38,7 +77,7 @@ Recursively discovers files in a directory and imports them as notes into Notesi
38
77
  | Option | Description | Default |
39
78
  |---|---|---|
40
79
  | `<path>` | Source directory or file (required) | — |
41
- | `--ext <list>` | Comma-separated file extensions | `md,txt,pdf,docx,json` |
80
+ | `--ext <list>` | Comma-separated file extensions | `md,txt,html,htm,pdf,docx,json` |
42
81
  | `--folder <name>` | Target folder name (created if absent) | — |
43
82
  | `--tags <list>` | Comma-separated tags for all imported notes | — |
44
83
  | `--conflict <mode>` | `skip` or `overwrite` existing notes by title | `skip` |
@@ -47,7 +86,9 @@ Recursively discovers files in a directory and imports them as notes into Notesi
47
86
  | `--quiet` | Suppress stdout output | — |
48
87
  | `--verbose` | Print per-file progress to stderr | — |
49
88
 
50
- Supported file types: `.md`, `.txt`, `.html`, `.pdf`, `.docx`, `.json`.
89
+ Supported file types: `.md`, `.txt`, `.html`, `.htm`, `.pdf`, `.docx`, `.json`.
90
+
91
+ Markdown source is retained locally for exact workspace and export output. HTML imports keep the document body as editable rich text after scripts, styles, iframes, forms, event handlers, and unsafe URLs are removed.
51
92
 
52
93
  JSON imports are transformed into flattened key-path text (with truncation guards for very large arrays/strings) to improve embedding quality.
53
94
 
@@ -62,6 +103,20 @@ Notes exceeding 100,000 characters are automatically split into multiple parts.
62
103
 
63
104
  `kb ask` automatically reuses the same conversation in the same terminal session. Use `--conversation-id` only when you want to override/reset the session.
64
105
 
106
+ `kb context` is the CLI handoff path for external AI coding assistants: it returns
107
+ source context as JSON rather than generating an answer. Review or filter that JSON,
108
+ then provide it to your assistant with the task and ask the assistant to preserve the
109
+ source references instead of guessing beyond the supplied context. The in-app Knowledge
110
+ Base Inspector provides the same owner-oriented preview workflow, but does not push or
111
+ export directly to an assistant.
112
+
113
+ ### Deep Links
114
+
115
+ Open a note in the desktop app via URL scheme:
116
+
117
+ - `com.notesia.app://open?id=<id>` — Open by local ID
118
+ - `com.notesia.app://open?title=<title>` — Open by title
119
+
65
120
  ## Examples
66
121
 
67
122
  ### Basic note operations
@@ -77,6 +132,47 @@ notesia sync
77
132
  notesia auth status
78
133
  ```
79
134
 
135
+ ### Search, move, open, and capture
136
+
137
+ ```bash
138
+ # Full-text search
139
+ notesia search "meeting notes"
140
+ notesia search "meeting" --json | jq '.notes[].title'
141
+
142
+ # Move a note to a different folder
143
+ notesia move --id 12 --folder-id 3
144
+
145
+ # Open a note in the desktop app
146
+ notesia open --title "My Note"
147
+
148
+ # Quick capture to Inbox
149
+ notesia capture --title "Quick idea" --content "Look into this later"
150
+ ```
151
+
152
+ ### Prepend and pipe examples
153
+
154
+ ```bash
155
+ # Prepend content before existing note body
156
+ echo "Important: " | notesia prepend --id 5
157
+
158
+ # Capture from clipboard (macOS)
159
+ pbpaste | notesia capture --title "Clipboard"
160
+ ```
161
+
162
+ ### Tags
163
+
164
+ ```bash
165
+ # List all tags with usage counts
166
+ notesia tags
167
+ notesia tags --format json
168
+
169
+ # Add tags to a note
170
+ notesia tag add --id 42 --tag project --tag important
171
+
172
+ # Remove tags from a note
173
+ notesia tag remove --id 42 --tag draft
174
+ ```
175
+
80
176
  ### Bulk import
81
177
 
82
178
  ```bash
@@ -87,7 +183,7 @@ notesia import ~/Documents/notes
87
183
  notesia import ./project-docs --folder "Work" --tags "project,2026"
88
184
 
89
185
  # Import HTML, PDF, DOCX and JSON files too
90
- notesia import ./archive --ext md,txt,html,pdf,docx,json
186
+ notesia import ./archive --ext md,txt,html,htm,pdf,docx,json
91
187
 
92
188
  # Overwrite existing notes with the same title
93
189
  notesia import ./updated-notes --conflict overwrite
@@ -114,9 +210,12 @@ notesia kb search --query "project plan" --limit 10
114
210
  # Ask KB directly (searches notes and todos)
115
211
  notesia kb ask --query "what are my pending tasks?"
116
212
 
117
- # Load full context for AI prompt (returns JSON with full content)
213
+ # Load source context for a controlled external handoff (returns JSON with full content)
118
214
  notesia kb context --query "Q1 roadmap" --limit 5
119
215
 
216
+ # Save context for a trusted external assistant workflow
217
+ notesia kb context --query "How does folder sync work?" --limit 5 > notesia-context.json
218
+
120
219
  # Continue a KB conversation across calls
121
220
  notesia kb ask --query "what did I change yesterday?"
122
221
  notesia kb ask --query "and what about folder sync?"
package/bin/notesia.mjs CHANGED
@@ -4,25 +4,31 @@ import { fileURLToPath } from 'url';
4
4
  import { dirname, resolve } from 'path';
5
5
  import { runCli } from '../src/commands.mjs';
6
6
  import { runImport } from '../src/import.mjs';
7
+ import { runMcpServer } from '../src/mcp.mjs';
7
8
 
8
9
  const __dirname = dirname(fileURLToPath(import.meta.url));
9
10
  const require = createRequire(import.meta.url);
10
11
 
11
12
  const argv = process.argv.slice(2);
13
+ const { version } = require(resolve(__dirname, '../package.json'));
12
14
 
13
15
  // Handle version flag / command
14
16
  if (argv[0] === 'version' || argv[0] === '-v' || argv[0] === '--version') {
15
- const { version } = require(resolve(__dirname, '../package.json'));
16
17
  process.stdout.write(`notesia v${version}\n`);
17
18
  process.exit(0);
18
19
  }
19
20
 
20
- // Dispatch `notesia import` to the dedicated import handler
21
+ // Dispatch `notesia import` and `notesia mcp` to dedicated handlers
21
22
  if (argv[0] === 'import') {
22
23
  runImport(argv.slice(1)).catch((error) => {
23
24
  process.stderr.write(`${error?.message || 'notesia import failed'}\n`);
24
25
  process.exit(1);
25
26
  });
27
+ } else if (argv[0] === 'mcp') {
28
+ runMcpServer(argv.slice(1), { serverVersion: version }).catch((error) => {
29
+ process.stderr.write(`${error?.message || 'notesia mcp failed'}\n`);
30
+ process.exit(1);
31
+ });
26
32
  } else {
27
33
  runCli(argv).catch((error) => {
28
34
  const message = error?.message || 'notesia CLI failed';
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@clarionstack/notesia",
3
3
  "private": false,
4
- "version": "0.1.0",
4
+ "version": "0.2.0",
5
5
  "description": "Notesia desktop bridge CLI — read, write, and bulk-import notes",
6
6
  "type": "module",
7
7
  "files": [
package/src/commands.mjs CHANGED
@@ -7,15 +7,46 @@ import {
7
7
  printListResult,
8
8
  printRetrieveResult,
9
9
  printMutationResult,
10
+ printOpenResult,
10
11
  printAuthStatusResult,
11
12
  printKbResult,
13
+ printTagsResult,
14
+ printFolderListResult,
15
+ printFolderMutationResult,
12
16
  readInputContent as defaultReadInputContent,
13
17
  } from './io.mjs';
14
18
 
15
- const SUPPORTED_OPS = new Set(['get', 'list', 'store', 'update', 'append', 'sync', 'auth-status', 'kb-search', 'kb-folders', 'kb-context', 'kb-ask', 'trash']);
19
+ const SUPPORTED_OPS = new Set([
20
+ 'get',
21
+ 'list',
22
+ 'store',
23
+ 'update',
24
+ 'append',
25
+ 'prepend',
26
+ 'move',
27
+ 'open',
28
+ 'sync',
29
+ 'auth-status',
30
+ 'kb-search',
31
+ 'kb-folders',
32
+ 'kb-context',
33
+ 'kb-ask',
34
+ 'trash',
35
+ 'search',
36
+ 'capture',
37
+ 'tags',
38
+ 'tag-add',
39
+ 'tag-remove',
40
+ 'folder-list',
41
+ 'folder-create',
42
+ 'folder-rename',
43
+ 'folder-move',
44
+ 'folder-delete',
45
+ ]);
16
46
  const OP_ALIASES = new Map([
17
47
  ['retrieve', 'get'],
18
48
  ['storage', 'store'],
49
+ ['whoami', 'auth-status'],
19
50
  ]);
20
51
  const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
21
52
  const KB_SESSION_TTL_MS = 24 * 60 * 60 * 1000;
@@ -171,6 +202,42 @@ export function parseArgs(argv = []) {
171
202
  }
172
203
  }
173
204
 
205
+ if (rawOp === 'tag') {
206
+ const subcommand = args.shift();
207
+ if (!subcommand || subcommand === '--help' || subcommand === '-h') {
208
+ return { op: 'help' };
209
+ }
210
+ const tagOps = { add: 'tag-add', remove: 'tag-remove' };
211
+ if (!tagOps[subcommand]) {
212
+ throw new CliCommandError('INVALID_OP', `Unsupported tag command: ${subcommand}. Use 'tags' to list or 'tag add/remove'.`);
213
+ }
214
+ op = tagOps[subcommand];
215
+ }
216
+
217
+ if (rawOp === 'folder') {
218
+ const subcommand = args.shift();
219
+ if (!subcommand || subcommand === '--help' || subcommand === '-h') {
220
+ return { op: 'help' };
221
+ }
222
+ const folderOps = {
223
+ list: 'folder-list',
224
+ create: 'folder-create',
225
+ rename: 'folder-rename',
226
+ move: 'folder-move',
227
+ delete: 'folder-delete',
228
+ };
229
+ if (!folderOps[subcommand]) {
230
+ throw new CliCommandError('INVALID_OP', `Unsupported folder command: ${subcommand}. Use list, create, rename, move, or delete.`);
231
+ }
232
+ op = folderOps[subcommand];
233
+ }
234
+
235
+ if (rawOp === 'search') {
236
+ if (args.length > 0 && !args[0].startsWith('--')) {
237
+ args.unshift('--query', args.shift());
238
+ }
239
+ }
240
+
174
241
  if (!op || op === '--help' || op === '-h') {
175
242
  return { op: 'help' };
176
243
  }
@@ -184,9 +251,14 @@ export function parseArgs(argv = []) {
184
251
  id: null,
185
252
  supabaseId: null,
186
253
  title: null,
254
+ matchTitle: null,
255
+ name: null,
256
+ icon: null,
187
257
  folderId: null,
258
+ parentId: null,
188
259
  content: undefined,
189
260
  limit: null,
261
+ offset: null,
190
262
  threshold: null,
191
263
  withMeta: false,
192
264
  query: null,
@@ -223,6 +295,12 @@ export function parseArgs(argv = []) {
223
295
  continue;
224
296
  }
225
297
 
298
+ if (token === '--match-title') {
299
+ parsed.matchTitle = readFlagValue(args, i);
300
+ i += 1;
301
+ continue;
302
+ }
303
+
226
304
  if (token === '--folder-id') {
227
305
  parsed.folderId = Number(readFlagValue(args, i));
228
306
  if (!Number.isFinite(parsed.folderId)) {
@@ -251,6 +329,38 @@ export function parseArgs(argv = []) {
251
329
  continue;
252
330
  }
253
331
 
332
+ if (token === '--offset') {
333
+ const offset = Number(readFlagValue(args, i));
334
+ if (!Number.isFinite(offset) || offset < 0) {
335
+ throw new CliCommandError('INVALID_ARGS', '--offset must be a non-negative number');
336
+ }
337
+ parsed.offset = Math.floor(offset);
338
+ i += 1;
339
+ continue;
340
+ }
341
+
342
+ if (token === '--name') {
343
+ parsed.name = readFlagValue(args, i);
344
+ i += 1;
345
+ continue;
346
+ }
347
+
348
+ if (token === '--icon') {
349
+ parsed.icon = readFlagValue(args, i);
350
+ i += 1;
351
+ continue;
352
+ }
353
+
354
+ if (token === '--parent-id') {
355
+ const parentId = Number(readFlagValue(args, i));
356
+ if (!Number.isFinite(parentId) || parentId < 0) {
357
+ throw new CliCommandError('INVALID_ARGS', '--parent-id must be a non-negative number');
358
+ }
359
+ parsed.parentId = parentId;
360
+ i += 1;
361
+ continue;
362
+ }
363
+
254
364
  if (token === '--threshold') {
255
365
  const threshold = Number(readFlagValue(args, i));
256
366
  if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1) {
@@ -309,7 +419,12 @@ export function parseArgs(argv = []) {
309
419
  const selector = {};
310
420
  if (parsed.id !== null) selector.id = parsed.id;
311
421
  if (parsed.supabaseId) selector.supabase_id = parsed.supabaseId;
312
- if (parsed.title && op === 'get') selector.title = parsed.title;
422
+ const titleSelectorOps = new Set(['get', 'open', 'append', 'prepend', 'move', 'trash', 'tag-add', 'tag-remove']);
423
+ if (parsed.matchTitle) {
424
+ selector.title = parsed.matchTitle;
425
+ } else if (parsed.title && titleSelectorOps.has(op)) {
426
+ selector.title = parsed.title;
427
+ }
313
428
  if (Object.keys(selector).length > 0) parsed.selector = selector;
314
429
 
315
430
  return parsed;
@@ -321,16 +436,30 @@ function usageText() {
321
436
  '',
322
437
  'Commands:',
323
438
  ' get --id <id>|--supabase-id <uuid>|--title <title> [--json] [--with-meta]',
324
- ' list [--limit <count>] [--format table|json]',
439
+ ' list [--limit <count>] [--offset <n>] [--folder-id <id>] [--tag <tag>] [--format table|json]',
325
440
  ' store [--title <title>] [--tag <tag>]... [--folder-id <id>] [--content <text>]',
326
- ' update --id <id>|--supabase-id <uuid>|--title <title> [--content <text>] [--title <new>]',
327
- ' append --id <id>|--supabase-id <uuid>|--title <title> [--content <text>]',
328
- ' trash --id <id>|--supabase-id <uuid>|--title <title>',
441
+ ' capture [--title <title>] [--tag <tag>]... [--content <text>] (saves to Inbox)',
442
+ ' update --id <id>|--supabase-id <uuid>|--match-title <title> [--content <text>] [--title <new>]',
443
+ ' append --id <id>|--supabase-id <uuid>|--match-title <title> [--content <text>]',
444
+ ' prepend --id <id>|--supabase-id <uuid>|--match-title <title> [--content <text>]',
445
+ ' search <query>|--query <text> [--limit <n>] [--threshold <0-1>] [--format text|json]',
446
+ ' move --id <id>|--supabase-id <uuid>|--match-title <title> --folder-id <id> (0 = root)',
447
+ ' open --id <id>|--supabase-id <uuid>|--title <title>',
448
+ ' trash --id <id>|--supabase-id <uuid>|--match-title <title>',
449
+ ' tags [--format table|json]',
450
+ ' tag add --id <id>|--supabase-id <uuid>|--match-title <title> --tag <name> [--tag <name2>]...',
451
+ ' tag remove --id <id>|--supabase-id <uuid>|--match-title <title> --tag <name> [--tag <name2>]...',
452
+ ' folder list [--format table|json]',
453
+ ' folder create --name <name> [--parent-id <id>] [--icon <icon>] [--format text|json]',
454
+ ' folder rename --id <id> --name <new> [--format text|json]',
455
+ ' folder move --id <id> --parent-id <id> [--format text|json] (0 = root)',
456
+ ' folder delete --id <id> [--format text|json] (empty folders only)',
457
+ ' mcp (start stdio MCP server for external AI agents)',
329
458
  ' sync',
330
459
  ' auth status [--format text|json]',
331
460
  '',
332
461
  'Bulk Import:',
333
- ' import <path> [--ext md,txt,pdf,docx,json] [--folder <name>] [--tags <list>]',
462
+ ' import <path> [--ext md,txt,html,htm,pdf,docx,json] [--folder <name>] [--tags <list>]',
334
463
  ' [--conflict skip|overwrite] [--dry-run]',
335
464
  ' [--format text|json] [--quiet] [--verbose]',
336
465
  '',
@@ -370,10 +499,22 @@ function buildPayload(parsed, pipedContent) {
370
499
  };
371
500
  }
372
501
 
502
+ if (parsed.op === 'open') {
503
+ return { selector: requireSelector(parsed) };
504
+ }
505
+
373
506
  if (parsed.op === 'list') {
374
- return {
507
+ const payload = {
375
508
  limit: parsed.limit ?? 100,
509
+ offset: parsed.offset ?? 0,
376
510
  };
511
+ if (parsed.folderId !== null && parsed.folderId !== undefined) {
512
+ payload.folder_id = parsed.folderId === 0 ? null : parsed.folderId;
513
+ }
514
+ if (parsed.tags.length > 0) {
515
+ payload.tag = parsed.tags[0];
516
+ }
517
+ return payload;
377
518
  }
378
519
 
379
520
  if (parsed.op === 'sync') {
@@ -393,6 +534,14 @@ function buildPayload(parsed, pipedContent) {
393
534
  };
394
535
  }
395
536
 
537
+ if (parsed.op === 'capture') {
538
+ return {
539
+ title: parsed.title || undefined,
540
+ content: parsed.content ?? pipedContent ?? '',
541
+ tags: parsed.tags,
542
+ };
543
+ }
544
+
396
545
  if (parsed.op === 'update') {
397
546
  const content = parsed.content ?? pipedContent;
398
547
  const hasContent = content !== undefined;
@@ -424,6 +573,30 @@ function buildPayload(parsed, pipedContent) {
424
573
  };
425
574
  }
426
575
 
576
+ if (parsed.op === 'prepend') {
577
+ const content = parsed.content ?? pipedContent;
578
+ if (content === undefined || content === '') {
579
+ throw new CliCommandError(
580
+ 'MISSING_CONTENT',
581
+ 'Prepend requires non-empty --content or piped stdin'
582
+ );
583
+ }
584
+ return {
585
+ selector: requireSelector(parsed),
586
+ content,
587
+ };
588
+ }
589
+
590
+ if (parsed.op === 'move') {
591
+ if (parsed.folderId === null || parsed.folderId === undefined) {
592
+ throw new CliCommandError('MISSING_ARGS', '--folder-id is required for move (use 0 for root)');
593
+ }
594
+ return {
595
+ selector: requireSelector(parsed),
596
+ folder_id: parsed.folderId === 0 ? null : parsed.folderId,
597
+ };
598
+ }
599
+
427
600
  if (parsed.op === 'trash') {
428
601
  return { selector: requireSelector(parsed) };
429
602
  }
@@ -462,6 +635,75 @@ function buildPayload(parsed, pipedContent) {
462
635
  };
463
636
  }
464
637
 
638
+ if (parsed.op === 'search') {
639
+ if (!parsed.query) {
640
+ throw new CliCommandError('MISSING_ARGS', '--query is required for search');
641
+ }
642
+ return { query: parsed.query, limit: parsed.limit ?? 20, threshold: parsed.threshold ?? undefined };
643
+ }
644
+
645
+ if (parsed.op === 'tags') {
646
+ return {};
647
+ }
648
+
649
+ if (parsed.op === 'tag-add' || parsed.op === 'tag-remove') {
650
+ if (parsed.tags.length === 0) {
651
+ throw new CliCommandError('MISSING_ARGS', '--tag is required for tag add/remove');
652
+ }
653
+ return {
654
+ selector: requireSelector(parsed),
655
+ tags: parsed.tags,
656
+ };
657
+ }
658
+
659
+ if (parsed.op === 'folder-list') {
660
+ return {};
661
+ }
662
+
663
+ if (parsed.op === 'folder-create') {
664
+ if (!parsed.name || !parsed.name.trim()) {
665
+ throw new CliCommandError('MISSING_ARGS', '--name is required for folder create');
666
+ }
667
+ return {
668
+ name: parsed.name.trim(),
669
+ parent_id: parsed.parentId === null || parsed.parentId === undefined || parsed.parentId === 0 ? null : parsed.parentId,
670
+ ...(parsed.icon ? { icon: parsed.icon } : {}),
671
+ };
672
+ }
673
+
674
+ if (parsed.op === 'folder-rename') {
675
+ if (parsed.id === null || parsed.id === undefined) {
676
+ throw new CliCommandError('MISSING_ARGS', '--id is required for folder rename');
677
+ }
678
+ if (!parsed.name || !parsed.name.trim()) {
679
+ throw new CliCommandError('MISSING_ARGS', '--name is required for folder rename');
680
+ }
681
+ return {
682
+ id: parsed.id,
683
+ name: parsed.name.trim(),
684
+ };
685
+ }
686
+
687
+ if (parsed.op === 'folder-move') {
688
+ if (parsed.id === null || parsed.id === undefined) {
689
+ throw new CliCommandError('MISSING_ARGS', '--id is required for folder move');
690
+ }
691
+ if (parsed.parentId === null || parsed.parentId === undefined) {
692
+ throw new CliCommandError('MISSING_ARGS', '--parent-id is required for folder move (use 0 for root)');
693
+ }
694
+ return {
695
+ id: parsed.id,
696
+ parent_id: parsed.parentId === 0 ? null : parsed.parentId,
697
+ };
698
+ }
699
+
700
+ if (parsed.op === 'folder-delete') {
701
+ if (parsed.id === null || parsed.id === undefined) {
702
+ throw new CliCommandError('MISSING_ARGS', '--id is required for folder delete');
703
+ }
704
+ return { id: parsed.id };
705
+ }
706
+
465
707
  throw new CliCommandError('INVALID_OP', `Unsupported command: ${parsed.op} `);
466
708
  }
467
709
 
@@ -479,7 +721,7 @@ export async function runCli(argv = [], {
479
721
  return { ok: true, help: true };
480
722
  }
481
723
 
482
- const needsPipedInput = ['store', 'update', 'append'].includes(parsed.op) && parsed.content === undefined;
724
+ const needsPipedInput = ['store', 'update', 'append', 'prepend', 'capture'].includes(parsed.op) && parsed.content === undefined;
483
725
  const pipedContent = needsPipedInput ? await readInputContent() : undefined;
484
726
 
485
727
  const payload = buildPayload(parsed, pipedContent);
@@ -526,8 +768,16 @@ export async function runCli(argv = [], {
526
768
  format: parsed.format,
527
769
  writeStdout,
528
770
  });
529
- } else if (['kb-search', 'kb-folders', 'kb-context', 'kb-ask'].includes(parsed.op)) {
530
- printKbResult(parsed.op, response.data, { format: parsed.format, writeStdout });
771
+ } else if (parsed.op === 'open') {
772
+ printOpenResult(response.data, { format: parsed.format, writeStdout });
773
+ } else if (parsed.op === 'tags') {
774
+ printTagsResult(response.data, { format: parsed.format === 'text' ? 'table' : parsed.format, writeStdout });
775
+ } else if (parsed.op === 'folder-list') {
776
+ printFolderListResult(response.data, { format: parsed.format === 'text' ? 'table' : parsed.format, writeStdout });
777
+ } else if (['folder-create', 'folder-rename', 'folder-move', 'folder-delete'].includes(parsed.op)) {
778
+ printFolderMutationResult(response.data, { format: parsed.format, writeStdout });
779
+ } else if (['search', 'kb-search', 'kb-folders', 'kb-context', 'kb-ask'].includes(parsed.op)) {
780
+ printKbResult(parsed.op === 'search' ? 'kb-search' : parsed.op, response.data, { format: parsed.format, writeStdout });
531
781
  } else {
532
782
  printMutationResult(response.data, {
533
783
  format: parsed.format,