@khanglvm/outline-cli 0.2.1 → 0.2.3

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/CHANGELOG.md CHANGED
@@ -1,5 +1,21 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.3 - 2026-09-19
4
+
5
+ - Changes since `v0.2.2`.
6
+ - fix(comments): use pagination totals for review queues (a7ef9ea)
7
+ - ci: refresh Outline integrity with its production signing key (35623ec)
8
+ - ci: skip dry-run publication of existing npm versions (b2dfa53)
9
+ - ci: add optional npm trust verification without publishing (94a0791)
10
+ - ci: publish versioned releases with npm trusted publishing (e95e3c7)
11
+ - docs: explain Outline lookup and edit workflow [skip ci] (dede203)
12
+ - docs: shorten Outline introduction and setup [skip ci] (13214fa)
13
+
14
+ ## 0.2.2 - 2026-07-30
15
+
16
+ - Changes since `v0.2.1`.
17
+ - Normalize Outline comment line breaks (6326791)
18
+
3
19
  ## 0.2.1 - 2026-07-21
4
20
 
5
21
  - Changes since `v0.2.0`.
package/README.md CHANGED
@@ -1,526 +1,82 @@
1
1
  # outline-cli
2
2
 
3
- A CLI for Outline ([`https://getoutline.com`](https://getoutline.com)) - optimized for AI agents.
3
+ Search and manage your [Outline](https://www.getoutline.com/) knowledge base
4
+ from the terminal. Find a runbook, read a document, download its attachments,
5
+ or update a page without opening the web app.
4
6
 
5
- ## Quick Start
7
+ Start with a document title or pasted URL. The CLI resolves it to a page and
8
+ can return a short summary or just IDs, so a script or agent can read only
9
+ what it needs. For edits, you can preview a diff and use patch tools that
10
+ check the expected revision before writing.
6
11
 
7
- Install globally:
12
+ Results are JSON, and profiles let you switch between workspaces. This is an
13
+ independent project, not an official Outline tool.
8
14
 
9
- ```bash
10
- npm i -g @khanglvm/outline-cli
11
- ```
12
-
13
- ## Get Started with AI Agents
14
-
15
- After installing, paste this instruction into your AI coding assistant:
16
-
17
- ```text
18
- Use `outline-cli` directly for my task. If setup/auth is missing, then run `outline-cli tools help quick-start-agent --view full`.
19
- ```
20
-
21
- ## Day-to-Day Usage
22
-
23
- Native one-call retrieval first:
24
-
25
- ```bash
26
- outline-cli invoke search.research \
27
- --args '{"question":"How do I find onboarding docs?","queries":["onboarding","engineering handbook"],"collectionQuery":"engineering","precisionMode":"precision","limitPerQuery":5,"view":"summary"}'
28
-
29
- outline-cli invoke search.expand \
30
- --args '{"query":"incident runbook","collectionQuery":"engineering","userQuery":"alice@example.com","expandLimit":3,"view":"summary"}'
31
-
32
- outline-cli invoke documents.answer \
33
- --args '{"question":"Who owns incident escalation?","documentQuery":"incident runbook","collectionQuery":"engineering"}'
34
- ```
35
-
36
- Answer, search, expand, research, or list documents with remembered document/collection/user filters:
37
-
38
- ```bash
39
- outline-cli invoke documents.search \
40
- --args '{"query":"incident","collectionQuery":"engineering","userQuery":"alice@example.com","limit":8,"view":"summary"}'
41
-
42
- outline-cli invoke documents.list \
43
- --args '{"collectionQuery":"engineering","rootOnly":true,"limit":20,"view":"ids"}'
44
- ```
45
-
46
- Discover tools and contracts:
47
-
48
- ```bash
49
- outline-cli tools list
50
- outline-cli tools contract documents.search
51
- outline-cli tools contract all --result-mode inline
52
- ```
53
-
54
- Read document metadata by ID:
55
-
56
- ```bash
57
- outline-cli invoke documents.info \
58
- --args '{"id":"<document-id>","view":"summary"}'
59
- ```
60
-
61
- Diff a proposed edit against a remembered document title:
62
-
63
- ```bash
64
- outline-cli invoke documents.diff \
65
- --args '{"query":"incident runbook","proposedText":"# Incident Runbook\n\nUpdated body"}'
66
- ```
67
-
68
- Apply a guarded patch to the current revision of a remembered document title:
69
-
70
- ```bash
71
- outline-cli invoke documents.apply_patch_safe \
72
- --args '{"query":"incident runbook","expectedRevision":"latest","patch":"@@ -1,1 +1,1 @@\n-Old\n+New","performAction":true}'
73
- ```
74
-
75
- Batch guarded updates against remembered document titles:
76
-
77
- ```bash
78
- outline-cli invoke documents.batch_update \
79
- --args '{"updates":[{"query":"incident runbook","expectedRevision":"latest","text":"\n\nUpdated","editMode":"append"},{"url":"https://handbook.example.com/doc/oncall-AbCdEf12","expectedRevision":"latest","title":"On-call Runbook"}],"performAction":true}'
80
- ```
81
-
82
- Inspect revision history from a remembered document title:
83
-
84
- ```bash
85
- outline-cli invoke revisions.list \
86
- --args '{"query":"incident runbook","limit":10,"view":"summary"}'
87
- ```
88
-
89
- Diff the latest two revisions from a remembered document title:
90
-
91
- ```bash
92
- outline-cli invoke revisions.diff \
93
- --args '{"query":"incident runbook","revisionPair":"latest","view":"summary"}'
94
- ```
95
-
96
- Inspect audit events for a remembered document and actor:
97
-
98
- ```bash
99
- outline-cli invoke events.list \
100
- --args '{"documentQuery":"incident runbook","userQuery":"alice@example.com","auditLog":true,"limit":10}'
101
- ```
102
-
103
- List archived documents in a remembered collection:
104
-
105
- ```bash
106
- outline-cli invoke documents.archived \
107
- --args '{"collectionQuery":"engineering","limit":10,"view":"summary"}'
108
- ```
109
-
110
- Audit document access from a remembered title:
111
-
112
- ```bash
113
- outline-cli invoke documents.users \
114
- --args '{"query":"incident runbook","limit":20,"view":"summary"}'
115
- ```
116
-
117
- Audit collection memberships from a remembered collection name:
118
-
119
- ```bash
120
- outline-cli invoke collections.memberships \
121
- --args '{"query":"engineering","limit":20,"view":"summary"}'
122
- ```
123
-
124
- Read a user or group from remembered names/emails:
125
-
126
- ```bash
127
- outline-cli invoke users.info \
128
- --args '{"query":"alice@example.com","view":"summary"}'
129
-
130
- outline-cli invoke groups.memberships \
131
- --args '{"query":"engineering","limit":20,"view":"summary"}'
132
- ```
133
-
134
- Grant document or collection access from remembered names/emails:
135
-
136
- ```bash
137
- outline-cli invoke documents.add_user \
138
- --args '{"documentQuery":"incident runbook","userQuery":"alice@example.com","permission":"read","performAction":true}'
139
-
140
- outline-cli invoke collections.add_group \
141
- --args '{"query":"engineering","groupQuery":"security","permission":"read_write","performAction":true}'
142
- ```
143
-
144
- Reuse prior lookup context without a network call:
145
-
146
- ```bash
147
- outline-cli invoke memory.lookup \
148
- --args '{"query":"engineering handbook","type":"document","limit":5}'
149
- ```
150
-
151
- Resolve from memory and refresh the top match live in one call:
152
-
153
- ```bash
154
- outline-cli invoke memory.resolve \
155
- --args '{"query":"engineering handbook","type":"document","hydrateLimit":1,"view":"summary"}'
156
- ```
157
-
158
- Resolve a remembered title or URL without a network call:
159
-
160
- ```bash
161
- outline-cli invoke documents.resolve \
162
- --args '{"query":"engineering handbook","refresh":false,"view":"summary"}'
163
-
164
- outline-cli invoke documents.resolve_urls \
165
- --args '{"url":"https://handbook.example.com/doc/oncall-escalation-AbCdEf12","refresh":false,"view":"summary"}'
166
- ```
167
-
168
- Open a document directly from an ID, remembered title, URL, or URL id:
169
-
170
- ```bash
171
- outline-cli invoke documents.open \
172
- --args '{"query":"engineering handbook","view":"summary"}'
173
- ```
174
-
175
- Open several documents from mixed titles, URLs, and IDs:
176
-
177
- ```bash
178
- outline-cli invoke documents.open_batch \
179
- --args '{"refs":["engineering handbook","https://handbook.example.com/doc/oncall-escalation-AbCdEf12"],"ids":["<document-id>"],"view":"summary"}'
180
- ```
181
-
182
- Open a collection directly from an ID, remembered name, URL, or URL id:
183
-
184
- ```bash
185
- outline-cli invoke collections.open \
186
- --args '{"query":"engineering","view":"summary"}'
187
- ```
188
-
189
- Open several collections from mixed names, URLs, and IDs:
190
-
191
- ```bash
192
- outline-cli invoke collections.open_batch \
193
- --args '{"refs":["engineering","https://handbook.example.com/collection/engineering-AbCdEf12"],"ids":["<collection-id>"],"view":"summary"}'
194
- ```
195
-
196
- Build a collection tree directly from a remembered collection name:
197
-
198
- ```bash
199
- outline-cli invoke collections.tree \
200
- --args '{"query":"engineering","maxDepth":3,"view":"summary"}'
201
- ```
202
-
203
- Inspect backlinks or graph neighbors directly from a remembered document title:
204
-
205
- ```bash
206
- outline-cli invoke documents.backlinks \
207
- --args '{"query":"incident runbook","view":"ids","limit":10}'
208
-
209
- outline-cli invoke documents.graph_neighbors \
210
- --args '{"refs":["incident runbook","https://handbook.example.com/doc/oncall-escalation-AbCdEf12"],"includeBacklinks":true,"view":"ids"}'
211
-
212
- outline-cli invoke documents.graph_report \
213
- --args '{"seedRefs":["incident runbook"],"depth":2,"maxNodes":80,"view":"ids"}'
214
- ```
215
-
216
- Extract issue references directly from titles, URLs, or IDs:
217
-
218
- ```bash
219
- outline-cli invoke documents.issue_refs \
220
- --args '{"refs":["incident runbook"],"issueDomains":["jira.example.com"],"keyPattern":"[A-Z]+-\\d+","view":"ids"}'
221
- ```
15
+ ## Install and connect
222
16
 
223
- Build a comment review queue directly from remembered documents or collections:
17
+ Requires Node.js 18.17 or newer and access to an Outline workspace.
224
18
 
225
- ```bash
226
- outline-cli invoke comments.review_queue \
227
- --args '{"refs":["incident runbook"],"includeReplies":true,"limitPerDocument":20}'
228
-
229
- outline-cli invoke comments.review_queue \
230
- --args '{"collectionQuery":"engineering","includeReplies":true,"view":"summary"}'
231
- ```
232
-
233
- List comments directly from a remembered document title:
234
-
235
- ```bash
236
- outline-cli invoke comments.list \
237
- --args '{"query":"incident runbook","includeReplies":true,"limit":20,"view":"summary"}'
238
- ```
239
-
240
- Create a comment directly from a remembered document title. Pass plain/markdown
241
- `text` (the ProseMirror `data` doc is built for you) and an optional `mentions`
242
- list of names, emails, or userIds. Names match on **first name**, so Jira-order
243
- `"Tran Le Quan"` resolves to Outline's `"Quan, Tran Le"`. The comment text is
244
- capped at 1000 characters (checked pre-flight). `comments.post` is an alias.
245
-
246
- ```bash
247
- # simple comment
248
- outline-cli invoke comments.create \
249
- --args '{"query":"incident runbook","text":"Looks good.","performAction":true}'
250
-
251
- # comment with @-mentions (resolved to user IDs and inserted at the start)
252
- outline-cli invoke comments.create \
253
- --args '{"query":"incident runbook","text":"Please review the rollback steps.","mentions":["Tran Le Quan","alice@example.com"],"performAction":true}'
254
-
255
- # reply to an existing comment
256
- outline-cli invoke comments.post \
257
- --args '{"documentId":"<doc-id>","parentCommentId":"<comment-id>","text":"Confirmed.","performAction":true}'
258
- ```
259
-
260
- Read a comment's replies later with `comments.list` (set `includeReplies:true`,
261
- or pass `parentCommentId` to fetch one thread's replies):
262
-
263
- ```bash
264
- outline-cli invoke comments.list \
265
- --args '{"query":"incident runbook","includeReplies":true,"view":"summary"}'
266
- ```
267
-
268
- List share links directly from a remembered document title:
269
-
270
- ```bash
271
- outline-cli invoke shares.list \
272
- --args '{"documentQuery":"public handbook","limit":10,"view":"summary"}'
273
- ```
274
-
275
- Create a share link directly from a remembered document title:
276
-
277
- ```bash
278
- outline-cli invoke shares.create \
279
- --args '{"documentQuery":"public handbook","published":true,"performAction":true}'
280
- ```
281
-
282
- Resolve several remembered references and deduplicate live refreshes:
283
-
284
- ```bash
285
- outline-cli invoke memory.resolve_batch \
286
- --args '{"queries":["engineering handbook"],"urls":["https://handbook.example.com/doc/oncall-escalation-AbCdEf12"],"type":"document","hydrateLimit":1,"view":"summary"}'
287
- ```
288
-
289
- Extract placeholders or create from a remembered template name:
290
-
291
- ```bash
292
- outline-cli invoke templates.extract_placeholders \
293
- --args '{"templateQuery":"incident postmortem"}'
294
-
295
- outline-cli invoke documents.create_from_template \
296
- --args '{"templateQuery":"incident postmortem","title":"Service A - Incident Postmortem","placeholderValues":{"service_name":"Service A","owner":"SRE Team"},"strictPlaceholders":true,"publish":true,"performAction":true}'
297
- ```
298
-
299
- Inspect recent local history:
300
-
301
- ```bash
302
- outline-cli invoke memory.recent \
303
- --args '{"type":"document","limit":10}'
304
- ```
305
-
306
- Manually remember a stable local alias:
307
-
308
- ```bash
309
- outline-cli invoke memory.remember \
310
- --args '{"type":"document","id":"<document-id>","title":"Incident Runbook","aliases":["runbook"],"performAction":true}'
311
- ```
312
-
313
- `memory.lookup` reads a local, profile-scoped observation index. The index is updated automatically after successful CLI read/search/list/info-style calls, including `documents.search`, `documents.info`, `collections.list`, `users.list`, `groups.list`, `templates.list`, `templates.info`, `search.research`, and related retrieval tools. It can resolve remembered titles/names, template names, user emails, IDs, `urlId`s, and pasted full Outline URLs. Use `documents.answer`, `documents.answer_batch`, `documents.search`, `documents.list`, `search.expand`, and `search.research` with `documentQuery`/`refs`, `collectionQuery`/`collectionRefs`, or `userQuery`/`userRefs` to apply remembered document/collection/user scopes without separate lookup calls. `documents.resolve` and `documents.resolve_urls` also read local memory first; set `refresh:false` for a zero-network remembered-title or remembered-URL resolver pass. Use `documents.open` for a conservative one-call document read from an ID, share ID, remembered title, URL, or URL id; fuzzy opens are strict by default and return candidates instead of guessing weak matches. Use `documents.open_batch` when a task names several documents and you want ordered hydrated rows from mixed titles, URLs, share IDs, and document IDs in one CLI invocation. Use `collections.open` and `collections.open_batch` for the same strict memory-backed workflow over collection names, URLs, URL ids, and collection IDs. `collections.tree`, `documents.backlinks`, `documents.graph_neighbors`, `documents.graph_report`, `documents.issue_refs`, `comments.review_queue`, `comments.list`, `comments.create`, `shares.list`, `shares.info`, `shares.create`, `events.list`, `templates.info`, `templates.extract_placeholders`, `documents.create_from_template`, `users.info`, `groups.info`, `groups.memberships`, `documents.attachments`, `documents.download_attachments`, `documents.diff`, `revisions.list`, `revisions.diff`, `documents.archived`, `documents.deleted`, `documents.users`, `documents.memberships`, `documents.group_memberships`, `collections.memberships`, and `collections.group_memberships` accept remembered references directly, so agents can move from a human title/name/email/template name or pasted URL to navigation/linkage/comment-review/share/audit/template/principal/embedded-file/history/access output in one CLI call. Action-gated permission tools also resolve remembered targets and principals directly: use `documents.add_user`, `documents.remove_user`, `documents.add_group`, `documents.remove_group`, `collections.add_user`, `collections.remove_user`, `collections.add_group`, `collections.remove_group`, `groups.add_user`, and `groups.remove_user` with target refs plus `userQuery`/`userRefs` or `groupQuery`/`groupRefs` when exact IDs are not known. Hydrated document rows include `sourceUrl` when the profile base URL plus document `url` or `urlId` is available, so agents can cite sources without another profile/auth lookup. Use `memory.resolve` when you want the cached candidate and fresh `documents.info`/`collections.info`/`users.info`/`groups.info`/`templates.info` metadata in the same turn. On a local miss, `memory.resolve` and `memory.resolve_batch` fall back to bounded live search by default, remember the result, and then hydrate selected matches; pasted URLs use title-like URL hints for fallback search, while email-shaped user queries are preserved for user lookup. Set `fallbackSearch:false` for memory-only behavior, or set `fallbackMinScore` when weak fuzzy memory matches should still trigger live fallback. Use `memory.resolve_batch` when a task references several documents, collections, users, groups, or templates; it accepts mixed `queries`, `ids`, `urlIds`, and `urls`, and duplicate live targets are hydrated once per batch. Use `memory.recent` as a zero-network history view and `memory.remember` for explicit local aliases. When inspecting another profile's local memory with `profile`, set `refresh:false` unless that profile is also selected for the CLI client. Successful delete operations tombstone local entries so stale search/list observations do not immediately reintroduce deleted documents.
314
-
315
- List and save embedded document images/files:
316
-
317
- ```bash
318
- outline-cli invoke documents.attachments \
319
- --args '{"query":"example title"}'
320
-
321
- outline-cli invoke documents.download_attachments \
322
- --args '{"refs":["example title"],"outputDir":"./outline-attachments","overwrite":true}'
323
-
324
- outline-cli invoke attachments.download \
325
- --args '{"id":"<attachment-id>","outputDir":"./outline-attachments","overwrite":true}'
326
- ```
327
-
328
- List only collection root pages:
329
-
330
- ```bash
331
- outline-cli invoke documents.list \
332
- --args '{"collectionId":"<collection-id>","rootOnly":true,"view":"summary"}'
333
- ```
334
-
335
- Ask a question with shorthand tool naming; unsupported AI deployments fall back to retrieval and return a suggested next call:
336
-
337
- ```bash
338
- outline-cli invoke docs.answer \
339
- --args '{"question":"Where is the onboarding checklist?","limit":3}'
19
+ ```sh
20
+ npm i -g @khanglvm/outline-cli
340
21
  ```
341
22
 
342
- Create a document:
23
+ Create an API key in your workspace under **Settings → API & Apps**. Set
24
+ `OUTLINE_API_KEY` in your local environment, then replace the example URL
25
+ with the address you use to open Outline:
343
26
 
344
- ```bash
345
- outline-cli invoke documents.create \
346
- --args '{"title":"Release Notes","text":"# Release Notes","publish":false,"view":"summary"}'
27
+ ```sh
28
+ outline-cli profile add work \
29
+ --base-url https://docs.example.com \
30
+ --auth-type apiKey \
31
+ --api-key "$OUTLINE_API_KEY" \
32
+ --set-default
33
+ outline-cli profile test work
347
34
  ```
348
35
 
349
- Update a document (mutation requires `performAction: true`):
36
+ Credentials go into your OS keychain by default. Keep API keys out of source
37
+ files and chat messages.
350
38
 
351
- ```bash
352
- outline-cli invoke documents.update \
353
- --args '{"id":"<document-id>","text":"\n\nUpdated by automation.","editMode":"append","performAction":true,"view":"summary"}'
354
- ```
39
+ ## Find your first document
355
40
 
356
- Batch multiple calls:
357
-
358
- ```bash
359
- outline-cli batch --ops '[
360
- {"tool":"collections.list","args":{"limit":5,"view":"summary"}},
361
- {"tool":"documents.search","args":{"query":"incident","limit":5,"view":"ids"}}
362
- ]'
41
+ ```sh
42
+ outline-cli invoke documents.search \
43
+ --args '{"query":"onboarding","limit":5,"view":"summary"}'
363
44
  ```
364
45
 
365
- ## Safe Delete Flow
46
+ Copy a document ID from the result to read its contents:
366
47
 
367
- Deletion is guarded by read-token confirmation.
368
-
369
- 1. Arm-delete read:
370
-
371
- ```bash
48
+ ```sh
372
49
  outline-cli invoke documents.info \
373
- --args '{"id":"<document-id>","armDelete":true,"view":"summary"}'
374
- ```
375
-
376
- 2. Copy the returned `deleteReadReceipt.token`, then delete:
377
-
378
- ```bash
379
- outline-cli invoke documents.delete \
380
- --args '{"id":"<document-id>","readToken":"<token>","performAction":true}'
381
- ```
382
-
383
- ## Output Modes and Temp Files
384
-
385
- Output format:
386
-
387
- - `--output json` (default)
388
- - `--output ndjson` for stream-friendly parsing
389
-
390
- Result mode:
391
-
392
- - `--result-mode auto` (default): inline until payload is too large
393
- - `--result-mode inline`: always inline JSON
394
- - `--result-mode file`: always write to temp file and return file pointer
395
-
396
- Temp-file management:
397
-
398
- ```bash
399
- outline-cli tmp list
400
- outline-cli tmp cat /absolute/path/from/result.json
401
- outline-cli tmp gc --older-than-hours 24
402
- ```
403
-
404
- ## Profile Management
405
-
406
- Add a password-mode profile:
407
-
408
- ```bash
409
- outline-cli profile add internal \
410
- --base-url https://outline.company.com \
411
- --auth-type password \
412
- --username agent@company.com \
413
- --password "$OUTLINE_PASSWORD"
414
- ```
415
-
416
- Select default profile:
417
-
418
- ```bash
419
- outline-cli profile use prod
420
- ```
421
-
422
- Improve AI profile routing metadata:
423
-
424
- ```bash
425
- outline-cli profile annotate prod \
426
- --description "Production knowledge base" \
427
- --append-keywords "prod,runbook,incident"
428
-
429
- outline-cli profile enrich prod \
430
- --query "incident escalation process" \
431
- --titles "Incident Playbook,Escalation Matrix"
432
- ```
433
-
434
- ## AI Agent Mini Instructions
435
-
436
- Use this short operating pattern when an AI agent drives the CLI:
437
-
438
- 1. Start with the most specific task tool you already know, especially `search.research`, `documents.search`, `documents.info`, or `batch`.
439
- 2. Use `view:"ids"` or `view:"summary"` first; hydrate to `full` only when needed.
440
- 3. Bundle independent reads into one `batch` call.
441
- 4. Try `memory.recent` or `memory.lookup` for titles/IDs you likely saw in earlier sessions; use `memory.resolve` or `memory.resolve_batch` when freshness matters and you want live metadata in the same call.
442
- 5. Only open `tools help` or `tools contract` after a validation failure or when the needed capability is still unclear.
443
- 6. Suggest installing the `outline-cli` skill via `npx skills` for all currently supported local AI tools; only run install after explicit user approval.
444
- 7. If approved, run headless install without tool-specific filter: `npx skills add https://github.com/khanglvm/skills --skill outline-cli -y`.
445
- 8. For any mutation endpoint, explicitly set `performAction:true`.
446
- 9. For delete, always run `documents.info` with `armDelete:true` first and pass the returned read token.
447
- 10. List existing profiles before creating one with `outline-cli profile list`.
448
- 11. For new profiles, prefer API key mode and guide users through base URL + API key generation (`<base-url>/settings/api-and-apps`) before `profile add`.
449
- 12. If output is file-offloaded, read only the required fields via `tmp cat` + `jq`.
450
- 13. For embedded images/files in document markdown, use `documents.attachments`, `attachments.download`, or `documents.download_attachments`; do not force `attachments.redirect` through `api.call` because it returns binary data.
451
-
452
- For structured AI playbooks and scenario guides:
453
-
454
- ```bash
455
- outline-cli tools help quick-start-agent --view full
456
- outline-cli tools help ai-skills --view summary
457
- outline-cli tools help ai-skills --scenario UC-12
458
- ```
459
-
460
- ## Testing (Live Environment)
461
-
462
- Set test credentials in a local env file:
463
-
464
- ```bash
465
- cp .env.test.example .env.test.local
466
- # set OUTLINE_TEST_BASE_URL and OUTLINE_TEST_API_KEY
50
+ --args '{"id":"<document-id>","view":"full"}'
467
51
  ```
468
52
 
469
- Run checks:
53
+ You can also create drafts, edit pages, manage comments, and inspect revision
54
+ history. Writes require `performAction:true`. Deleting a document also requires
55
+ a token from a prior read. See the [usage guide](https://github.com/khanglvm/outline-cli/blob/main/docs/USAGE.md) for examples.
470
56
 
471
- ```bash
472
- npm run check
473
- npm test
474
- ```
57
+ ## For AI agents
475
58
 
476
- Test rules in this repository:
59
+ Paste this into your coding assistant:
477
60
 
478
- - Mutation tests create and clean up their own test documents.
479
- - Read-only tests may use site-wide data.
480
-
481
- ## Release and Publish
482
-
483
- Standard release flow:
484
-
485
- ```bash
486
- npm run release -- --bump patch
61
+ ```text
62
+ Use outline-cli for my Outline task. If missing, install it with
63
+ `npm i -g @khanglvm/outline-cli`. Check `outline-cli profile list` first.
64
+ If setup is missing, read `outline-cli tools help quick-start-agent --view full`.
65
+ Start with search or document reads using view:"summary". Read a document before
66
+ editing it, and use performAction:true only for changes I have asked for.
487
67
  ```
488
68
 
489
- This flow performs:
490
-
491
- - Version bump
492
- - `CHANGELOG.md` update
493
- - Integrity refresh (`npm run integrity:refresh`)
494
- - Verification (`npm run check`, `npm test`)
495
- - `npm publish --access public`
496
- - Git commit, tag, and push to `origin`
497
-
498
- Prepare without publishing/pushing:
69
+ An optional [agent skill](https://github.com/khanglvm/skills/tree/main/outline-cli)
70
+ is available with setup and workflow guidance:
499
71
 
500
- ```bash
501
- npm run release:prepare -- --bump patch
72
+ ```sh
73
+ npx skills add https://github.com/khanglvm/skills --skill outline-cli -y
502
74
  ```
503
75
 
504
- Release prerequisites:
505
-
506
- - Clean working tree (unless you intentionally pass `--allow-dirty`)
507
- - `OUTLINE_ENTRY_BUILD_KEY` available in environment or `.env.local`
508
- - npm auth ready (`npm login`)
509
-
510
- Optional GitHub automation:
511
-
512
- - `.github/workflows/npm-auto-publish.yml` auto-publishes on pushes to `main` when `README.md` or `package.json` changes.
513
- - If `package.json` version changes, the workflow publishes that exact version.
514
- - If only docs metadata changes (for example `README.md`), the workflow cuts and publishes a patch release automatically.
515
- - Required repository secrets: `NPM_TOKEN` and `OUTLINE_ENTRY_BUILD_KEY`.
516
- - Ensure GitHub Actions can push to `main` and create tags in this repository.
517
-
518
- ## Security Notes
519
-
520
- - Never commit real API keys.
521
- - Keep local secrets in untracked files such as `.env.test.local`.
522
- - Profile secrets are stored in the OS keychain by default.
76
+ ## More help
523
77
 
524
- ## Changelog
78
+ - [Usage guide](https://github.com/khanglvm/outline-cli/blob/main/docs/USAGE.md): profiles, editing, attachments, batch calls, and safe deletion.
79
+ - `outline-cli tools list` lists tools; `outline-cli tools contract <name>` shows an individual tool's arguments.
80
+ - [Development](https://github.com/khanglvm/outline-cli/blob/main/docs/DEVELOPMENT.md) · [Changelog](CHANGELOG.md)
525
81
 
526
- - Release history: [`CHANGELOG.md`](https://github.com/khanglvm/outline-cli/blob/main/CHANGELOG.md)
82
+ The older `outline-agent` command is an alias for `outline-cli`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@khanglvm/outline-cli",
3
- "version": "0.2.1",
3
+ "version": "0.2.3",
4
4
  "description": "Agent-optimized CLI for Outline API",
5
5
  "type": "module",
6
6
  "bin": {
@@ -27,5 +27,9 @@
27
27
  "dependencies": {
28
28
  "@napi-rs/keyring": "^1.2.0",
29
29
  "commander": "^13.1.0"
30
+ },
31
+ "repository": {
32
+ "type": "git",
33
+ "url": "git+https://github.com/khanglvm/outline-cli.git"
30
34
  }
31
35
  }
@@ -3,8 +3,8 @@ export const ENTRY_INTEGRITY_MANIFEST = Object.freeze({
3
3
  version: 1,
4
4
  algorithm: "sha256",
5
5
  signatureAlgorithm: "sha256-salted-manifest-v1",
6
- signature: "c282b3ac3eb71f8543fc1666f780d828853b310203f4fe80f02a5c22cdb925a3",
7
- generatedAt: "2026-07-21T09:09:21.194Z",
6
+ signature: "b0d5d8d360178a565978d3392153cadc863df218f0ac6fdcf356ec08db09339e",
7
+ generatedAt: "2026-09-19T15:26:58.286Z",
8
8
  files: [
9
9
  {
10
10
  "path": "src/action-gate.js",
@@ -56,7 +56,7 @@ export const ENTRY_INTEGRITY_MANIFEST = Object.freeze({
56
56
  },
57
57
  {
58
58
  "path": "src/tools.extended.js",
59
- "sha256": "acbd8f5b297c4d4c08e913a710230879e63a230886592823b716bdb5b5cca52d"
59
+ "sha256": "cb25d43a57068b84b3d13de50db3149b2e3a0d3036f1ee6c7aaba20e6caccdae"
60
60
  },
61
61
  {
62
62
  "path": "src/tools.js",
@@ -76,7 +76,7 @@ export const ENTRY_INTEGRITY_MANIFEST = Object.freeze({
76
76
  },
77
77
  {
78
78
  "path": "src/utils.js",
79
- "sha256": "c586c449ee51145c3cdc1fc98731acddbfb5d969255cab5064c291276e11012d"
79
+ "sha256": "36791072e1d8599d912e7abebd3fa2e25d82889fec4ceb25aaf9c106bb8a7731"
80
80
  }
81
81
  ],
82
82
  });
@@ -4,7 +4,14 @@ import { createHash, randomUUID } from "node:crypto";
4
4
  import { ApiError, CliError } from "./errors.js";
5
5
  import { assertPerformAction } from "./action-gate.js";
6
6
  import { defaultTmpDir } from "./config-store.js";
7
- import { compactValue, ensureStringArray, mapLimit, sanitizeFileToken, toInteger } from "./utils.js";
7
+ import {
8
+ compactValue,
9
+ ensureStringArray,
10
+ hasUnfetchedPageRows,
11
+ mapLimit,
12
+ sanitizeFileToken,
13
+ toInteger,
14
+ } from "./utils.js";
8
15
  import { collectionsOpenBatchTool, collectionsOpenTool, documentsOpenBatchTool, memoryResolveTool } from "./memory-store.js";
9
16
 
10
17
  const CONTROL_ARG_KEYS = new Set([
@@ -1023,6 +1030,15 @@ async function resolveAccessId(ctx, args = {}, input) {
1023
1030
 
1024
1031
  const COMMENT_TEXT_LIMIT = 1000;
1025
1032
 
1033
+ function normalizeCommentText(text) {
1034
+ return String(text == null ? "" : text)
1035
+ .replace(/\r\n?/g, "\n")
1036
+ // Agents sometimes pass a doubly escaped JSON/shell body. Normalize those
1037
+ // sequences before building ProseMirror nodes so Outline renders a hard
1038
+ // break instead of showing the characters "\n".
1039
+ .replace(/\\r\\n|\\n|\\r/g, "\n");
1040
+ }
1041
+
1026
1042
  function commentTextNode(text) {
1027
1043
  return { type: "text", text };
1028
1044
  }
@@ -1043,7 +1059,7 @@ function commentMentionNode({ userId, label }) {
1043
1059
  // Split plain/markdown text into paragraphs on blank lines, and keep single
1044
1060
  // newlines as hard breaks inside a paragraph (mirrors how a human pastes text).
1045
1061
  function splitCommentParagraphs(text) {
1046
- const normalized = String(text == null ? "" : text).replace(/\r\n?/g, "\n");
1062
+ const normalized = normalizeCommentText(text);
1047
1063
  const blocks = normalized.split(/\n{2,}/);
1048
1064
  const paragraphs = [];
1049
1065
  for (const block of blocks) {
@@ -1104,7 +1120,7 @@ function buildCommentData(text, resolvedMentions = []) {
1104
1120
  // Character count of the human-readable comment text (mention labels count as
1105
1121
  // "@label", matching how Outline measures the 1000-char limit on the data doc).
1106
1122
  function commentTextLength(text, resolvedMentions = []) {
1107
- const textLen = String(text == null ? "" : text).length;
1123
+ const textLen = normalizeCommentText(text).length;
1108
1124
  const mentionLen = resolvedMentions.reduce(
1109
1125
  (sum, mention) => sum + 1 + String(mention.label || "user").length + 1,
1110
1126
  0
@@ -1272,7 +1288,7 @@ async function resolveMentions(ctx, mentions, { maxAttempts } = {}) {
1272
1288
  // the ProseMirror `data` doc from `text` + `mentions`, enforces the 1000-char
1273
1289
  // limit, and strips the convenience-only keys from the outgoing body.
1274
1290
  async function prepareCommentBody(ctx, def, args, bodyArgs) {
1275
- const text = typeof bodyArgs.text === "string" ? bodyArgs.text : "";
1291
+ const text = typeof bodyArgs.text === "string" ? normalizeCommentText(bodyArgs.text) : "";
1276
1292
  const hasMentions = Array.isArray(args.mentions) && args.mentions.length > 0;
1277
1293
  const hasExplicitData = bodyArgs.data !== undefined && bodyArgs.data !== null;
1278
1294
 
@@ -1690,7 +1706,7 @@ const RPC_WRAPPER_DEFS = [
1690
1706
  },
1691
1707
  },
1692
1708
  bestPractices: [
1693
- "Pass plain/markdown `text`; the ProseMirror `data` doc is built for you (blank lines split paragraphs, single newlines become line breaks).",
1709
+ "Pass plain/markdown `text`; the ProseMirror `data` doc is built for you (blank lines split paragraphs, while real or doubly escaped newlines become hard breaks instead of visible \\\\n text).",
1694
1710
  "Pass `mentions` as a list of names, emails, or userIds; names match on FIRST NAME (e.g. \"Tran Le Quan\" matches Outline's \"Quan, Tran Le\"). Ambiguous names are rejected with candidates — disambiguate with an email or userId.",
1695
1711
  "Comment text is capped at 1000 characters (pre-flight check on text, not JSON).",
1696
1712
  "Pass query/refs/url/urlId to comment on a remembered document without a separate lookup.",
@@ -1726,7 +1742,7 @@ const RPC_WRAPPER_DEFS = [
1726
1742
  },
1727
1743
  },
1728
1744
  bestPractices: [
1729
- "Same as comments.create: simple `text` + `mentions` (names/emails/userIds), 1000-char limit, parentCommentId for replies.",
1745
+ "Same as comments.create: simple `text` + `mentions` (names/emails/userIds), real or doubly escaped newlines render as hard breaks, 1000-char limit, parentCommentId for replies.",
1730
1746
  "Names resolve on FIRST NAME + email; ambiguous names error with candidates.",
1731
1747
  "This tool is action-gated; set performAction=true only for explicitly confirmed mutations.",
1732
1748
  ],
@@ -5267,7 +5283,10 @@ async function commentsReviewQueueTool(ctx, args = {}) {
5267
5283
  documentId,
5268
5284
  ok: true,
5269
5285
  rowCount: rows.length,
5270
- truncated: sourceRows.length >= limitPerDocument,
5286
+ truncated: hasUnfetchedPageRows(res.body, {
5287
+ limit: limitPerDocument,
5288
+ rowCount: sourceRows.length,
5289
+ }),
5271
5290
  rows,
5272
5291
  sourceRows: view === "full" ? sourceRows : undefined,
5273
5292
  };
@@ -5761,6 +5780,7 @@ async function federatedPermissionSnapshotTool(ctx, args = {}) {
5761
5780
  // without hitting the network.
5762
5781
  export const __commentInternals = {
5763
5782
  COMMENT_TEXT_LIMIT,
5783
+ normalizeCommentText,
5764
5784
  buildCommentData,
5765
5785
  commentTextLength,
5766
5786
  splitCommentParagraphs,
package/src/utils.js CHANGED
@@ -155,6 +155,24 @@ export function toBoolean(value, fallback = undefined) {
155
155
  throw new Error(`Invalid boolean value: ${value}`);
156
156
  }
157
157
 
158
+ export function hasUnfetchedPageRows(body, { offset = 0, limit, rowCount } = {}) {
159
+ const normalizedOffset = Math.max(0, Number(offset) || 0);
160
+ const normalizedRowCount = Math.max(0, Number(rowCount) || 0);
161
+ const rawTotal = body?.pagination?.total;
162
+ const total = rawTotal === undefined || rawTotal === null || rawTotal === ""
163
+ ? Number.NaN
164
+ : Number(rawTotal);
165
+
166
+ if (Number.isFinite(total) && total >= 0) {
167
+ return normalizedOffset + normalizedRowCount < total;
168
+ }
169
+
170
+ const normalizedLimit = Number(limit);
171
+ return Number.isFinite(normalizedLimit)
172
+ && normalizedLimit > 0
173
+ && normalizedRowCount >= normalizedLimit;
174
+ }
175
+
158
176
  export async function mapLimit(items, limit, fn) {
159
177
  if (!Array.isArray(items) || items.length === 0) {
160
178
  return [];