@usehandout/cli 1.4.0 → 1.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -0
- package/SKILL.md +28 -27
- package/handout.mjs +1288 -343
- package/package.json +5 -1
- package/setup/SKILL.md +116 -0
package/README.md
CHANGED
|
@@ -24,6 +24,13 @@ handout skill install --dir <path> # any other agent's skills directory
|
|
|
24
24
|
In Claude Code you can install the plugin instead: `/plugin marketplace add usehandout/handout`,
|
|
25
25
|
then `/plugin install handout@usehandout`. Use the plugin or `--agent claude`, not both.
|
|
26
26
|
|
|
27
|
+
Each install also adds `handout-setup`, a one-time guided setup that you start yourself:
|
|
28
|
+
`/handout:setup` with the plugin, `/handout-setup` otherwise in Claude Code; in Codex, ask for
|
|
29
|
+
the Handout setup. It saves your publishing defaults (such as the default format and audience),
|
|
30
|
+
offers starter collections, and adds a short Handout section to your agent's instructions only
|
|
31
|
+
after you approve the exact change. `handout setup print-instructions --agent claude` prints that section; it never
|
|
32
|
+
writes a file.
|
|
33
|
+
|
|
27
34
|
## Update
|
|
28
35
|
|
|
29
36
|
```bash
|
package/SKILL.md
CHANGED
|
@@ -42,21 +42,17 @@ Then make this skill available to your agent:
|
|
|
42
42
|
| Codex | `handout skill install --agent codex` (writes `~/.agents/skills/handout/SKILL.md`). |
|
|
43
43
|
| Another terminal agent | `handout skill install --dir <its skills directory>`. |
|
|
44
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.
|
|
45
|
+
`handout skill install` copies the `SKILL.md` that ships with the installed CLI into `<skills directory>/handout/SKILL.md`, and the setup skill into `<skills directory>/handout-setup/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
46
|
|
|
47
47
|
The CLI talks to `https://usehandout.com` unless `--host` or `HANDOUT_HOST` names another Handout site.
|
|
48
48
|
|
|
49
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
50
|
|
|
51
|
-
**
|
|
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
|
-
```
|
|
51
|
+
**Guided setup.** `handout skill install` also installs `handout-setup`, a one-time guided setup that the user starts (`/handout:setup` with the Claude Code plugin, `/handout-setup` otherwise). It saves the account's publishing defaults and can add a Handout section to the agent's instructions. Do not suggest it on your own: when `handout settings get` prints a setup tip on stderr (at most once per machine), pass it on to the user in one line, and say nothing more about setup.
|
|
56
52
|
|
|
57
53
|
## Sign in
|
|
58
54
|
|
|
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.
|
|
55
|
+
`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, and later commands keep to it). A login kept in the file moves into the keychain the first time the keychain is usable, and that command says so once on stderr; pass it on to the user in one line. `handout whoami` shows who you are signed in as and your workspaces; `handout logout` removes this host's credential.
|
|
60
56
|
|
|
61
57
|
When a command exits 2 with `Not signed in. Run: handout login`, ask the user to run `handout login` in their own terminal.
|
|
62
58
|
|
|
@@ -64,9 +60,11 @@ When a command exits 2 with `Not signed in. Run: handout login`, ask the user to
|
|
|
64
60
|
|
|
65
61
|
## Workspaces
|
|
66
62
|
|
|
67
|
-
Every document lives in a workspace, identified by a handle. `handout workspaces list` shows yours; `handout use <handle>`
|
|
63
|
+
Every document lives in a workspace, identified by a handle. `handout workspaces list` shows yours; `handout use <handle>` saves a default on your account (the web app follows); `--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
64
|
|
|
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.
|
|
65
|
+
**Account publishing defaults.** Before you produce a document the user may publish, and before a publishing workflow, run `handout settings get --json`. It returns settings directly, including optional `defaultFormat`, `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.
|
|
66
|
+
|
|
67
|
+
**Default format.** `defaultFormat` (`html`, `markdown` or `pdf`) is the format to make a new document in when the user does not name one; when it is absent, choose the format as usual. A format the user names wins, and the setting never converts a document that already exists or one the user gave you.
|
|
70
68
|
|
|
71
69
|
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
70
|
|
|
@@ -87,15 +85,13 @@ Every command takes the global flags `--workspace/-w`, `--host`, `--json`, `--qu
|
|
|
87
85
|
| `invite` | `handout invite q3-report --to a@b.com` | a confirmation line |
|
|
88
86
|
| `activity` / `audit` / `acks` | `handout activity q3-report` | views, history, acknowledgments |
|
|
89
87
|
| `list` | `handout list --label report` | url, audience, type, title per line; `--collection <slug>` filters to one collection |
|
|
90
|
-
| `labels` | `handout labels --json` |
|
|
88
|
+
| `labels` | `handout labels --json` | suggested labels with usage counts; `add`, `remove`, `reorder`, `seed` edit the list |
|
|
91
89
|
| `get` | `handout get q3-report` | a key/value block |
|
|
92
90
|
| `search` | `handout search "quarterly"` | slug, where it matched, title |
|
|
93
91
|
| `source` | `handout source q3-report --out report.md` | the source file |
|
|
94
92
|
| `open` | `handout open q3-report` | the URL (no network call) |
|
|
95
93
|
| `read` | `handout read <ref>` | the rendered body or the file bytes |
|
|
96
94
|
| `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
95
|
| `comments` | `handout comments list <ref>` | `list`, `resolve`, `unresolve`, `delete` |
|
|
100
96
|
| `browse` | `handout browse --query roadmap` | documents and collections you can open |
|
|
101
97
|
| `workspaces` | `handout workspaces list` | `list`, `create`, `get`, `update`, `delete`, `restore` |
|
|
@@ -106,7 +102,8 @@ Every command takes the global flags `--workspace/-w`, `--host`, `--json`, `--qu
|
|
|
106
102
|
| `shared` / `library` | `handout shared` | what others shared; saved, followed, recent |
|
|
107
103
|
| `save` / `unsave` / `follow` / `unfollow` | `handout follow acme/q3-report` | a confirmation line |
|
|
108
104
|
| `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
|
|
105
|
+
| `skill` | `handout skill install --agent codex` | `install`: copies this SKILL.md and the setup skill into an agent's skills directory |
|
|
106
|
+
| `setup` | `handout setup print-instructions --agent claude --json` | the Handout block for an agent's instructions file and the change it would make (never writes) |
|
|
110
107
|
| `help` | `handout help publish` | usage for a command |
|
|
111
108
|
|
|
112
109
|
`handout --version` prints the installed version. `handout <command> --help` prints that command's flags.
|
|
@@ -119,20 +116,24 @@ Each workspace keeps a short, editable list of suggested labels. Before you labe
|
|
|
119
116
|
|
|
120
117
|
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
118
|
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
|
|
119
|
+
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 `handout labels seed` adds the suggested set, and run it only if they say yes.
|
|
123
120
|
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.
|
|
121
|
+
5. A `suggested` or `other` entry may carry `matchesCollection: { slug, name }`: every document with that label is exactly the members of that collection, so the label stores the same fact twice. **Suggest the collection to the user** ("Every document labelled `q3` is already in the Q3 pack collection; use the collection instead?") and do not apply that label to new documents. It is a suggestion only: never remove the label, add or remove collection members, or delete anything because of it unless the user says to.
|
|
122
|
+
|
|
123
|
+
Edit the suggested list only when the user asks (or in guided setup): `handout labels add <label>…`, `labels remove <label>…`, `labels reorder <label>…` (every suggested label, once) and `labels seed` (the starter set). They print the new list (`--json`: `suggestedLabels`, `added`, `removed`) and never touch a document's own labels.
|
|
124
124
|
|
|
125
125
|
The user's account `defaultLabels` setting is separate: it stamps labels on every publish, and you never change it unless asked.
|
|
126
126
|
|
|
127
127
|
## Publish what you just generated
|
|
128
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).
|
|
129
|
+
1. Write the file to disk first; the CLI publishes files, not stdin. When the user named no format, make it in the account's `defaultFormat` if one is set. 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
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
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
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
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
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
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
|
+
A `pdf_no_text` warning means the PDF is published but "We couldn't find much searchable text in this PDF. If it's a scan, running OCR and republishing will make it searchable." Pass that on in one line, then offer to make it searchable: run text recognition (OCR) on the file locally and publish the result as a new version of the same document. Ask the user first; never OCR or republish unasked. When they agree and `ocrmypdf` is installed (`ocrmypdf --version`), run `ocrmypdf --skip-text <file> <file-ocr>.pdf`, then `handout update <slug> <file-ocr>.pdf --diff-summary "Made the text searchable."`. If no OCR tool is available, tell them and leave the document as it is. Handout itself never runs OCR.
|
|
136
137
|
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
138
|
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
139
|
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.
|
|
@@ -196,7 +197,7 @@ Pass `--json` whenever you will parse the output, and never scrape the text outp
|
|
|
196
197
|
- `purge`: `{"slug","purged":true}`; `collections delete`: `{"slug","deleted":true}`; `use`: `{"defaultWorkspace":"<handle>"}`;
|
|
197
198
|
- `activity`: the activity record alone; everything else: the API response unchanged.
|
|
198
199
|
|
|
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`, `
|
|
200
|
+
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`, `read`, `open`, `help`.
|
|
200
201
|
|
|
201
202
|
stdout carries only the result; every notice, summary line and warning goes to stderr.
|
|
202
203
|
|
|
@@ -289,17 +290,17 @@ Each line shows the command and its expected output.
|
|
|
289
290
|
|
|
290
291
|
## Environment variables
|
|
291
292
|
|
|
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
|
|
293
|
+
| Variable | Effect |
|
|
294
|
+
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
|
|
295
|
+
| `HANDOUT_HOST` | The Handout origin to talk to (default `https://usehandout.com`) |
|
|
296
|
+
| `HANDOUT_REFRESH_TOKEN` | Headless credential; overrides the stored one. Treat as a password |
|
|
297
|
+
| `HANDOUT_API_KEY` | Firebase web API key to use with `HANDOUT_REFRESH_TOKEN` |
|
|
298
|
+
| `HANDOUT_WORKSPACE` | Default workspace handle for the invocation (below `--workspace`) |
|
|
299
|
+
| `HANDOUT_DOCUMENT_PASSWORD` | Document or collection password when `--password` is absent; never printed |
|
|
300
|
+
| `HANDOUT_NO_KEYCHAIN=1` | Skip the OS keychain, as `--no-keychain` does |
|
|
301
|
+
| `HANDOUT_SKILL_SOURCE` | The `SKILL.md` that `handout skill install` copies (default: the packaged one); the setup skill is `setup/SKILL.md` beside it |
|
|
302
|
+
| `HANDOUT_SKIP_VERSION_CHECK=1` | Bypass the minimum-version gate; tell the user if you set it |
|
|
303
|
+
| `NO_COLOR` | Disables colour |
|
|
303
304
|
|
|
304
305
|
Precedence for every setting: flag, then environment, then the local config file, then the account setting, then the default.
|
|
305
306
|
|