@usehandout/cli 0.0.0 → 1.4.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.
Files changed (6) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +4 -0
  3. package/README.md +43 -0
  4. package/SKILL.md +308 -0
  5. package/handout.mjs +29094 -0
  6. package/package.json +37 -3
package/LICENSE ADDED
@@ -0,0 +1,202 @@
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright [yyyy] [name of copyright owner]
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.
package/NOTICE ADDED
@@ -0,0 +1,4 @@
1
+ Handout CLI and agent skill
2
+ Copyright 2026 Nate Pierce
3
+
4
+ This product is licensed under the Apache License, Version 2.0 (see LICENSE).
package/README.md ADDED
@@ -0,0 +1,43 @@
1
+ # @usehandout/cli
2
+
3
+ The `handout` command turns an `.html`, `.md` or `.pdf` file into a
4
+ [Handout](https://usehandout.com) link, with a chosen audience and a version history. It also ships
5
+ the agent skill (`SKILL.md`) that lets Claude Code, Codex and other terminal agents publish what
6
+ they make.
7
+
8
+ ```bash
9
+ npm install -g @usehandout/cli
10
+ handout login
11
+ handout publish report.html
12
+ ```
13
+
14
+ Requires Node.js 24 or later. Works on macOS, Linux and Windows.
15
+
16
+ ## Give your agent the skill
17
+
18
+ ```bash
19
+ handout skill install --agent claude # ~/.claude/skills/handout/SKILL.md
20
+ handout skill install --agent codex # ~/.agents/skills/handout/SKILL.md
21
+ handout skill install --dir <path> # any other agent's skills directory
22
+ ```
23
+
24
+ In Claude Code you can install the plugin instead: `/plugin marketplace add usehandout/handout`,
25
+ then `/plugin install handout@usehandout`. Use the plugin or `--agent claude`, not both.
26
+
27
+ ## Update
28
+
29
+ ```bash
30
+ npm install -g @usehandout/cli@latest
31
+ handout skill install --agent claude # again, for each agent you installed the skill for
32
+ ```
33
+
34
+ ## More
35
+
36
+ `handout --help` lists every command; `handout <command> --help` shows its flags. Every command
37
+ that lists, gets or searches accepts `--json`. The CLI talks to `https://usehandout.com` unless
38
+ `--host` or `HANDOUT_HOST` names another Handout site.
39
+
40
+ Issues and releases: [github.com/usehandout/handout](https://github.com/usehandout/handout).
41
+ Each version is published from that repository with npm provenance.
42
+
43
+ Copyright 2026 Nate Pierce. Licensed under the [Apache License 2.0](LICENSE); see NOTICE.
package/SKILL.md ADDED
@@ -0,0 +1,308 @@
1
+ ---
2
+ name: handout
3
+ description: Offer Handout after creating a finished user-facing HTML, Markdown or PDF document; publish when requested or approved, respecting account defaults and explicit audience choices. Update existing links, manage access and search published documents; supports --json.
4
+ ---
5
+
6
+ # Handout
7
+
8
+ Handout turns a file into a link. You give it an `.html`, `.md` or `.pdf` file and get back a URL that opens in a reader, with a chosen audience (only me, specific people, anyone with a password, or anyone with the link) and a version history behind it. The `handout` command publishes, updates, manages, searches and reports on those links. Every command that lists, gets or searches accepts `--json`, and every mutation with a stable response shape does too.
9
+
10
+ ## When to use this skill
11
+
12
+ After creating a finished, user-facing HTML, Markdown or PDF document, briefly offer to publish it with Handout unless the user has declined or asked for a file attachment only. Do not offer for routine source files, repository maintenance files, intermediate drafts, or secrets. Offering is not publishing: only publish when the user requests or approves it, including an explicit standing instruction to auto-publish eligible documents. Avoid repeating the offer after a decline.
13
+
14
+ Also use it when the user asks you to:
15
+
16
+ - share, publish or host a document that they or you produced, and give them a link;
17
+ - update a link they already have (a new version at the same URL);
18
+ - find something they published earlier, or something shared with them;
19
+ - change who can open a document (the audience), or take a link off;
20
+ - see aggregate reading activity or who explicitly acknowledged a document.
21
+
22
+ Do not use it when the file is secret and the user did not ask to share it, or when the user wants a file attachment rather than a link.
23
+
24
+ ## Install
25
+
26
+ Handout works with any agent that can read local instructions and run terminal commands. The CLI and its JSON output are the same for every agent; only installation and instruction discovery differ.
27
+
28
+ Install the CLI from npm. It needs Node 24 or later and works on macOS, Linux and Windows:
29
+
30
+ ```bash
31
+ npm install -g @usehandout/cli
32
+ handout --version
33
+ ```
34
+
35
+ Every version is published from the public repository `usehandout/handout` by its release workflow, with npm provenance: the package page on npmjs.com links the commit and the workflow run that built it.
36
+
37
+ Then make this skill available to your agent:
38
+
39
+ | Agent | How |
40
+ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
41
+ | Claude Code | In Claude Code, run `/plugin marketplace add usehandout/handout`, then `/plugin install handout@usehandout`. Without the plugin: `handout skill install --agent claude`. Use one of the two, not both. |
42
+ | Codex | `handout skill install --agent codex` (writes `~/.agents/skills/handout/SKILL.md`). |
43
+ | Another terminal agent | `handout skill install --dir <its skills directory>`. |
44
+
45
+ `handout skill install` copies the `SKILL.md` that ships with the installed CLI into `<skills directory>/handout/SKILL.md`; `--agent claude` uses `~/.claude/skills`. If the agent discovers skills automatically, start a new conversation after installation. Otherwise ask it to read that `SKILL.md` before using Handout. Installing the CLI does not itself make every agent load the skill.
46
+
47
+ The CLI talks to `https://usehandout.com` unless `--host` or `HANDOUT_HOST` names another Handout site.
48
+
49
+ **Staying up to date.** At most once a day the CLI prints `A newer handout CLI (<version>) is available; update it with: npm install -g @usehandout/cli@latest` on stderr; run that command when convenient, then `handout skill install` again for each agent you installed the skill for that way (a Claude Code plugin updates from `/plugin`). Exit code 3 with `no longer supported` means the installed CLI is too old for the host: run the same npm command, and do not set `HANDOUT_SKIP_VERSION_CHECK=1` without telling the user.
50
+
51
+ **Optional persistent preference.** Installing the skill does not edit any agent instructions file. Offer the user a separate, opt-in prompt to add a concise Handout section to their agent's active persistent instructions. Let them choose project-only or global scope; preserve existing content, update an existing Handout section instead of duplicating it, and show the resulting change. Never modify these files merely because installation succeeded. Suggested instruction:
52
+
53
+ ```text
54
+ After creating a finished, user-facing HTML, Markdown or PDF document, briefly offer to publish it through Handout. Skip routine source files, intermediate drafts, secrets, and repeated offers after I decline. Publish only when I request or approve it. Before publishing, read handout settings get --json and respect my saved defaults unless I explicitly override them. Do not change account settings without my instruction. For an existing handout, update the same link and preserve its audience.
55
+ ```
56
+
57
+ ## Sign in
58
+
59
+ `handout login` opens the user's browser once for a one-time sign-in; it needs a person at the keyboard. Credentials are kept per host in the operating system keychain, or in a private file under `~/.config/handout/` when no keychain is reachable (`--no-keychain` forces the file). `handout whoami` shows who you are signed in as and your workspaces; `handout logout` removes this host's credential.
60
+
61
+ When a command exits 2 with `Not signed in. Run: handout login`, ask the user to run `handout login` in their own terminal.
62
+
63
+ **Headless and CI.** Export `HANDOUT_REFRESH_TOKEN` (and optionally `HANDOUT_API_KEY`), obtained once with `handout login --print-refresh-token` on any machine. Treat it like a password: keep it in the runner's secret store, never in a repository or a log. `HANDOUT_HOST` points the CLI at another deployment (the default is `https://usehandout.com`).
64
+
65
+ ## Workspaces
66
+
67
+ Every document lives in a workspace, identified by a handle. `handout workspaces list` shows yours; `handout use <handle>` stores a default; `--workspace <handle>` (or `-w`) overrides it for one call. A user with exactly one workspace needs neither. A user with none creates one: `handout workspaces create <handle> --name "<name>"`.
68
+
69
+ **Account publishing defaults.** Before a publishing workflow, run `handout settings get --json`. It returns settings directly, including optional `defaultExposure`, labels, collection, source-download, notification and acknowledgment defaults. Read the live settings rather than storing a copy in agent memory; refresh them if the user changes them. `handout settings set default-exposure private` sets the Only me default, but only run settings mutations when the user asks.
70
+
71
+ Audience precedence is the user's explicit request, then their saved account default, then the system fallback (`private`, meaning only the document owner). With no explicit audience override, omit `--exposure` so the server applies current account defaults and verification fallbacks; do not hardcode `private` merely because it is common. Apply the same principle to other publishing flags. A saved `open` default is an explicit account preference, not a reason to change other documents' audiences. Explain the audience in the publish offer/result, request missing people/password details when needed, and never infer public access from vague wording such as "share." If settings cannot be read, report the failure rather than guessing. Updating an existing document preserves its existing audience instead of reapplying new-document defaults.
72
+
73
+ ## Command cheat-sheet
74
+
75
+ Every command takes the global flags `--workspace/-w`, `--host`, `--json`, `--quiet/-q`, `--yes/-y`, `--no-color` and `--help/-h`. A `<ref>` is a slug, `<handle>/<slug>`, `<handle>/c/<slug>` (a collection) or a Handout link.
76
+
77
+ | Command | Shortest useful form | Prints |
78
+ | ----------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
79
+ | `publish` | `handout publish report.html --title "Q3 report"` | the URL, one per file |
80
+ | `update` | `handout update q3-report report.md` | the same URL (new version) |
81
+ | `upsert` | `handout upsert notes.md --slug meeting-notes` | the URL (create or update) |
82
+ | `manage` | `handout manage q3-report --exposure people --people @acme.com` | one result line |
83
+ | `rename` | `handout rename q3-report q3-final` | the new URL |
84
+ | `move` | `handout move q3-report --to other-team` | the new URL |
85
+ | `trash` / `restore` / `purge` | `handout trash q3-report` | a confirmation line |
86
+ | `versions` | `handout versions list q3-report` | list, `source`, `restore`, `prune --keep <n>`, `diff <slug> <v1> <v2>` |
87
+ | `invite` | `handout invite q3-report --to a@b.com` | a confirmation line |
88
+ | `activity` / `audit` / `acks` | `handout activity q3-report` | views, history, acknowledgments |
89
+ | `list` | `handout list --label report` | url, audience, type, title per line; `--collection <slug>` filters to one collection |
90
+ | `labels` | `handout labels --json` | the workspace's suggested labels with usage counts |
91
+ | `get` | `handout get q3-report` | a key/value block |
92
+ | `search` | `handout search "quarterly"` | slug, where it matched, title |
93
+ | `source` | `handout source q3-report --out report.md` | the source file |
94
+ | `open` | `handout open q3-report` | the URL (no network call) |
95
+ | `read` | `handout read <ref>` | the rendered body or the file bytes |
96
+ | `collections` | `handout collections list` | `list`, `create`, `get`, `update`, `rename`, `delete`, `add`, `remove`, `reorder`, `activity`, `audit` |
97
+ | `proposals` | `handout proposals list q3-report` | `list`, `source`, `approve`, `reject` |
98
+ | `lease` | `handout lease claim q3-report` | `claim`, `release` |
99
+ | `comments` | `handout comments list <ref>` | `list`, `resolve`, `unresolve`, `delete` |
100
+ | `browse` | `handout browse --query roadmap` | documents and collections you can open |
101
+ | `workspaces` | `handout workspaces list` | `list`, `create`, `get`, `update`, `delete`, `restore` |
102
+ | `use` | `handout use acme` | `Default workspace: acme` |
103
+ | `login` / `logout` / `whoami` | `handout whoami` | identity, the account's document count, and workspaces |
104
+ | `settings` | `handout settings set theme dark` | `get`, `set <key> <value>` |
105
+ | `account` | `handout account delete` | `delete`, `restore` |
106
+ | `shared` / `library` | `handout shared` | what others shared; saved, followed, recent |
107
+ | `save` / `unsave` / `follow` / `unfollow` | `handout follow acme/q3-report` | a confirmation line |
108
+ | `usage` | `handout usage` | documents against your limit across all workspaces; storage per workspace and document (no `--workspace`) |
109
+ | `skill` | `handout skill install --agent codex` | `install`: copies this SKILL.md into an agent's skills directory |
110
+ | `help` | `handout help publish` | usage for a command |
111
+
112
+ `handout --version` prints the installed version. `handout <command> --help` prints that command's flags.
113
+
114
+ ## Labels and collections
115
+
116
+ **The rule: a label says what kind of document it is; a collection says what it belongs to.** `plan`, `spec`, `report`, `review`, `guide`, `notes`, `proposal` and `prototype` are labels. A project, a client, a quarter or a team (`handout`, `q3`, `contoso`) is a collection. Never use a status (`draft`, `final`) as a label.
117
+
118
+ Each workspace keeps a short, editable list of suggested labels. Before you label anything:
119
+
120
+ 1. Run `handout labels --json`. `suggested` is the list, each entry with the number of documents that carry it; `other` is labels in use that are not suggested.
121
+ 2. Pick from `suggested`, one or two per document. Reuse an existing spelling instead of a variant (`Plan` vs `plan`).
122
+ 3. If nothing on the list fits, **ask the user before inventing a label**. A free-text label is still accepted, but a guessed one becomes a permanent near-duplicate. When `suggested` is empty and `seedable` is true, the workspace already uses labels and has no list yet: do not invent one; tell the user they can adopt the suggested set on the workspace's settings page.
123
+ 4. When two or more documents share a project, client or period, **suggest a collection** (`handout collections create` and `collections add`) instead of a label, and ask before creating it. `handout list --collection <slug>` lists what is in one, and `handout get <slug>` shows the collections a document is in. Never label a document with its collection's name.
124
+
125
+ The user's account `defaultLabels` setting is separate: it stamps labels on every publish, and you never change it unless asked.
126
+
127
+ ## Publish what you just generated
128
+
129
+ 1. Write the file to disk first; the CLI publishes files, not stdin. Use the extension that matches the content (`.html`, `.md`, `.pdf`) or pass `--content-type`. Word (`.docx`) is not supported: export it as PDF, or convert it to Markdown or HTML first. A document may be up to 20 MB (the account's limit can be lower; the CLI reports it).
130
+ 2. Check that it isn't already published. If you published this artefact earlier in the conversation, use `handout update <slug> <file>`. Otherwise run `handout search "<words from its title>" --json`; when a match looks like the same document, confirm it with the user and update it instead of minting a duplicate.
131
+ 3. For rich HTML, run the grep checklist in the HTML authoring section and fix every hit, or publish `--interactive` when the document genuinely needs scripts and the user accepts the audience rule.
132
+ 4. Read the account publishing defaults as described above. Explicit audience requests override them: "just for me" is `--exposure private`; "the team" is `--exposure people --people @acme.com`; named people or a domain is `--people a@b.com --people @acme.com` (this implies `people`); "anyone with the link" is `--exposure open`; "with a password" is `--password -` (reads the password from stdin, so it stays out of the process list). Otherwise omit `--exposure` to honor the saved account default, falling back to `private` server-side. Never explicitly select `open` without a user instruction; an existing saved default is applied by the server, not rewritten as a hardcoded flag.
133
+ 5. Give it a short, real title: the document's own `<title>` or first heading, or `--title "<short title>"` when it has none (always for a PDF). The link is made from the title plus 8 random characters (`q3-report-k7f2qx9a`), so it reads well and still can't be guessed. Anyone who sees the link sees those title words, whatever the audience, so for a sensitive document ask the user for a neutral title. Leave out `--slug` unless the user asks for a specific link; then pass a short kebab-case one (`--slug q3-report`) and tell them a link like that can be guessed by anyone who knows the workspace, which matters for "anyone with the link" and password documents.
134
+ 6. Choose labels as described in Labels and collections (`handout labels --json`, pick from `suggested`, ask before inventing one). Run `handout publish <file> [--exposure ...] [--title ...] [--label ...] --json` and read `items[0].url`, `slug`, `version` and `warnings`.
135
+ 7. Report the URL to the user verbatim. If `warnings` is not empty, summarise each in one line and offer to fix the file and run `handout update <slug> <file>`.
136
+ 8. If the slug came back as 12 random characters (`aB3xY9zQ1pR7`), the document had no usable title. Rename it at once, before the link is shared, since a rename breaks the old link: `handout rename <slug> <kebab-case-title>-<8 random lowercase letters and digits>`. Give later versions a title.
137
+ 9. Remember the slug for the rest of the conversation. Later edits are `handout update <slug> <file>` (same link, new version), never a second `publish`, which mints a second link. `handout upsert <file> --slug <slug>` creates or updates in one call when you already know the slug.
138
+ Every update carries a change note by default: `--diff-summary "<one line on what changed>"`, written for the readers ("Added the Q4 numbers and fixed the totals table."), not as a commit message. Readers who come back see it as "What's new in v{n}", followers get it in their update email, and it is listed in the version history. Keep it to one sentence (it shows up to 280 characters; 500 is the hard limit), never paste the document or anything secret into it, and leave it out only when the user asks.
139
+ 10. On `402 plan_limit`, tell the user which limit was reached by name. The live-document limit counts the person's documents across all their workspaces (`handout usage` shows it). When the message says the limit is the document owner's, say so and that only the owner can change it. Tell the user it is a limit on the account and that the Handout team can raise it. Do not retry on another audience or with a smaller file unless the user asks.
140
+
141
+ For retry safety without `upsert`, generate one UUID per logical publish and pass it as `--idempotency-key` on every retry. `--dry-run` shows what would be published without sending anything.
142
+
143
+ ## Search Handout first before re-deriving
144
+
145
+ Before writing a document from scratch, before answering "where is the ...", and before any command that takes a slug the user did not give verbatim:
146
+
147
+ 1. Run `handout search "<two or more words from the request>" --json`. Use `handout list --json` (optionally `--label` for a kind of document or `--collection` for a project) for browse-shaped requests, and `handout library --json` or `handout shared --json` when the user is a reader rather than the publisher.
148
+ 2. Exactly one match: confirm the slug and title with the user in one line, then proceed. Several: present `slug - title (updated)` candidates and ask; never pick the first row silently. None: say so and offer to publish anew (or `collections create` for a collection).
149
+ 3. Resolve labels from `handout labels --json`, not by guessing: reuse the suggested spelling when the requested label is only a case or hyphenation variant (`Report` vs `report`), and when the request names a topic or project (`finance`, `Q3`) treat it as a collection, not a label. If no suggested label fits, ask the user before creating one.
150
+ 4. Resolve a collection by `handout collections list --json` and fuzzy-matching the user's words against `name`; confirm before `collections add` or `--collection`.
151
+ 5. If the user pasted a Handout link, pass it as the `<ref>` directly; the CLI accepts links and `<handle>/<slug>`.
152
+ 6. Ambiguity is always the user's call. A guessed slug is a `404`, and a guessed label is a permanent near-duplicate.
153
+
154
+ ## Audiences (--exposure)
155
+
156
+ | `--exposure` | In the app | Who can open it |
157
+ | ------------ | -------------------- | ----------------------------------------- |
158
+ | `private` | Only me | the publisher |
159
+ | `people` | Specific people | signed-in people on the list (`--people`) |
160
+ | `password` | Password | anyone with the link and the password |
161
+ | `open` | Anyone with the link | anyone with the link |
162
+
163
+ - `--people` takes email addresses and whole domains (`@contoso.example`), repeatable or comma-separated, at most 200 entries; it implies `--exposure people`. `--invite <email>` (at most 25) also emails the people a link.
164
+ - `--password <secret>` is 4 to 128 characters and implies `--exposure password`. Prefer `--password -` or the `HANDOUT_DOCUMENT_PASSWORD` variable over a literal argument.
165
+ - Link controls: `--expires <when>` (a date, or a duration such as `7d`, `24h`, `30m`), `--max-views <n>`, `--one-time`, and `--revoke` / `--restore` on `manage`.
166
+ - Labels: `--label <name>`, repeatable, at most 10 per document, 1 to 24 characters each. A label says what kind of document it is; pick from `handout labels --json`.
167
+ - Listing: new documents are unlisted (kept off the publisher's public page). Pass `--no-unlisted` ("show on my public page") only when the user asks for that.
168
+ - Other switches: `--unlisted`, `--notify-on-view`, `--request-ack` (not with `--exposure password` or `open`: only signed-in readers of a private or people document can acknowledge), `--allow-source-download`, `--allow-external-images`, and for PDFs `--view-only` and `--watermark`.
169
+
170
+ On `update`, access flags are refused: a new version keeps the document's audience. Change the audience with `handout manage`.
171
+
172
+ ## Changing a document later
173
+
174
+ - `handout update <slug> <file> --diff-summary "<what changed>"` publishes a new version at the same link with its change note (readers see it). `--expected-version <n>` makes it fail when someone else published in between.
175
+ - `handout manage <slug> <changes>` changes audience, people, password, expiry, labels and the other settings without touching the content. An empty value clears a list (`--label ""`).
176
+ - `handout rename <slug> <new-slug>` changes the link; the old link stops working.
177
+ - `handout move <slug> --to <handle>` moves the document to another workspace you belong to.
178
+ - `handout versions list <slug>`, `versions diff <slug> <v1> <v2>`, `versions restore <slug> <n>`, `versions source <slug> <n>`, `versions prune <slug> --keep <n>`.
179
+ - `handout trash <slug>` moves it to the trash; `handout restore <slug>` brings it back; `handout purge <slug>` deletes it for good (it asks first, or needs `--yes`).
180
+
181
+ ## Collections
182
+
183
+ A collection is a named, ordered set of documents with its own link and audience. Create one when the user wants several documents under one link: `handout collections create --name "Onboarding" --items welcome,handbook --exposure people --people @acme.com`. Edit the membership with `collections add <slug> <doc-slug>...`, `remove`, and `reorder` (which must list every item exactly once). `--collection <slug>` on `publish` or `upsert` appends the new documents to a collection after publishing; a failure there is a warning and does not change the exit code.
184
+
185
+ ## Seeing who read it
186
+
187
+ `handout activity <slug>` shows total, unique, anonymous and password views, the last 30 days, the viewers, who on a people list has not opened it yet, and who acknowledged it. `handout acks <slug>` lists acknowledgments, and `handout audit <slug>` the history of changes. If the full report is not available on the account, `handout list` still shows the view count.
188
+
189
+ ## --json guidance
190
+
191
+ Pass `--json` whenever you will parse the output, and never scrape the text output. One JSON document on one line is printed to stdout:
192
+
193
+ - `publish`, `update`, `upsert`: `{"items":[{...}]}` (add `"dryRun":true` with `--dry-run`);
194
+ - `list`, `collections list`, `shared`: `{"items":[...],"nextCursor"?:"..."}`;
195
+ - `versions diff`: `{"slug","from","to","diff"}`;
196
+ - `purge`: `{"slug","purged":true}`; `collections delete`: `{"slug","deleted":true}`; `use`: `{"defaultWorkspace":"<handle>"}`;
197
+ - `activity`: the activity record alone; everything else: the API response unchanged.
198
+
199
+ Errors under `--json` are one JSON line on stderr: `{"error":{"code":"<code>","message":"<message>","status"?:<http>,"details"?:{...},"requestId"?:"<id>"}}`. `code` is the API error code (`plan_limit`, `slug_taken`, ...) or one of `usage`, `file`, `config`, `auth`, `network`, `response_shape`, `cancelled`, `version_unsupported`. Exit codes: 0 success, 1 failure, 2 not signed in, 3 CLI too old. Commands with no `--json`: `login`, `logout`, `source`, `versions source`, `proposals source`, `read`, `open`, `help`.
200
+
201
+ stdout carries only the result; every notice, summary line and warning goes to stderr.
202
+
203
+ ## Error handling
204
+
205
+ | What you see | What to do |
206
+ | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
207
+ | exit 2, `Not signed in. Run: handout login` | Ask the user to run `handout login` in their terminal (it needs their browser). In CI, check `HANDOUT_REFRESH_TOKEN`. |
208
+ | exit 3, `no longer supported` | Run `npm install -g @usehandout/cli@latest`. Do not set `HANDOUT_SKIP_VERSION_CHECK` without telling the user. |
209
+ | `error.code = "plan_limit"` | Report which limit was reached (and that only the owner can change it when it is the document owner's); stop. |
210
+ | `email_unverified` | Ask the user to verify their email in Handout (it is also needed to publish `open` and for a second workspace), then run `handout login` again. |
211
+ | exit 2, `signed out everywhere` | The user ended all sessions from Settings. Ask them to run `handout login` again; retrying will not help. |
212
+ | `scheduled for deletion` (403) | The account has a pending deletion and every change is paused. Ask the user whether to run `handout account restore`. |
213
+ | `not_a_member` / `workspace_not_found` | The workspace belongs to someone else, or the handle is wrong: check `handout workspaces list`, `--workspace` or `handout use`. |
214
+ | `slug_taken` | Pick another `--slug`, or if it is the same document use `update` / `upsert`. |
215
+ | `version_mismatch` | Re-read with `handout get --json`, re-apply the edit, retry once with the new `--expected-version`. |
216
+ | `validation_failed` / `bad_request` | The message names the field; fix the flag. Do not retry blindly. |
217
+ | `rate_limited` | Wait at least 60 seconds. Do not loop; tell the user if it persists. |
218
+ | `gone` / `password_required` on a read | The link is off or needs a password; ask the user. |
219
+ | `network` / a timeout | Retry once after a pause, then report. The CLI already retried reads. |
220
+ | `response_shape` | The CLI is stale; run `npm install -g @usehandout/cli@latest`. |
221
+
222
+ ## Authoring HTML for the Handout reader
223
+
224
+ Handout shows HTML in a sanitized reader: a document that is not published `--interactive` has scripts and unsafe markup removed before it is shown. Author for this contract; it is derived from the sanitizer itself.
225
+
226
+ **Tags that render** (anything else is dropped; the text inside most dropped tags is kept):
227
+
228
+ - structure: `address` `article` `aside` `footer` `header` `hgroup` `main` `nav` `section` `div` `p` `blockquote` `hr` `pre`
229
+ - headings: `h1` `h2` `h3` `h4` `h5` `h6`
230
+ - lists: `ul` `ol` `li` `menu` `dl` `dt` `dd`
231
+ - inline: `a` `abbr` `b` `bdi` `bdo` `br` `cite` `code` `data` `dfn` `em` `i` `kbd` `mark` `q` `rb` `rp` `rt` `rtc` `ruby` `s` `samp` `small` `span` `strong` `sub` `sup` `time` `u` `var` `wbr`
232
+ - figures and tables: `figure` `figcaption` `table` `caption` `colgroup` `col` `thead` `tbody` `tfoot` `tr` `th` `td`
233
+ - other: `img` `style` `details` `summary` `input` `label`
234
+ - inline SVG: `svg` `g` `path` `rect` `circle` `ellipse` `line` `polyline` `polygon` `text` `tspan` `defs` `linearGradient` `radialGradient` `stop` `title` `marker`
235
+
236
+ **Attributes that survive**:
237
+
238
+ - on any element: `class` `id` `style` `title` `lang` `dir` `align` `width` `height` `colspan` `rowspan` `role`, any `aria-*`, any `data-*`
239
+ - on `a`: `href` `name` `target` `rel`
240
+ - on `img`: `src` `alt` `title` `width` `height`
241
+ - on `input`: `type` (only `radio` or `checkbox`) `name` `checked` `disabled` `id`
242
+ - on `label`: `for` `id`
243
+ - on SVG elements: `viewBox` `d` `fill` `stroke` `stroke-width` `stroke-linecap` `stroke-linejoin` `cx` `cy` `r` `rx` `ry` `x` `y` `x1` `y1` `x2` `y2` `points` `offset` `stop-color` `transform` `opacity` `width` `height` `text-anchor` `dominant-baseline` `alignment-baseline` `baseline-shift` `font-size` `font-weight` `font-family` `font-style` `text-decoration` `letter-spacing` `word-spacing` `dx` `dy` `rotate` `textLength` `lengthAdjust` `writing-mode` `fill-opacity` `fill-rule` `clip-rule` `stroke-opacity` `stroke-dasharray` `stroke-dashoffset` `stroke-miterlimit` `display` `visibility` `marker-start` `marker-mid` `marker-end` `markerWidth` `markerHeight` `refX` `refY` `orient` `markerUnits` `gradientUnits` `gradientTransform` `spreadMethod` `stop-opacity` `preserveAspectRatio`
244
+
245
+ On `fill`, `stroke` and `marker-*` a `url()` is kept only when it points into the document (`url(#gradient)`); an external `url(https://…)` removes the attribute.
246
+
247
+ **URL schemes** for links and images: `http`, `https`, `ftp`, `mailto`, `tel`, and protocol-relative `//`. `javascript:` is always dropped. `data:` is allowed on `img` `src` only. Every `http(s)` link is rewritten to open in a new tab with `rel="noopener noreferrer"`.
248
+
249
+ **Inline `style` attributes** keep only these properties, and no value containing `url(`, `expression(` or a backslash: `color` `background-color` `border` `border-color` `border-radius` `border-width` `border-style` `border-top` `border-right` `border-bottom` `border-left` `font-size` `font-weight` `font-style` `font-family` `text-align` `text-decoration` `text-transform` `line-height` `letter-spacing` `margin` `margin-top` `margin-right` `margin-bottom` `margin-left` `padding` `padding-top` `padding-right` `padding-bottom` `padding-left` `width` `height` `max-width` `min-width` `display` `vertical-align` `white-space` `opacity`. Put everything else in a `<style>` block.
250
+
251
+ **Stripped tags**: `script` `iframe` `object` `embed` `video` `audio` `canvas` `button` `textarea` `select` `form` `fieldset` `link` `meta` `head` `base` `foreignObject` `use`. Replacements: build interactivity from CSS; link out instead of embedding; style an `<a>` as a button; use radio or checkbox inputs with a `label` and `:checked` for toggles; put CSS in `<style>`.
252
+
253
+ **Stripped attributes**: every `on*` event handler (`onclick`, `onload`, ...), `tabindex`, `hidden`, `contenteditable`, and `open` on `details` (a `details` always renders collapsed). An `input` of any type other than `radio` or `checkbox` loses its `type`; do not use one.
254
+
255
+ **What a `<style>` block can and cannot do**: its rules apply as written, but any declaration that fetches something is neutralised (`url(...)`, `image-set(...)`, `@import`). Custom web fonts (`@font-face` with `url()`) and CSS background images therefore do not load. Use a system font stack, and put images in `<img>`.
256
+
257
+ **Rules of thumb**: interactivity is CSS-only. Tabs and accordions use `:checked`, never `:target`. `<details>` and `<summary>` work. Inline SVG shapes render. Images must be `https://` or `data:`; remote images load on `private`, `password` and `open` documents but are blocked by default on `workspace` and `people` documents unless you publish with `--allow-external-images` or inline them as `data:`.
258
+
259
+ **Layout constraints** (the reader grows the frame to the document height and never scrolls it internally): never use `vh`, `dvh` or `svh` for height; no `position: sticky` or `position: fixed`; no `:target`-driven interactivity. Headings `h1` to `h3` feed the reader's Contents menu.
260
+
261
+ **Grep-before-publish checklist.** Any hit must be reworked, or the document published `--interactive`:
262
+
263
+ ```
264
+ grep -Eno '<script|<iframe|<button|<textarea|<select|<form|<object|<embed|<video|<audio|<canvas|<link |<foreignObject|<use |on[a-z]+=|javascript:|href="#|[0-9]vh|position:\s*sticky|position:\s*fixed' your-file.html
265
+ ```
266
+
267
+ The `warnings` in the publish response are the server's view of the same rules; the checklist is the cheap pre-flight.
268
+
269
+ ## Interactive documents
270
+
271
+ `--interactive` (HTML only) serves the document with its scripts intact on an isolated content origin, inside a frame with `sandbox="allow-scripts allow-popups allow-forms"`. The frame never gets `allow-same-origin`, so the page cannot read Handout's cookies or storage. Sanitized (non-interactive) documents are the mirror image: a frame with `sandbox="allow-popups allow-same-origin allow-popups-to-escape-sandbox allow-top-navigation-by-user-activation"`, no scripts, and a script-less content security policy.
272
+
273
+ An interactive page may only talk to the origins you allow with `--connect-src <https-origin>` (repeatable, at most 8, each a bare `https://host[:port]` with no path); with none, it cannot make network requests. Some accounts can use `--interactive` only on `private` and `workspace` documents; wider audiences also need a verified email address (`402 plan_limit` or `403 email_unverified` otherwise). Tell the user that visitors run the author's code in their browser, in the sandbox above, before you publish an interactive document to a wide audience.
274
+
275
+ ## Examples
276
+
277
+ Each line shows the command and its expected output.
278
+
279
+ 1. `handout publish report.html` prints `https://handout.app/acme/q3-report-k7f2qx9a` (the link comes from the document's title, `Q3 report`).
280
+ 2. `handout publish report.md --exposure open --title "Q3 report" --label report --json` prints `{"items":[{"file":"report.md","handle":"acme","slug":"...","id":"...","url":"...","exposure":"open","version":1,...}]}`.
281
+ 3. `handout publish deck.pdf --people vicki@contoso.example --people @contoso.example --invite vicki@contoso.example` prints the URL (stderr: `published acme/... v1 pdf 2.3 MB people`).
282
+ 4. `handout publish spec.html --exposure password --password - < pw.txt` prints the URL.
283
+ 5. `handout update q3-report report.md --diff-summary "Added the Q4 numbers."` prints the same URL (stderr: `updated acme/q3-report v2 ...`); returning readers see "What's new in v2: Added the Q4 numbers."
284
+ 6. `handout upsert notes.md --slug meeting-notes --expected-version 3` prints the URL, or exits 1 with `Version conflict (409) ...`.
285
+ 7. `handout manage q3-report --exposure people --people @acme.com --label "" --expires 7d` prints `q3-report: people, expires: 2026-11-05T17:03:00.000Z`.
286
+ 8. `handout search "quarterly" --json` prints `{"query":"quarterly","items":[...]}`.
287
+ 9. `handout collections create --name "Onboarding" --items welcome,handbook --exposure people --people @acme.com` prints `https://handout.app/acme/c/onboarding-m4w8r2zt`.
288
+ 10. `handout versions diff q3-report 2 3` prints a unified diff.
289
+
290
+ ## Environment variables
291
+
292
+ | Variable | Effect |
293
+ | ------------------------------ | ------------------------------------------------------------------------------ |
294
+ | `HANDOUT_HOST` | The Handout origin to talk to (default `https://usehandout.com`) |
295
+ | `HANDOUT_REFRESH_TOKEN` | Headless credential; overrides the stored one. Treat as a password |
296
+ | `HANDOUT_API_KEY` | Firebase web API key to use with `HANDOUT_REFRESH_TOKEN` |
297
+ | `HANDOUT_WORKSPACE` | Default workspace handle for the invocation (below `--workspace`) |
298
+ | `HANDOUT_DOCUMENT_PASSWORD` | Document or collection password when `--password` is absent; never printed |
299
+ | `HANDOUT_NO_KEYCHAIN=1` | Skip the OS keychain, as `--no-keychain` does |
300
+ | `HANDOUT_SKILL_SOURCE` | The `SKILL.md` that `handout skill install` copies (default: the packaged one) |
301
+ | `HANDOUT_SKIP_VERSION_CHECK=1` | Bypass the minimum-version gate; tell the user if you set it |
302
+ | `NO_COLOR` | Disables colour |
303
+
304
+ Precedence for every setting: flag, then environment, then the local config file, then the account setting, then the default.
305
+
306
+ ## Deliberate limits
307
+
308
+ The CLI never performs a reader-side act that attests to a human reading or asking: it cannot acknowledge a document, request access, record a view, report a document or post a comment, because a script doing so would falsify the publisher's analytics and read receipts. It does not mint interactive URLs (a browser concern; `handout read` returns the sanitized body). If the user wants one of these, tell them to do it in the Handout app.