@clarionstack/notesia 0.1.0 → 0.1.1
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 +65 -1
- package/package.json +1 -1
- package/src/commands.mjs +95 -5
- package/src/io.mjs +38 -0
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Notesia CLI
|
|
2
2
|
|
|
3
|
-
Local CLI for reading,
|
|
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
|
|
|
@@ -23,10 +23,26 @@ npm install -g @clarionstack/notesia
|
|
|
23
23
|
- `notesia store --title "<title>" [--tag <tag>]... [--folder-id <id>] [--content <text>]`
|
|
24
24
|
- `notesia update --id <id>|... [--content <text>] [--title "<new title>"]`
|
|
25
25
|
- `notesia append --id <id>|... [--content <text>]`
|
|
26
|
+
- `notesia prepend --id <id>|... [--content <text>]`
|
|
27
|
+
- `notesia move --id <id>|... --folder-id <id>` *(use 0 for root)*
|
|
26
28
|
- `notesia trash --id <id>|...`
|
|
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
|
+
### Search
|
|
35
|
+
|
|
36
|
+
- `notesia search <query> [--limit <n>] [--format text|json]`
|
|
37
|
+
|
|
38
|
+
Alias for `notesia kb search`. Full-text search across all notes by title and content.
|
|
39
|
+
|
|
40
|
+
### Tags
|
|
41
|
+
|
|
42
|
+
- `notesia tags [--format text|json]` — List all tags with note counts
|
|
43
|
+
- `notesia tag add --id <id>|... --tag <tag> [--tag <tag>]...` — Add tags to a note
|
|
44
|
+
- `notesia tag remove --id <id>|... --tag <tag> [--tag <tag>]...` — Remove tags from a note
|
|
45
|
+
|
|
30
46
|
### Bulk Import
|
|
31
47
|
|
|
32
48
|
```
|
|
@@ -62,6 +78,13 @@ Notes exceeding 100,000 characters are automatically split into multiple parts.
|
|
|
62
78
|
|
|
63
79
|
`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
80
|
|
|
81
|
+
### Deep Links
|
|
82
|
+
|
|
83
|
+
Open a note in the desktop app via URL scheme:
|
|
84
|
+
|
|
85
|
+
- `com.notesia.app://open?id=<id>` — Open by local ID
|
|
86
|
+
- `com.notesia.app://open?title=<title>` — Open by title
|
|
87
|
+
|
|
65
88
|
## Examples
|
|
66
89
|
|
|
67
90
|
### Basic note operations
|
|
@@ -77,6 +100,47 @@ notesia sync
|
|
|
77
100
|
notesia auth status
|
|
78
101
|
```
|
|
79
102
|
|
|
103
|
+
### Search, move, open, and capture
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
# Full-text search
|
|
107
|
+
notesia search "meeting notes"
|
|
108
|
+
notesia search "meeting" --json | jq '.notes[].title'
|
|
109
|
+
|
|
110
|
+
# Move a note to a different folder
|
|
111
|
+
notesia move --id 12 --folder-id 3
|
|
112
|
+
|
|
113
|
+
# Open a note in the desktop app
|
|
114
|
+
notesia open --title "My Note"
|
|
115
|
+
|
|
116
|
+
# Quick capture to Inbox
|
|
117
|
+
notesia capture --title "Quick idea" --content "Look into this later"
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### Prepend and pipe examples
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
# Prepend content before existing note body
|
|
124
|
+
echo "Important: " | notesia prepend --id 5
|
|
125
|
+
|
|
126
|
+
# Capture from clipboard (macOS)
|
|
127
|
+
pbpaste | notesia capture --title "Clipboard"
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### Tags
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
# List all tags with usage counts
|
|
134
|
+
notesia tags
|
|
135
|
+
notesia tags --format json
|
|
136
|
+
|
|
137
|
+
# Add tags to a note
|
|
138
|
+
notesia tag add --id 42 --tag project --tag important
|
|
139
|
+
|
|
140
|
+
# Remove tags from a note
|
|
141
|
+
notesia tag remove --id 42 --tag draft
|
|
142
|
+
```
|
|
143
|
+
|
|
80
144
|
### Bulk import
|
|
81
145
|
|
|
82
146
|
```bash
|
package/package.json
CHANGED
package/src/commands.mjs
CHANGED
|
@@ -7,15 +7,18 @@ import {
|
|
|
7
7
|
printListResult,
|
|
8
8
|
printRetrieveResult,
|
|
9
9
|
printMutationResult,
|
|
10
|
+
printOpenResult,
|
|
10
11
|
printAuthStatusResult,
|
|
11
12
|
printKbResult,
|
|
13
|
+
printTagsResult,
|
|
12
14
|
readInputContent as defaultReadInputContent,
|
|
13
15
|
} from './io.mjs';
|
|
14
16
|
|
|
15
|
-
const SUPPORTED_OPS = new Set(['get', 'list', 'store', 'update', 'append', 'sync', 'auth-status', 'kb-search', 'kb-folders', 'kb-context', 'kb-ask', 'trash']);
|
|
17
|
+
const SUPPORTED_OPS = new Set(['get', 'list', 'store', 'update', 'append', 'prepend', 'move', 'open', 'sync', 'auth-status', 'kb-search', 'kb-folders', 'kb-context', 'kb-ask', 'trash', 'search', 'capture', 'tags', 'tag-add', 'tag-remove']);
|
|
16
18
|
const OP_ALIASES = new Map([
|
|
17
19
|
['retrieve', 'get'],
|
|
18
20
|
['storage', 'store'],
|
|
21
|
+
['whoami', 'auth-status'],
|
|
19
22
|
]);
|
|
20
23
|
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
24
|
const KB_SESSION_TTL_MS = 24 * 60 * 60 * 1000;
|
|
@@ -171,6 +174,24 @@ export function parseArgs(argv = []) {
|
|
|
171
174
|
}
|
|
172
175
|
}
|
|
173
176
|
|
|
177
|
+
if (rawOp === 'tag') {
|
|
178
|
+
const subcommand = args.shift();
|
|
179
|
+
if (!subcommand || subcommand === '--help' || subcommand === '-h') {
|
|
180
|
+
return { op: 'help' };
|
|
181
|
+
}
|
|
182
|
+
const tagOps = { add: 'tag-add', remove: 'tag-remove' };
|
|
183
|
+
if (!tagOps[subcommand]) {
|
|
184
|
+
throw new CliCommandError('INVALID_OP', `Unsupported tag command: ${subcommand}. Use 'tags' to list or 'tag add/remove'.`);
|
|
185
|
+
}
|
|
186
|
+
op = tagOps[subcommand];
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
if (rawOp === 'search') {
|
|
190
|
+
if (args.length > 0 && !args[0].startsWith('--')) {
|
|
191
|
+
args.unshift('--query', args.shift());
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
|
|
174
195
|
if (!op || op === '--help' || op === '-h') {
|
|
175
196
|
return { op: 'help' };
|
|
176
197
|
}
|
|
@@ -309,7 +330,7 @@ export function parseArgs(argv = []) {
|
|
|
309
330
|
const selector = {};
|
|
310
331
|
if (parsed.id !== null) selector.id = parsed.id;
|
|
311
332
|
if (parsed.supabaseId) selector.supabase_id = parsed.supabaseId;
|
|
312
|
-
if (parsed.title && op === 'get') selector.title = parsed.title;
|
|
333
|
+
if (parsed.title && (op === 'get' || op === 'open')) selector.title = parsed.title;
|
|
313
334
|
if (Object.keys(selector).length > 0) parsed.selector = selector;
|
|
314
335
|
|
|
315
336
|
return parsed;
|
|
@@ -323,9 +344,17 @@ function usageText() {
|
|
|
323
344
|
' get --id <id>|--supabase-id <uuid>|--title <title> [--json] [--with-meta]',
|
|
324
345
|
' list [--limit <count>] [--format table|json]',
|
|
325
346
|
' store [--title <title>] [--tag <tag>]... [--folder-id <id>] [--content <text>]',
|
|
347
|
+
' capture [--title <title>] [--tag <tag>]... [--content <text>] (saves to Inbox)',
|
|
326
348
|
' update --id <id>|--supabase-id <uuid>|--title <title> [--content <text>] [--title <new>]',
|
|
327
349
|
' append --id <id>|--supabase-id <uuid>|--title <title> [--content <text>]',
|
|
350
|
+
' prepend --id <id>|--supabase-id <uuid>|--title <title> [--content <text>]',
|
|
351
|
+
' search <query>|--query <text> [--limit <n>] [--threshold <0-1>] [--format text|json]',
|
|
352
|
+
' move --id <id>|--supabase-id <uuid>|--title <title> --folder-id <id> (0 = root)',
|
|
353
|
+
' open --id <id>|--supabase-id <uuid>|--title <title>',
|
|
328
354
|
' trash --id <id>|--supabase-id <uuid>|--title <title>',
|
|
355
|
+
' tags [--format table|json]',
|
|
356
|
+
' tag add --id <id>|... --tag <name> [--tag <name2>]...',
|
|
357
|
+
' tag remove --id <id>|... --tag <name> [--tag <name2>]...',
|
|
329
358
|
' sync',
|
|
330
359
|
' auth status [--format text|json]',
|
|
331
360
|
'',
|
|
@@ -370,6 +399,10 @@ function buildPayload(parsed, pipedContent) {
|
|
|
370
399
|
};
|
|
371
400
|
}
|
|
372
401
|
|
|
402
|
+
if (parsed.op === 'open') {
|
|
403
|
+
return { selector: requireSelector(parsed) };
|
|
404
|
+
}
|
|
405
|
+
|
|
373
406
|
if (parsed.op === 'list') {
|
|
374
407
|
return {
|
|
375
408
|
limit: parsed.limit ?? 100,
|
|
@@ -393,6 +426,14 @@ function buildPayload(parsed, pipedContent) {
|
|
|
393
426
|
};
|
|
394
427
|
}
|
|
395
428
|
|
|
429
|
+
if (parsed.op === 'capture') {
|
|
430
|
+
return {
|
|
431
|
+
title: parsed.title || undefined,
|
|
432
|
+
content: parsed.content ?? pipedContent ?? '',
|
|
433
|
+
tags: parsed.tags,
|
|
434
|
+
};
|
|
435
|
+
}
|
|
436
|
+
|
|
396
437
|
if (parsed.op === 'update') {
|
|
397
438
|
const content = parsed.content ?? pipedContent;
|
|
398
439
|
const hasContent = content !== undefined;
|
|
@@ -424,6 +465,30 @@ function buildPayload(parsed, pipedContent) {
|
|
|
424
465
|
};
|
|
425
466
|
}
|
|
426
467
|
|
|
468
|
+
if (parsed.op === 'prepend') {
|
|
469
|
+
const content = parsed.content ?? pipedContent;
|
|
470
|
+
if (content === undefined || content === '') {
|
|
471
|
+
throw new CliCommandError(
|
|
472
|
+
'MISSING_CONTENT',
|
|
473
|
+
'Prepend requires non-empty --content or piped stdin'
|
|
474
|
+
);
|
|
475
|
+
}
|
|
476
|
+
return {
|
|
477
|
+
selector: requireSelector(parsed),
|
|
478
|
+
content,
|
|
479
|
+
};
|
|
480
|
+
}
|
|
481
|
+
|
|
482
|
+
if (parsed.op === 'move') {
|
|
483
|
+
if (parsed.folderId === null || parsed.folderId === undefined) {
|
|
484
|
+
throw new CliCommandError('MISSING_ARGS', '--folder-id is required for move (use 0 for root)');
|
|
485
|
+
}
|
|
486
|
+
return {
|
|
487
|
+
selector: requireSelector(parsed),
|
|
488
|
+
folder_id: parsed.folderId === 0 ? null : parsed.folderId,
|
|
489
|
+
};
|
|
490
|
+
}
|
|
491
|
+
|
|
427
492
|
if (parsed.op === 'trash') {
|
|
428
493
|
return { selector: requireSelector(parsed) };
|
|
429
494
|
}
|
|
@@ -462,6 +527,27 @@ function buildPayload(parsed, pipedContent) {
|
|
|
462
527
|
};
|
|
463
528
|
}
|
|
464
529
|
|
|
530
|
+
if (parsed.op === 'search') {
|
|
531
|
+
if (!parsed.query) {
|
|
532
|
+
throw new CliCommandError('MISSING_ARGS', '--query is required for search');
|
|
533
|
+
}
|
|
534
|
+
return { query: parsed.query, limit: parsed.limit ?? 20, threshold: parsed.threshold ?? undefined };
|
|
535
|
+
}
|
|
536
|
+
|
|
537
|
+
if (parsed.op === 'tags') {
|
|
538
|
+
return {};
|
|
539
|
+
}
|
|
540
|
+
|
|
541
|
+
if (parsed.op === 'tag-add' || parsed.op === 'tag-remove') {
|
|
542
|
+
if (parsed.tags.length === 0) {
|
|
543
|
+
throw new CliCommandError('MISSING_ARGS', '--tag is required for tag add/remove');
|
|
544
|
+
}
|
|
545
|
+
return {
|
|
546
|
+
selector: requireSelector(parsed),
|
|
547
|
+
tags: parsed.tags,
|
|
548
|
+
};
|
|
549
|
+
}
|
|
550
|
+
|
|
465
551
|
throw new CliCommandError('INVALID_OP', `Unsupported command: ${parsed.op} `);
|
|
466
552
|
}
|
|
467
553
|
|
|
@@ -479,7 +565,7 @@ export async function runCli(argv = [], {
|
|
|
479
565
|
return { ok: true, help: true };
|
|
480
566
|
}
|
|
481
567
|
|
|
482
|
-
const needsPipedInput = ['store', 'update', 'append'].includes(parsed.op) && parsed.content === undefined;
|
|
568
|
+
const needsPipedInput = ['store', 'update', 'append', 'prepend', 'capture'].includes(parsed.op) && parsed.content === undefined;
|
|
483
569
|
const pipedContent = needsPipedInput ? await readInputContent() : undefined;
|
|
484
570
|
|
|
485
571
|
const payload = buildPayload(parsed, pipedContent);
|
|
@@ -526,8 +612,12 @@ export async function runCli(argv = [], {
|
|
|
526
612
|
format: parsed.format,
|
|
527
613
|
writeStdout,
|
|
528
614
|
});
|
|
529
|
-
} else if (
|
|
530
|
-
|
|
615
|
+
} else if (parsed.op === 'open') {
|
|
616
|
+
printOpenResult(response.data, { format: parsed.format, writeStdout });
|
|
617
|
+
} else if (parsed.op === 'tags') {
|
|
618
|
+
printTagsResult(response.data, { format: parsed.format === 'text' ? 'table' : parsed.format, writeStdout });
|
|
619
|
+
} else if (['search', 'kb-search', 'kb-folders', 'kb-context', 'kb-ask'].includes(parsed.op)) {
|
|
620
|
+
printKbResult(parsed.op === 'search' ? 'kb-search' : parsed.op, response.data, { format: parsed.format, writeStdout });
|
|
531
621
|
} else {
|
|
532
622
|
printMutationResult(response.data, {
|
|
533
623
|
format: parsed.format,
|
package/src/io.mjs
CHANGED
|
@@ -47,6 +47,18 @@ export function printRetrieveResult(result, {
|
|
|
47
47
|
writeStdout(String(result?.content ?? ''));
|
|
48
48
|
}
|
|
49
49
|
|
|
50
|
+
export function printOpenResult(result, {
|
|
51
|
+
format = 'text',
|
|
52
|
+
writeStdout = defaultWriteStdout,
|
|
53
|
+
} = {}) {
|
|
54
|
+
if (format === 'json') {
|
|
55
|
+
writeStdout(`${JSON.stringify(result ?? {}, null, 2)}\n`);
|
|
56
|
+
return;
|
|
57
|
+
}
|
|
58
|
+
const title = result?.title || 'Untitled';
|
|
59
|
+
writeStdout(`Opened: ${title} (id: ${result?.id ?? 'unknown'})\n`);
|
|
60
|
+
}
|
|
61
|
+
|
|
50
62
|
export function printMutationResult(result, {
|
|
51
63
|
format = 'text',
|
|
52
64
|
writeStdout = defaultWriteStdout,
|
|
@@ -153,6 +165,32 @@ export function printAuthStatusResult(result, {
|
|
|
153
165
|
writeStdout(`${lines.join('\n')}\n`);
|
|
154
166
|
}
|
|
155
167
|
|
|
168
|
+
export function printTagsResult(result, {
|
|
169
|
+
format = 'table',
|
|
170
|
+
writeStdout = defaultWriteStdout,
|
|
171
|
+
} = {}) {
|
|
172
|
+
if (format === 'json') {
|
|
173
|
+
writeStdout(`${JSON.stringify(result ?? { tags: [], total: 0 }, null, 2)}\n`);
|
|
174
|
+
return;
|
|
175
|
+
}
|
|
176
|
+
const tags = Array.isArray(result?.tags) ? result.tags : [];
|
|
177
|
+
if (tags.length === 0) {
|
|
178
|
+
writeStdout('No tags found.\n');
|
|
179
|
+
return;
|
|
180
|
+
}
|
|
181
|
+
const headers = ['ID', 'NAME', 'NOTES'];
|
|
182
|
+
const rows = tags.map((t) => [
|
|
183
|
+
formatCell(t.id),
|
|
184
|
+
formatCell(t.name),
|
|
185
|
+
formatCell(t.note_count),
|
|
186
|
+
]);
|
|
187
|
+
const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
|
|
188
|
+
const renderRow = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join(' ').trimEnd();
|
|
189
|
+
const lines = [renderRow(headers), widths.map((w) => '-'.repeat(w)).join(' '), ...rows.map(renderRow)];
|
|
190
|
+
writeStdout(`${lines.join('\n')}\n`);
|
|
191
|
+
if (result?.total != null) writeStdout(`Total: ${result.total}\n`);
|
|
192
|
+
}
|
|
193
|
+
|
|
156
194
|
export function printKbResult(op, result, {
|
|
157
195
|
format = 'text',
|
|
158
196
|
writeStdout = defaultWriteStdout,
|