@usehandout/cli 0.0.0 → 1.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +202 -0
- package/NOTICE +4 -0
- package/README.md +43 -0
- package/SKILL.md +294 -0
- package/handout.mjs +28815 -0
- 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
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,294 @@
|
|
|
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 finance` | url, audience, type, title per line |
|
|
90
|
+
| `get` | `handout get q3-report` | a key/value block |
|
|
91
|
+
| `search` | `handout search "quarterly"` | slug, where it matched, title |
|
|
92
|
+
| `source` | `handout source q3-report --out report.md` | the source file |
|
|
93
|
+
| `open` | `handout open q3-report` | the URL (no network call) |
|
|
94
|
+
| `read` | `handout read <ref>` | the rendered body or the file bytes |
|
|
95
|
+
| `collections` | `handout collections list` | `list`, `create`, `get`, `update`, `rename`, `delete`, `add`, `remove`, `reorder`, `activity`, `audit` |
|
|
96
|
+
| `proposals` | `handout proposals list q3-report` | `list`, `source`, `approve`, `reject` |
|
|
97
|
+
| `lease` | `handout lease claim q3-report` | `claim`, `release` |
|
|
98
|
+
| `comments` | `handout comments list <ref>` | `list`, `resolve`, `unresolve`, `delete` |
|
|
99
|
+
| `browse` | `handout browse --query roadmap` | documents and collections you can open |
|
|
100
|
+
| `workspaces` | `handout workspaces list` | `list`, `create`, `get`, `update`, `delete`, `restore` |
|
|
101
|
+
| `use` | `handout use acme` | `Default workspace: acme` |
|
|
102
|
+
| `login` / `logout` / `whoami` | `handout whoami` | identity, the account's document count, and workspaces |
|
|
103
|
+
| `settings` | `handout settings set theme dark` | `get`, `set <key> <value>` |
|
|
104
|
+
| `account` | `handout account delete` | `delete`, `restore` |
|
|
105
|
+
| `shared` / `library` | `handout shared` | what others shared; saved, followed, recent |
|
|
106
|
+
| `save` / `unsave` / `follow` / `unfollow` | `handout follow acme/q3-report` | a confirmation line |
|
|
107
|
+
| `usage` | `handout usage` | documents against your limit across all workspaces; storage per workspace and document (no `--workspace`) |
|
|
108
|
+
| `skill` | `handout skill install --agent codex` | `install`: copies this SKILL.md into an agent's skills directory |
|
|
109
|
+
| `help` | `handout help publish` | usage for a command |
|
|
110
|
+
|
|
111
|
+
`handout --version` prints the installed version. `handout <command> --help` prints that command's flags.
|
|
112
|
+
|
|
113
|
+
## Publish what you just generated
|
|
114
|
+
|
|
115
|
+
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).
|
|
116
|
+
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.
|
|
117
|
+
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.
|
|
118
|
+
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.
|
|
119
|
+
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.
|
|
120
|
+
6. Run `handout publish <file> [--exposure ...] [--title ...] [--label ...] --json` and read `items[0].url`, `slug`, `version` and `warnings`.
|
|
121
|
+
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>`.
|
|
122
|
+
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.
|
|
123
|
+
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.
|
|
124
|
+
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.
|
|
125
|
+
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.
|
|
126
|
+
|
|
127
|
+
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.
|
|
128
|
+
|
|
129
|
+
## Search Handout first before re-deriving
|
|
130
|
+
|
|
131
|
+
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:
|
|
132
|
+
|
|
133
|
+
1. Run `handout search "<two or more words from the request>" --json`. Use `handout list --json` (optionally `--label`) for browse-shaped requests, and `handout library --json` or `handout shared --json` when the user is a reader rather than the publisher.
|
|
134
|
+
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).
|
|
135
|
+
3. Resolve labels the same way: collect the union of `labels` from `handout list --json` and reuse an existing spelling when the requested label is only a case or hyphenation variant (`Q3` vs `q3` vs `q3-report`). Apply a genuinely new label as given.
|
|
136
|
+
4. Resolve a collection by `handout collections list --json` and fuzzy-matching the user's words against `name`; confirm before `collections add` or `--collection`.
|
|
137
|
+
5. If the user pasted a Handout link, pass it as the `<ref>` directly; the CLI accepts links and `<handle>/<slug>`.
|
|
138
|
+
6. Ambiguity is always the user's call. A guessed slug is a `404`, and a guessed label is a permanent near-duplicate.
|
|
139
|
+
|
|
140
|
+
## Audiences (--exposure)
|
|
141
|
+
|
|
142
|
+
| `--exposure` | In the app | Who can open it |
|
|
143
|
+
| ------------ | -------------------- | ----------------------------------------- |
|
|
144
|
+
| `private` | Only me | the publisher |
|
|
145
|
+
| `people` | Specific people | signed-in people on the list (`--people`) |
|
|
146
|
+
| `password` | Password | anyone with the link and the password |
|
|
147
|
+
| `open` | Anyone with the link | anyone with the link |
|
|
148
|
+
|
|
149
|
+
- `--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.
|
|
150
|
+
- `--password <secret>` is 4 to 128 characters and implies `--exposure password`. Prefer `--password -` or the `HANDOUT_DOCUMENT_PASSWORD` variable over a literal argument.
|
|
151
|
+
- Link controls: `--expires <when>` (a date, or a duration such as `7d`, `24h`, `30m`), `--max-views <n>`, `--one-time`, and `--revoke` / `--restore` on `manage`.
|
|
152
|
+
- Labels: `--label <name>`, repeatable, at most 10 per document, 1 to 24 characters each.
|
|
153
|
+
- 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.
|
|
154
|
+
- 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`.
|
|
155
|
+
|
|
156
|
+
On `update`, access flags are refused: a new version keeps the document's audience. Change the audience with `handout manage`.
|
|
157
|
+
|
|
158
|
+
## Changing a document later
|
|
159
|
+
|
|
160
|
+
- `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.
|
|
161
|
+
- `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 ""`).
|
|
162
|
+
- `handout rename <slug> <new-slug>` changes the link; the old link stops working.
|
|
163
|
+
- `handout move <slug> --to <handle>` moves the document to another workspace you belong to.
|
|
164
|
+
- `handout versions list <slug>`, `versions diff <slug> <v1> <v2>`, `versions restore <slug> <n>`, `versions source <slug> <n>`, `versions prune <slug> --keep <n>`.
|
|
165
|
+
- `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`).
|
|
166
|
+
|
|
167
|
+
## Collections
|
|
168
|
+
|
|
169
|
+
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.
|
|
170
|
+
|
|
171
|
+
## Seeing who read it
|
|
172
|
+
|
|
173
|
+
`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.
|
|
174
|
+
|
|
175
|
+
## --json guidance
|
|
176
|
+
|
|
177
|
+
Pass `--json` whenever you will parse the output, and never scrape the text output. One JSON document on one line is printed to stdout:
|
|
178
|
+
|
|
179
|
+
- `publish`, `update`, `upsert`: `{"items":[{...}]}` (add `"dryRun":true` with `--dry-run`);
|
|
180
|
+
- `list`, `collections list`, `shared`: `{"items":[...],"nextCursor"?:"..."}`;
|
|
181
|
+
- `versions diff`: `{"slug","from","to","diff"}`;
|
|
182
|
+
- `purge`: `{"slug","purged":true}`; `collections delete`: `{"slug","deleted":true}`; `use`: `{"defaultWorkspace":"<handle>"}`;
|
|
183
|
+
- `activity`: the activity record alone; everything else: the API response unchanged.
|
|
184
|
+
|
|
185
|
+
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`.
|
|
186
|
+
|
|
187
|
+
stdout carries only the result; every notice, summary line and warning goes to stderr.
|
|
188
|
+
|
|
189
|
+
## Error handling
|
|
190
|
+
|
|
191
|
+
| What you see | What to do |
|
|
192
|
+
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
193
|
+
| 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`. |
|
|
194
|
+
| exit 3, `no longer supported` | Run `npm install -g @usehandout/cli@latest`. Do not set `HANDOUT_SKIP_VERSION_CHECK` without telling the user. |
|
|
195
|
+
| `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. |
|
|
196
|
+
| `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. |
|
|
197
|
+
| exit 2, `signed out everywhere` | The user ended all sessions from Settings. Ask them to run `handout login` again; retrying will not help. |
|
|
198
|
+
| `scheduled for deletion` (403) | The account has a pending deletion and every change is paused. Ask the user whether to run `handout account restore`. |
|
|
199
|
+
| `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`. |
|
|
200
|
+
| `slug_taken` | Pick another `--slug`, or if it is the same document use `update` / `upsert`. |
|
|
201
|
+
| `version_mismatch` | Re-read with `handout get --json`, re-apply the edit, retry once with the new `--expected-version`. |
|
|
202
|
+
| `validation_failed` / `bad_request` | The message names the field; fix the flag. Do not retry blindly. |
|
|
203
|
+
| `rate_limited` | Wait at least 60 seconds. Do not loop; tell the user if it persists. |
|
|
204
|
+
| `gone` / `password_required` on a read | The link is off or needs a password; ask the user. |
|
|
205
|
+
| `network` / a timeout | Retry once after a pause, then report. The CLI already retried reads. |
|
|
206
|
+
| `response_shape` | The CLI is stale; run `npm install -g @usehandout/cli@latest`. |
|
|
207
|
+
|
|
208
|
+
## Authoring HTML for the Handout reader
|
|
209
|
+
|
|
210
|
+
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.
|
|
211
|
+
|
|
212
|
+
**Tags that render** (anything else is dropped; the text inside most dropped tags is kept):
|
|
213
|
+
|
|
214
|
+
- structure: `address` `article` `aside` `footer` `header` `hgroup` `main` `nav` `section` `div` `p` `blockquote` `hr` `pre`
|
|
215
|
+
- headings: `h1` `h2` `h3` `h4` `h5` `h6`
|
|
216
|
+
- lists: `ul` `ol` `li` `menu` `dl` `dt` `dd`
|
|
217
|
+
- 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`
|
|
218
|
+
- figures and tables: `figure` `figcaption` `table` `caption` `colgroup` `col` `thead` `tbody` `tfoot` `tr` `th` `td`
|
|
219
|
+
- other: `img` `style` `details` `summary` `input` `label`
|
|
220
|
+
- inline SVG: `svg` `g` `path` `rect` `circle` `ellipse` `line` `polyline` `polygon` `text` `tspan` `defs` `linearGradient` `radialGradient` `stop` `title` `marker`
|
|
221
|
+
|
|
222
|
+
**Attributes that survive**:
|
|
223
|
+
|
|
224
|
+
- on any element: `class` `id` `style` `title` `lang` `dir` `align` `width` `height` `colspan` `rowspan` `role`, any `aria-*`, any `data-*`
|
|
225
|
+
- on `a`: `href` `name` `target` `rel`
|
|
226
|
+
- on `img`: `src` `alt` `title` `width` `height`
|
|
227
|
+
- on `input`: `type` (only `radio` or `checkbox`) `name` `checked` `disabled` `id`
|
|
228
|
+
- on `label`: `for` `id`
|
|
229
|
+
- 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`
|
|
230
|
+
|
|
231
|
+
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.
|
|
232
|
+
|
|
233
|
+
**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"`.
|
|
234
|
+
|
|
235
|
+
**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.
|
|
236
|
+
|
|
237
|
+
**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>`.
|
|
238
|
+
|
|
239
|
+
**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.
|
|
240
|
+
|
|
241
|
+
**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>`.
|
|
242
|
+
|
|
243
|
+
**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:`.
|
|
244
|
+
|
|
245
|
+
**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.
|
|
246
|
+
|
|
247
|
+
**Grep-before-publish checklist.** Any hit must be reworked, or the document published `--interactive`:
|
|
248
|
+
|
|
249
|
+
```
|
|
250
|
+
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
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
The `warnings` in the publish response are the server's view of the same rules; the checklist is the cheap pre-flight.
|
|
254
|
+
|
|
255
|
+
## Interactive documents
|
|
256
|
+
|
|
257
|
+
`--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.
|
|
258
|
+
|
|
259
|
+
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.
|
|
260
|
+
|
|
261
|
+
## Examples
|
|
262
|
+
|
|
263
|
+
Each line shows the command and its expected output.
|
|
264
|
+
|
|
265
|
+
1. `handout publish report.html` prints `https://handout.app/acme/q3-report-k7f2qx9a` (the link comes from the document's title, `Q3 report`).
|
|
266
|
+
2. `handout publish report.md --exposure open --title "Q3 report" --label finance --label q3 --json` prints `{"items":[{"file":"report.md","handle":"acme","slug":"...","id":"...","url":"...","exposure":"open","version":1,...}]}`.
|
|
267
|
+
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`).
|
|
268
|
+
4. `handout publish spec.html --exposure password --password - < pw.txt` prints the URL.
|
|
269
|
+
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."
|
|
270
|
+
6. `handout upsert notes.md --slug meeting-notes --expected-version 3` prints the URL, or exits 1 with `Version conflict (409) ...`.
|
|
271
|
+
7. `handout manage q3-report --exposure people --people @acme.com --label "" --expires 7d` prints `q3-report: people, expires: 2026-11-05T17:03:00.000Z`.
|
|
272
|
+
8. `handout search "quarterly" --json` prints `{"query":"quarterly","items":[...]}`.
|
|
273
|
+
9. `handout collections create --name "Onboarding" --items welcome,handbook --exposure people --people @acme.com` prints `https://handout.app/acme/c/onboarding-m4w8r2zt`.
|
|
274
|
+
10. `handout versions diff q3-report 2 3` prints a unified diff.
|
|
275
|
+
|
|
276
|
+
## Environment variables
|
|
277
|
+
|
|
278
|
+
| Variable | Effect |
|
|
279
|
+
| ------------------------------ | ------------------------------------------------------------------------------ |
|
|
280
|
+
| `HANDOUT_HOST` | The Handout origin to talk to (default `https://usehandout.com`) |
|
|
281
|
+
| `HANDOUT_REFRESH_TOKEN` | Headless credential; overrides the stored one. Treat as a password |
|
|
282
|
+
| `HANDOUT_API_KEY` | Firebase web API key to use with `HANDOUT_REFRESH_TOKEN` |
|
|
283
|
+
| `HANDOUT_WORKSPACE` | Default workspace handle for the invocation (below `--workspace`) |
|
|
284
|
+
| `HANDOUT_DOCUMENT_PASSWORD` | Document or collection password when `--password` is absent; never printed |
|
|
285
|
+
| `HANDOUT_NO_KEYCHAIN=1` | Skip the OS keychain, as `--no-keychain` does |
|
|
286
|
+
| `HANDOUT_SKILL_SOURCE` | The `SKILL.md` that `handout skill install` copies (default: the packaged one) |
|
|
287
|
+
| `HANDOUT_SKIP_VERSION_CHECK=1` | Bypass the minimum-version gate; tell the user if you set it |
|
|
288
|
+
| `NO_COLOR` | Disables colour |
|
|
289
|
+
|
|
290
|
+
Precedence for every setting: flag, then environment, then the local config file, then the account setting, then the default.
|
|
291
|
+
|
|
292
|
+
## Deliberate limits
|
|
293
|
+
|
|
294
|
+
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.
|