@ghostlytools/cli 1.7.3 → 1.8.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 (106) hide show
  1. package/README.md +30 -19
  2. package/SKILL.md +6 -4
  3. package/dist/assets/{api-B42F9ytB.js → api-Dj1yn0px.js} +2 -2
  4. package/dist/assets/{api-tf-wAAnB.js → api-I_KbuXHa.js} +192 -88
  5. package/dist/assets/api-I_KbuXHa.js.map +1 -0
  6. package/dist/assets/{apiKit-DJb9hulp.js → apiKit-C-_PWZvy.js} +44 -9
  7. package/dist/assets/apiKit-C-_PWZvy.js.map +1 -0
  8. package/dist/assets/{apps-DIrWmLgL.js → apps-DKIe8VjF.js} +11 -8
  9. package/dist/assets/apps-DKIe8VjF.js.map +1 -0
  10. package/dist/assets/{apps-BfoDISRg.js → apps-DbEfL_3b.js} +1 -1
  11. package/dist/assets/{arkade-CJAhhgPQ.js → arkade-k1bdSm70.js} +2 -2
  12. package/dist/assets/{arkade-CJAhhgPQ.js.map → arkade-k1bdSm70.js.map} +1 -1
  13. package/dist/assets/{backup-BkUeeduy.js → backup-Cdd6-HNu.js} +1 -1
  14. package/dist/assets/{backup-Bko-AAm0.js → backup-beKfbfNk.js} +7 -7
  15. package/dist/assets/{backup-Bko-AAm0.js.map → backup-beKfbfNk.js.map} +1 -1
  16. package/dist/assets/bark_ffi_wasm_bg-EY2uc0Bx.js.map +1 -1
  17. package/dist/assets/bitcoindevkit_bg-B-iLWrmX.js.map +1 -1
  18. package/dist/assets/{blobFiles-Bckz9fjp.js → blobFiles-DOQDRdDI.js} +3 -3
  19. package/dist/assets/{blobFiles-Bckz9fjp.js.map → blobFiles-DOQDRdDI.js.map} +1 -1
  20. package/dist/assets/buttons-BO1_7V4L.js +2 -0
  21. package/dist/assets/{buttons-DeA6Yddq.js → buttons-ClI13rdv.js} +7 -6
  22. package/dist/assets/buttons-ClI13rdv.js.map +1 -0
  23. package/dist/assets/{daemonProof-Bp9lJDxf.js → daemonProof-DtrL5lE5.js} +2 -2
  24. package/dist/assets/{daemonProof-Bp9lJDxf.js.map → daemonProof-DtrL5lE5.js.map} +1 -1
  25. package/dist/assets/{envelope-Cz5fc7BM.js → envelope-B88yiCQj.js} +2 -2
  26. package/dist/assets/{envelope-Cz5fc7BM.js.map → envelope-B88yiCQj.js.map} +1 -1
  27. package/dist/assets/{errors-mnjSQlbX.js → errors-R4S2SAEM.js} +8 -3
  28. package/dist/assets/errors-R4S2SAEM.js.map +1 -0
  29. package/dist/assets/{fileBytes-OolN5cSY.js → fileBytes-BPDKufla.js} +1 -1
  30. package/dist/assets/{fileBytes-BD0v3rRG.js → fileBytes-DNgrRL0R.js} +3 -3
  31. package/dist/assets/{fileBytes-BD0v3rRG.js.map → fileBytes-DNgrRL0R.js.map} +1 -1
  32. package/dist/assets/{fileBytes-_fd-2JRY.js → fileBytes-Q3ehcEr8.js} +2 -2
  33. package/dist/assets/{fileBytes-_fd-2JRY.js.map → fileBytes-Q3ehcEr8.js.map} +1 -1
  34. package/dist/assets/fileBytesIdb-DZcESfTt.js +2 -0
  35. package/dist/assets/{fileBytesIdb-NtA8r9EM.js → fileBytesIdb-Dm1EyEbT.js} +3 -3
  36. package/dist/assets/{fileBytesIdb-NtA8r9EM.js.map → fileBytesIdb-Dm1EyEbT.js.map} +1 -1
  37. package/dist/assets/{fileBytesOpfs-B8fJwkwM.js → fileBytesOpfs-ZGD21c4Q.js} +3 -3
  38. package/dist/assets/{fileBytesOpfs-B8fJwkwM.js.map → fileBytesOpfs-ZGD21c4Q.js.map} +1 -1
  39. package/dist/assets/{groupFiles-BlZRBWpt.js → groupFiles-DjQc5XXv.js} +151 -28
  40. package/dist/assets/groupFiles-DjQc5XXv.js.map +1 -0
  41. package/dist/assets/{host-BX0DmKW6.js → host-CNWGB3-j.js} +86 -24
  42. package/dist/assets/host-CNWGB3-j.js.map +1 -0
  43. package/dist/assets/{hyperdhtRelay-DitYDnXx.js → hyperdhtRelay-g7eXzf5h.js} +2 -2
  44. package/dist/assets/{hyperdhtRelay-DitYDnXx.js.map → hyperdhtRelay-g7eXzf5h.js.map} +1 -1
  45. package/dist/assets/{idb-BlH8-O3R.js → idb-BkOJES5_.js} +5 -3
  46. package/dist/assets/idb-BkOJES5_.js.map +1 -0
  47. package/dist/assets/{irohWeb-R3bcd34h.js → irohWeb-Bx8dI4be.js} +2 -2
  48. package/dist/assets/{irohWeb-R3bcd34h.js.map → irohWeb-Bx8dI4be.js.map} +1 -1
  49. package/dist/assets/{main-6QOSvQ8b.js → main-BRxhBctJ.js} +462 -126
  50. package/dist/assets/main-BRxhBctJ.js.map +1 -0
  51. package/dist/assets/{mainline-BfwezHWi.js → mainline-CwuS6ngj.js} +39 -12
  52. package/dist/assets/mainline-CwuS6ngj.js.map +1 -0
  53. package/dist/assets/mints-BaOmx517.js +2 -0
  54. package/dist/assets/{mints-BrlY773j.js → mints-j5XAOk4f.js} +15 -3
  55. package/dist/assets/mints-j5XAOk4f.js.map +1 -0
  56. package/dist/assets/{networkReason-Ba9415nn.js → networkReason-CIAMieQm.js} +3 -3
  57. package/dist/assets/{networkReason-Ba9415nn.js.map → networkReason-CIAMieQm.js.map} +1 -1
  58. package/dist/assets/{nwc-ovXSN2M2.js → nwc-C9JLJJkL.js} +3 -3
  59. package/dist/assets/{nwc-ovXSN2M2.js.map → nwc-C9JLJJkL.js.map} +1 -1
  60. package/dist/assets/{nwcProvider-BzZbfFP3.js → nwcProvider-pFMrsUJh.js} +2 -2
  61. package/dist/assets/{nwcProvider-BzZbfFP3.js.map → nwcProvider-pFMrsUJh.js.map} +1 -1
  62. package/dist/assets/{profiles-C6XWqre5.js → profiles-MFtCmJwK.js} +104 -10
  63. package/dist/assets/profiles-MFtCmJwK.js.map +1 -0
  64. package/dist/assets/{registry-B0Uv9yL6.js → registry-Cks7FA_o.js} +45 -14
  65. package/dist/assets/registry-Cks7FA_o.js.map +1 -0
  66. package/dist/assets/{registry-CFtlhWCI.js → registry-DY2ixQfU.js} +1 -1
  67. package/dist/assets/{resolve-BzFG4WDU.js → resolve-C4Y2HPqQ.js} +79 -30
  68. package/dist/assets/resolve-C4Y2HPqQ.js.map +1 -0
  69. package/dist/assets/{restoredRows-Fv-MuY45.js → restoredRows-BCRCjhdF.js} +27 -3
  70. package/dist/assets/{restoredRows-Fv-MuY45.js.map → restoredRows-BCRCjhdF.js.map} +1 -1
  71. package/dist/assets/{server-BGCuHbmQ.js → server-D9RAmGdm.js} +1398 -358
  72. package/dist/assets/server-D9RAmGdm.js.map +1 -0
  73. package/dist/assets/{src-DWw2hUE5.js → src-1RU4TilT.js} +1416 -234
  74. package/dist/assets/src-1RU4TilT.js.map +1 -0
  75. package/dist/assets/{translate-DObb-1tq.js → translate-od5GbpvR.js} +19 -13
  76. package/dist/assets/translate-od5GbpvR.js.map +1 -0
  77. package/dist/assets/{usdt-Bkva90Vo.js → usdt-DldXV0MR.js} +3 -3
  78. package/dist/assets/{usdt-Bkva90Vo.js.map → usdt-DldXV0MR.js.map} +1 -1
  79. package/dist/assets/waitNotice-Ck3el3_Z.js +45 -0
  80. package/dist/assets/waitNotice-Ck3el3_Z.js.map +1 -0
  81. package/dist/assets/{words-odSAoasK.js → words-BS2qq_vV.js} +7 -4
  82. package/dist/assets/words-BS2qq_vV.js.map +1 -0
  83. package/dist/ghostly.mjs +1 -1
  84. package/examples/claude-code-agent.sh +1 -1
  85. package/package.json +1 -1
  86. package/dist/assets/api-tf-wAAnB.js.map +0 -1
  87. package/dist/assets/apiKit-DJb9hulp.js.map +0 -1
  88. package/dist/assets/apps-DIrWmLgL.js.map +0 -1
  89. package/dist/assets/buttons-Be7u0V5g.js +0 -2
  90. package/dist/assets/buttons-DeA6Yddq.js.map +0 -1
  91. package/dist/assets/errors-mnjSQlbX.js.map +0 -1
  92. package/dist/assets/fileBytesIdb-CsSQcSxD.js +0 -2
  93. package/dist/assets/groupFiles-BlZRBWpt.js.map +0 -1
  94. package/dist/assets/host-BX0DmKW6.js.map +0 -1
  95. package/dist/assets/idb-BlH8-O3R.js.map +0 -1
  96. package/dist/assets/main-6QOSvQ8b.js.map +0 -1
  97. package/dist/assets/mainline-BfwezHWi.js.map +0 -1
  98. package/dist/assets/mints-BrlY773j.js.map +0 -1
  99. package/dist/assets/mints-CqTdA4Gk.js +0 -2
  100. package/dist/assets/profiles-C6XWqre5.js.map +0 -1
  101. package/dist/assets/registry-B0Uv9yL6.js.map +0 -1
  102. package/dist/assets/resolve-BzFG4WDU.js.map +0 -1
  103. package/dist/assets/server-BGCuHbmQ.js.map +0 -1
  104. package/dist/assets/src-DWw2hUE5.js.map +0 -1
  105. package/dist/assets/translate-DObb-1tq.js.map +0 -1
  106. package/dist/assets/words-odSAoasK.js.map +0 -1
package/README.md CHANGED
@@ -92,9 +92,12 @@ waits until the message went out. Bots should run the daemon: a one-shot is offl
92
92
 
93
93
  Every command prints one JSON object on stdout. A failure prints `{"error":{"code","message"}}` and exits with:
94
94
  `1` failed (the engine or the network refused), `2` usage, `3` not found, `4` timed out, `5` needs a confirmation
95
- (`--force`, `--yes`, `--confirm-real`). A daemon that does not answer a read or `daemon status` within 15 seconds, or
95
+ (`--force`, `--yes`, `--confirm-real`), `130` stopped with Ctrl-C (`interrupted`: a one-shot closes its profile first,
96
+ and a line on stderr says what became of what it waited on). A daemon that does not answer a read or `daemon status` within 15 seconds, or
96
97
  a command that waits (`chat wait`, `file wait`, `--wait`) within its `--timeout` plus 10, is a timeout too (`4`,
97
- `details.method`); `ghostly daemon restart` is the way out ([docs/CLI.md](../../docs/CLI.md#what-it-does)). A `<chat>` is
98
+ `details.method`); `ghostly daemon restart` is the way out ([docs/CLI.md](../../docs/CLI.md#what-it-does)). On a
99
+ terminal, a command that waits says on stderr what it waits for once it has waited a second; nothing is said there on
100
+ a pipe. A `<chat>` is
98
101
  its id, a unique prefix of it, or its name; a `<group>` too.
99
102
 
100
103
  The rows are in alphabetical order of their first command, and every command of `ghostly help` has one
@@ -118,21 +121,21 @@ The rows are in alphabetical order of their first command, and every command of
118
121
  | `chat connect <chat>`, `chat disconnect <chat> [--hold <minutes>]` | Reconnect now (ends a hold); close the live session, or with `--hold` stay off the direct link that long ([Staying off the direct link](#staying-off-the-direct-link)) |
119
122
  | `chat history <chat> [--limit n] [--before x] [--after x] [--translate lang]` | Messages, oldest first; `x` is a message id or a time in ms ([Translation](#translation)) |
120
123
  | `chat list [--show-secret]`, `chat show <chat> [--show-secret]` | Chats, and one chat's connection: transports, last attempt, comparison code. A pending chat's `invite` prints as `<hidden>` without `--show-secret` |
121
- | `chat pay <chat> <sats> [--memo t] [--network n] [--confirm-real]` | Ecash to a contact. A contact that offers no way of paying is `refused`: `details.reason` `contact_no_wallet` (it has no wallet yet) or `contact_payments_off` (it has payments off in this chat, or an older app) |
122
- | `chat rename <chat> <name>`, `chat remove <chat> --yes` | Name it here; delete it (keys and history) here |
123
- | `chat request <chat> <sats> [--memo t] [--method m] [--rail r]`, `chat pay-request <chat> <payment>` | Ask a contact to pay; pay the contact's request. Refused as `chat pay` is when the contact offers no way of paying |
124
+ | `chat pay <chat> <sats> [--memo t] [--network n] [--confirm-real]` | Ecash to a contact. A contact that offers no way of paying is `refused`: `details.reason` `contact_no_wallet` (it has no wallet yet) or `contact_payments_off` (it has payments off in this chat, or an older app). With no Cashu wallet of the network on this side, `refused` with `details.reason` `no_wallet` and the `wallet create` command to run; with one too short of sats, `refused` |
125
+ | `chat rename <chat> <name>`, `chat remove <chat> --yes` | Name it here; delete it (keys and history) here, refused (`busy`) while a call is on in it: hang the call up first |
126
+ | `chat request <chat> <sats> [--memo t] [--method m] [--rail r]`, `chat pay-request <chat> <payment>` | Ask a contact to pay; pay the contact's request. Refused as `chat pay` is when the contact offers no way of paying, or when `chat request` has no Cashu wallet of the network here (`no_wallet`) |
124
127
  | `chat transport <chat> <auto\|dht\|webrtc\|iroh\|hyperdht>` | What carries the chat |
125
128
  | `chat verify <chat> --code <code>` | Mark the contact verified after comparing the codes out of band |
126
129
  | `chat wait <chat> [--until live\|text\|paired] [--timeout s]` | Wait for a chat to go live, carry text, or see its contact. Live means a session that exists now, in this run of the daemon: a chat that was live before a restart counts once its contact answers again |
127
- | `daemon [--detach] [--timeout s]`, `daemon status [--timeout s]`, `daemon stop [--timeout s]`, `daemon restart [--timeout s]` | Keep the profile online; `status` names its version and its socket (`socket`, for the [socket API](#the-socket-api)); `restart` stops it and starts this release's code in the background ([After an upgrade](#after-an-upgrade)). Ctrl-C, SIGTERM and the terminal closing (SIGHUP) stop it cleanly. A command that holds the profile for a moment (a bot's `send` while a service manager restarts it) is waited for, up to `--timeout` (60 s): still held then, `busy` with its pid |
130
+ | `daemon [--detach] [--timeout s]`, `daemon status [--timeout s]`, `daemon stop [--timeout s]`, `daemon restart [--timeout s]` | Keep the profile online; `status` names its version and its socket (`socket`, for the [socket API](#the-socket-api)), or says `"starting": true` with the `pid` of a daemon whose socket does not listen yet (`stop` and `restart` wait up to `--timeout` for that socket, then stop it); `restart` stops it and starts this release's code in the background ([After an upgrade](#after-an-upgrade)). Ctrl-C, SIGTERM and the terminal closing (SIGHUP) stop it cleanly. A command that holds the profile for a moment (a bot's `send` while a service manager restarts it) is waited for, up to `--timeout` (60 s): still held then, `busy` with its pid |
128
131
  | `edit <chat> <message> [text… \| --text <text> \| --stdin] [--force] [--wait none\|confirmed] [--timeout s]` | Replace the text of a message you sent (1:1 chats, `group edit` for a group; `<message>` is the `messageId` `send` gave, or its wire id). The contact sees it in place, marked edited; `--wait confirmed` waits for its app to confirm (the default without a daemon). At most 100 edits a message, no time limit; an older contact app gets it once it shows edits |
129
132
  | `engine <method> [json \| -] [--confirm-real] [--show-secret] [--yes] [--force]`, `engine --list [--verbose]` | Any call of the app's engine; `--verbose` lists what each takes (`{ linkId, label }`, `?` for an optional key). A call given less than it takes is refused as `bad_request`. One that deletes chats or groups (`clearProfileData`, `removeLink`, `leaveGroup`, `forgetGroup`, `deviceRemove`) needs `--yes`; `clearProfileData` answers what it removed and stops a daemon. One that sends a text that looks like a secret (`sendMessage`, `sendGroupMessage`, `editMessage`, `forwardMessages`) needs `--force` |
130
133
  | `events [--since seq] [--translate lang]` | What the event journal holds, without following ([Translation](#translation)) |
131
- | `file list <chat\|group>`, `file accept\|decline\|pause\|resume\|cancel [<chat>] <file>` | Transfers; a file over 25 MiB waits for `file accept` (files/3), and so does a group's file that did not come by itself (over 8 MiB). A file's id names its chat or its group, so `<chat>` may be left out |
134
+ | `file list <chat\|group>`, `file accept\|decline\|pause\|resume\|cancel [<chat>] <file>` | Transfers; a file over 25 MiB waits for `file accept` (files/3), and so does a group's file that did not come by itself (over 8 MiB): its row's `transfer` says `stage: "asking"`, `waitingFor: "me"` (a file sent from here that the contact has not taken yet: `waitingFor: "contact"`). A file's id names its chat or its group, so `<chat>` may be left out |
132
135
  | `file resend [<chat>] <file>`, `file request [<chat>] <file>` | A file that stopped moving: sent again from here, or asked for again from the contact (a group's file: from whoever holds it); either goes on from the bytes the receiver holds (files/3) |
133
136
  | `file save [<chat>] <file> [--dir d \| --path p] [--force] [--wait [--timeout s]]` | Write a received file to disk: to `--path`, or into `--dir` under the name its sender gave it, with a `_` first when that name starts with `-`, so no tool run in the folder takes it for an option; a voice message goes in under the name Ghostly makes for it (`Ghostly voice <date time>`), and when that name is taken (two of one second) under a free `… (2)` (the answer's `path` is what was written). Never over a file without `--force`; an unfinished one says how many bytes are here; `--wait` waits for it first |
134
137
  | `file send <chat\|group> <path> [--name n] [--mime t] [--voice [ms] [--peaks …]] [--reply <message>]` | A file, or a voice note (its length and waveform measured from the file unless given); `--reply` quotes a message, as `send --reply` does. Answers the message's `messageId` (what `message delete`, `react` and `pin` take) and the file's id. To a group (`group:<id>` when a chat has the same name), up to 100 MiB: every member sees it at once and each member's app fetches it from a member who has it (WISP 503) |
135
- | `file wait [<chat>] <file> [--timeout s]` | Wait until a transfer ends: exit `0` when the file is all here, `1` with the transfer's error when it failed (`details.retry`: `file resend` can go on), `4` on timeout (default 300 s) |
138
+ | `file wait [<chat>] <file> [--timeout s]` | Wait until a transfer ends: exit `0` when the file is all here, `1` with the transfer's error when it failed (`details.retry`: `file resend` can go on), `4` on timeout (default 300 s), `5` at once when a received file waits for you to take it (over 25 MiB, or a group's file that did not come by itself): the message names `file accept` |
136
139
  | `forward <chat\|group> <message>… --to <chat\|group>… [--force] [--wait none\|sent] [--timeout s]` | Forward messages to up to 5 chats and groups (`--to` again for each; `group:<id>` names a group when a chat has the same name; an id that starts with a dash is taken as it is, `--to -Ab…` or `--to=-Ab…`). Each is a new message of yours that says it was forwarded (`forwarded`, the hop count) and nothing of who wrote it. Files go from the bytes this profile holds, never fetched again; a group takes texts only. A text that looks like a seed, a key or ecash needs `--force`. Answers `{from, results: [{to, kind, messageIds, error}]}`; any refusal fails the command (exit 1) with the results in `details`. `--wait sent`: each text on its way (a group's taken by an edge), each file's transfer done |
137
140
  | `group create <name> [--mesh]`, `group join [<link> \| -]` | A community (a link anyone can open), or a private mesh. `group join` reads the link from stdin when none is given or `-` (on the command line it shows in `ps` and the shell's history, and the CLI warns). `group join` with the link of a community the profile was removed from asks to be let in again, and keeps its history |
138
141
  | `group edit <group> <message> [text… \| --text <text> \| --stdin] [--mention <member>]… [--force]` | Replace the text of a message you sent to the group (`<message>` is the `messageId` `group send` gave). Every member sees it in place, marked edited; mentions whose `@name` is still in the text stay, `--mention` adds more. Answers `{group, messageId, edits, sent, edges}`: `edges` and `sent` as for `group send` (`sent: false` while no edge took this edit, also while it waits for the pace); `--wait sent` and `--timeout` as for `group send`. The text the message already has is no edit: `sent: false, unchanged: true`. A private group's members whose edge is down get it when it opens, a community's with the catch-up; a member on an older app keeps the old text |
@@ -163,17 +166,17 @@ The rows are in alphabetical order of their first command, and every command of
163
166
  | `profile picture <jpeg> \| --clear` | The picture contacts see (a JPEG within 512 px; 128 px is what the app sends) |
164
167
  | `profile show`, `profile set [--name <name>] [--share-profile \| --no-share-profile]` | The name contacts see |
165
168
  | `react <chat> <message> <emoji> [--remove] [--wait none\|confirmed] [--timeout s]` | React to a message with one emoji; a new one replaces yours, `--remove` takes it back. Without a daemon it stays until the contact confirmed it (`--wait confirmed`, the default there; `--timeout`, 30 s): a one-shot that left at once took the reaction along unsaid. `confirmed` says whether the contact has it |
166
- | `routine send <chat\|group> --name <name> --schedule "every day 01:00" [--cron "0 1 * * *"] [--state active\|paused] [--next <time>] [--run ok\|failed\|skipped[:summary]] [--link url]… [--id id] [--text <text>] [--json json\|-\|file] [--force]`, `routine update <chat\|group> <routine> [fields…]` | A routine card for something a bot runs on a schedule (WISP 405 · Status Cards): its name, schedule (and cron line, shown only), state, last run and result, next run and up to 10 recent runs. `--run` records a run now as the last one; `--next` takes milliseconds or a date. Updates merge and are paced as `task update`'s, and wait as `task send` and `task update` do. The app shows it, and runs nothing |
169
+ | `routine send <chat\|group> --name <name> --schedule "every day 01:00" [--cron "0 1 * * *"] [--state active\|paused] [--next <time>] [--run ok\|failed\|skipped[:summary]] [--link url]… [--id id] [--text <text>] [--json json\|-\|file] [--force]`, `routine update <chat\|group> <routine> [fields…]` | A routine card for something a bot runs on a schedule (WISP 405 · Status Cards): its name, schedule (and cron line, shown only), state, last run and result, next run and up to 10 recent runs. `--run` records a run now as the last one; `--next` takes milliseconds or a date (no zone: local time, a bare `2026-09-30` local midnight; `Z` or `+02:00` as given). Updates merge and are paced as `task update`'s, and wait as `task send` and `task update` do. The app shows it, and runs nothing |
167
170
  | `saved add\|remove <chat\|group> <message>`, `saved list` | Saved messages: mark a message of a chat or a group to find it again, kept for this profile on this device and never sent (the app shows the same list in its Saved view). `saved list` gives them the last saved first, each as it is now (an edit shows its latest text) with its `chat` or `group` and `savedAt`; a deleted message drops out |
168
171
  | `send <chat> [text…] [--reply <message>] [--button id:Label]… [--style id=primary\|neutral\|danger]… [--once] [--id id] [--stdin] [--force] [--wait none\|sent\|delivered] [--timeout s]` | Send text (arguments, or stdin); `--reply` quotes a message of the chat. `--button yes:Yes` (1 to 6; the id ends at the first colon; no two labels alike ignoring case and spaces, and no label that is another button's id, else exit 2) puts buttons under the text, which is the question and what older apps show, so say how to answer in words. `--once`: one answer a person. A question that goes on the DHT floor or into a hold (the contact's app closed) reaches them as text alone; the engine sends its buttons again once the chat is live, as an edit of the buttons alone (no `message.edited` for it). The answer adds `buttons` (the question's id, `ask-…` unless `--id`), `card`, and `pressable`: whether the contact's app shows buttons (null until it says). A press comes back as `button.pressed` ([Events](#events)) |
169
172
  | `service add <name> <http://127.0.0.1:port>`, `service share <service> <chat> [--off]`, `service list`, `service remove\|enable` | Share a web app on this machine, per contact. `service add` answers the new one as `service` (the id the others take); its old key `serviceId` stays beside it for one release |
170
173
  | `service peer <chat>`, `service open <chat> <service> [--port p]`, `service close <chat> <service>` | A contact's app on a loopback port here (daemon). `url` is a link for your browser, `http://<random>.localhost:<port>/.ghostly-open/<token>`: it sets the service's cookie and shows the app on a host name of its own; any other host name, or a request without that cookie, gets 404. Chrome, Edge and curl reach `*.localhost` names by themselves; Safari and Node's `fetch` on macOS may not (add the name to `/etc/hosts` for them) |
171
- | `settings get [--show-secret]`, `settings set <key> <json>` | Relays, Iroh relays, the HyperDHT relay, ICE servers, `sendTyping` (false: contacts are never told you type), … |
174
+ | `settings get [--show-secret]`, `settings set <key> <json>` | Relays, Iroh relays, the HyperDHT relay, ICE servers, `sendTyping` (false: contacts are never told you type), … `<json>` as `-`, or none on a pipe, is read from stdin: a TURN password stays out of `ps` |
172
175
  | `status` | The profile, its chats, whether WebRTC and calls run, the last event seq |
173
176
  | `store sign <index> --key <file> [--out <dir>]` | Sign a store index (WISP 1200 · Stores) with the store key file (kept offline; made when missing, the index names no `key` and no signed index is in the output folder): writes `ghostly-store.json`, canonical, and `ghostly-store.sig` beside the index or in `--out`. Refused, with the reason, when a client would refuse the index (`expires` more than 90 days ahead, a bad field), or when the index already there has a higher `sequence` (`rollback`), the same one with other content (`equivocation`), or is signed by another key (`store-key`: another store is another `--out`) |
174
177
  | `task send <chat\|group> --title <title> [--status s] [--progress n \| --steps a/b] [--step "…"] [--item state:text]… [--pr-url url --pr-number n --additions n --deletions n --files n --pr-state s --pr-checks c] [--branch b] [--tag label]… [--parent task] [--link url]… [--id id] [--text <text>] [--json json\|-\|file] [--force]`, `task update <chat\|group> <task> [fields…]` | A task card for a bot's work (WISP 405 · Status Cards): a title, a status (queued, running, blocked, done, failed, cancelled), progress, the step it is on, up to 20 steps or log lines (`--item done:Codec`; the card holds at most 8 KiB in all, so 20 long items of non-Latin text are past it; a lowercase word before the colon must be an item state: pending, running, done, failed or skipped) and its pull request, shown as a small card that apps without cards read as text. Optional, and ignored by apps from before them: where the pull request stands (`--pr-state draft`, `open`, `merged` or `closed`; an open one puts the task in the board's Review column) and its checks (`--pr-checks passing`, `failing` or `pending`), up to 3 tags of 24 characters (`--tag core --tag web`; an update's tags replace the card's), and `--parent <task>`, a task of yours in the same chat that this one is a part of (sent first; its parts stack under it on the board). `send` prints the task's id and message; `update` merges the fields given over the card (an update's `--item` list replaces the card's: give all of them) and edits its message, at most once per 2.5 s (sooner updates merge into the next). `--json` takes the whole card; `null` in it removes a field. Without a daemon a card in a chat stays until it went out: `send` until it is sent (`--wait sent`), `update` until the contact confirmed it (`--wait confirmed`), up to `--timeout` (30 s, then exit 4: it goes with the next command); `--wait none` answers at once, as a daemon and a group do by default. Only the CLI sends cards: the app shows them |
175
178
  | `typing <chat> [--kind typing\|recording\|thinking] [--status "<text>"] [--for s] [--stop]` | Show the contact you are writing, recording or thinking, or a short status line in its place ("Transcribing your audio…", 40 characters, no links): live chats only, it holds 6 s there; `--for s` keeps it on that long (up to 600 s; a one-shot stays that long once the chat is live, and stops with `live: false` when it is not live within 15 s); a new kind or status shows at once; a message to the chat or `--stop` ends it |
176
- | `usage send [<chat\|group>] [--all] --left <percent> [--window "5 h"] [--resets <time>] [--label Claude] [--account <name>] [--also week=80@<time>]… [--used n --limit n] [--id id] [--text <text>] [--json json\|-\|file] [--force]` | How much of a quota the bot has left (WISP 405 § Usage): the percent (or `--used` of `--limit`), what it is of, the account, the window, when it resets, and up to 3 other windows (`--also week=80@2026-10-10T00:00:00Z`). The app shows a small meter on the chat's row and in its header, amber under 20%, red under 5%, muted once 6 h old or past the reset. One card per chat: the first report sends it, later ones edit it in place (quiet, paced as `task update`'s); each report is whole, so a field it leaves out goes. Without a daemon a report in a chat stays until it went out (`--wait sent`: the first sent, a later one confirmed by the contact), up to `--timeout`; `--wait none` answers at once. `--all` reports to every 1:1 chat with a contact. See [docs/AI-AGENTS.md](../../docs/AI-AGENTS.md#reporting-usage) for where a bot gets its numbers |
179
+ | `usage send [<chat\|group>] [--all] --left <percent> [--window "5 h"] [--resets <time>] [--label Claude] [--account <name>] [--also week=80@<time>]… [--used n --limit n] [--id id] [--text <text>] [--json json\|-\|file] [--force]` | How much of a quota the bot has left (WISP 405 § Usage): the percent (or `--used` of `--limit`), what it is of, the account, the window, when it resets, and up to 3 other windows (`--also week=80@2026-10-10T00:00:00Z`); `--resets` and `@` take milliseconds or a date (no zone: local time, a bare date local midnight). The app shows a small meter on the chat's row and in its header, amber under 20%, red under 5%, muted once 6 h old or past the reset. One card per chat: the first report sends it, later ones edit it in place (quiet, paced as `task update`'s); each report is whole, so a field it leaves out goes. Without a daemon a report in a chat stays until it went out (`--wait sent`: the first sent, a later one confirmed by the contact), up to `--timeout`; `--wait none` answers at once. `--all` reports to every 1:1 chat with a contact. See [docs/AI-AGENTS.md](../../docs/AI-AGENTS.md#reporting-usage) for where a bot gets its numbers |
177
180
  | `version` | This CLI's version, `{"version":"…"}` (also `ghostly --version`) |
178
181
  | `wallet create <type> [--network testnet] [--provider id] [--value name=value]… [--stdin] [--invite code] [--api-key key]` | A wallet: `cashu`, `lightning` (a card: its source's form in `--value`), `arkade`, `spark` (on Mainnet, `--api-key` is your Breez API key), `bitcoin` (BDK), `fedimint` (`--invite` is the federation's invite code), `usdt`. With `--stdin`, secret fields come as `name=value` lines on stdin (`api-key=…` too), out of `ps` and the shell's history; a `--value` the source's form marks secret (an NWC URI, a macaroon, a rune, an RPC password) is warned about |
179
182
  | `wallet faucet <type>`, `wallet add-mint <url> [--primary]` | Test coins; another Cashu mint |
@@ -217,7 +220,7 @@ ghostly listen --type message.received --exec '
217
220
  [ -n "$file" ] && ghostly file save "$file" --dir ./inbox --wait --timeout 120'
218
221
  ```
219
222
 
220
- `file wait <file>` alone does the waiting: exit `0` when done, `1` with the error when it failed, `4` on timeout.
223
+ `file wait <file>` alone does the waiting: exit `0` when done, `1` with the error when it failed, `4` on timeout, `5` at once when the file waits for `file accept` (over 25 MiB).
221
224
 
222
225
  ### Staying off the direct link
223
226
 
@@ -309,7 +312,9 @@ chat (`chat list`, `chat show`, `chat rename`, …) and `engine getState` print
309
312
  - A message's `from` is `me`, `peer`, or `system` for a group's own line in `group history` (`event`: created, joined,
310
313
  renamed, …; the stream says it as `group.event`): nobody wrote it, whatever `member` key it carries.
311
314
  - `seq` grows by one per event in the profile, across restarts; `id` is the same whenever the same fact is reported.
312
- Dedupe by `id`; resume with `--since <seq>`, or let `--cursor <file>` remember the last event handled.
315
+ Dedupe by `id`; resume with `--since <seq>`, or let `--cursor <file>` remember the last event handled. A cursor
316
+ file that holds no event number (empty, edited by hand) is refused at start (`bad_request`, naming the file): fix or
317
+ remove it, or give `--since`.
313
318
  - Types: `daemon.started`, `chat.created`, `chat.removed`, `chat.renamed`, `chat.pairing` (`stage`: publishing,
314
319
  waiting, resolving, on-dht, live, …), `chat.connection` (`live`, `transport`), `typing.started` (with `kind` and, when given, `status`; again when either changes) and `typing.stopped` (the contact is writing, or stopped: a message, a stop, or 6 s of silence), `chat.joined` (the contact's app
315
320
  announced itself; not a message), `chat.announced`, `message.received` (`message.nick`: the name the contact gave), `message.sent`, `message.delivery`
@@ -321,7 +326,8 @@ chat (`chat list`, `chat show`, `chat rename`, …) and `engine getState` print
321
326
  none: a copy another member handed on without it, completed by the author's, or an edit that names this profile; once), `group.sent`, `group.event`, `file.offered` (a file over 25 MiB waits for `file accept`),
322
327
  `file.stage`, `file.done`, `file.failed` (each with `chat`, or `group` for a group's file, `file`, `messageId`), `chat.held` and
323
328
  `chat.released` (`chat disconnect --hold`), `identity.received` and `identity.status` (what a contact
324
- showed, as checked here), `identity.approval` and `identity.progress` (a signer waits on a link or a code), `group.deleted` (`{group, messageId}`: a group's message deleted, not the group), `group.removed`, `payment.created` and
329
+ showed, as checked here: `identity` with `status`, and `error`, why it is not verified, or null; each change of
330
+ status is a new `identity.status`, even back to one it had before), `identity.approval` and `identity.progress` (a signer waits on a link or a code), `group.deleted` (`{group, messageId}`: a group's message deleted, not the group), `group.removed`, `payment.created` and
325
331
  `payment.updated` (`payment`: id, chat, kind request|payment, direction in|out, amount, memo, state pending|
326
332
  settled|failed, network, method), `call.incoming`, `call.outgoing`, `call.connected` and `call.ended` (voice
327
333
  calls: see [Calls](#calls)), `app.opened` (`chat`, `app`, `version`), `app.closed` (`chat`, `app`, and `offline`
@@ -355,8 +361,10 @@ chat (`chat list`, `chat show`, `chat rename`, …) and `engine getState` print
355
361
  unpinned), `ref` the id both sides know it by, and `by` `peer` or a member key.
356
362
  - `--type message.received` keeps one type; `--type message` (or `message.`, `message.*`) a family. A family deeper
357
363
  down ends in "." (`group.typing.`): `group.message` is that type alone.
358
- - `--from <chat|key>` and `--group <group>` (again for more): an allowlist. Only the chats (id, prefix, name, or the
359
- contact's `peer` key, which also matches a chat made later) and groups named get through; any other chat's or
364
+ - `--from <chat|key>` and `--group <group>` (again for more): an allowlist. Only the chats (id, a label given here,
365
+ or the contact's `peer` key, which also matches a chat made later) and groups (id, prefix or name) named get through;
366
+ a prefix of a chat's id or the name its contact gave itself is refused (another contact could call itself that:
367
+ name the chat first with `chat rename`); any other chat's or
360
368
  group's event stops before `--exec`, `--webhook` and stdout (the message stays in the chat; the cursor moves past
361
369
  it). The profile's own events (`daemon.started`, `events.gap`, `identity.approval`) pass. Names become ids once,
362
370
  at the start. A flag, not profile state: each listener (each agent) has its own ([docs/CLI.md](../../docs/CLI.md#allowlist)).
@@ -377,6 +385,8 @@ chat (`chat list`, `chat show`, `chat rename`, …) and `engine getState` print
377
385
  apart, and the cursor stays before it until the bridge takes it. A 4xx or a redirect (not followed) passes the event
378
386
  as not taken.
379
387
  - With no daemon running, `listen` becomes the daemon (socket included), so a hook can answer with `ghostly send`.
388
+ `daemon stop` or `daemon restart` then ends that listen too: it exits 1 (`unavailable`) with a line on stderr, and
389
+ the stop's answer carries `listen: true`, as `daemon status` does while it runs. Start `ghostly daemon --detach` first for a listen that follows a restart.
380
390
  - `--translate <lang>`: received messages carry a translation, once the CLI has a language detector ([Translation](#translation)).
381
391
 
382
392
  As the app's chat screen does, the side that joined a chat says `👋 <name> joined` once it first goes live, and the
@@ -506,9 +516,10 @@ default route (seen with NordVPN on the same Mac as the CLI) makes the app send
506
516
  nothing on that machine can answer: allow local network traffic in the VPN, or pause it.
507
517
 
508
518
  **A TURN relay.** Calls use the apps' STUN servers, then the profile's own ICE servers:
509
- `ghostly settings set iceServers '[{"urls":"turn:turn.example.org:3478","username":"…","credential":"…"}]'` (the
510
- same setting chats use). A relay connects the calls no direct path can: a VPN that takes every packet through its
511
- tunnel, a NAT that maps each destination apart. The media stays encrypted end to end; the relay sees both
519
+ `… | ghostly settings set iceServers -` with `[{"urls":"turn:turn.example.org:3478","username":"…","credential":"…"}]`
520
+ on stdin (the same setting chats use). On stdin, the password stays out of `ps` and the shell's history; given as an
521
+ argument it is still taken, with a warning. A relay connects the calls no direct path can: a VPN that takes every
522
+ packet through its tunnel, a NAT that maps each destination apart. The media stays encrypted end to end; the relay sees both
512
523
  addresses and when and how much is sent. The CLI (libdatachannel) reaches TURN over UDP only: a `turns:` or
513
524
  `?transport=tcp` address stays in the setting for the apps, which use it, and `settings set` warns that the CLI does
514
525
  not. Behind a network that blocks UDP, the CLI has no relay. libdatachannel never gives a relay back when a call
package/SKILL.md CHANGED
@@ -272,7 +272,8 @@ ghostly routine update owner nightly --state paused
272
272
  ```
273
273
 
274
274
  `--schedule` is words people read (80 characters) and `--cron` is only shown. `--run ok|failed|skipped[:summary]`
275
- records a run as the last one (the card keeps 10); `--next` takes a date or milliseconds, up to a year ahead.
275
+ records a run as the last one (the card keeps 10); `--next` takes a date or milliseconds, up to a year ahead: `2026-10-01` and
276
+ `2026-10-01 01:00` are local time (a date alone is local midnight), `2026-10-01T01:00:00Z` or `+02:00` keep their zone.
276
277
 
277
278
  ### 11. Safety
278
279
 
@@ -296,8 +297,9 @@ records a run as the last one (the card keeps 10); `--next` takes a date or mill
296
297
 
297
298
  - **No daemon, and `listen` takes the profile.** With no daemon running, `listen` opens the profile itself and serves
298
299
  its socket, so it becomes the daemon: `daemon --detach` then fails ("A daemon already runs profile …"), and when
299
- that listener stops, the profile goes offline with it. Start `ghostly daemon --detach` first, so `listen` only
300
- subscribes. Any other command with no daemon runs the profile for that one command and exits.
300
+ that listener stops, the profile goes offline with it. `daemon stop` and `daemon restart` (the advice after an
301
+ upgrade) end such a listener: it exits 1 with a line on stderr, and the restarted daemon has no reader. Start
302
+ `ghostly daemon --detach` first, so `listen` only subscribes and follows a restart. Any other command with no daemon runs the profile for that one command and exits.
301
303
  - **A headless session is not woken later.** An agent whose session ends (a `-p` run, a closed chat) hears nothing
302
304
  when a message arrives. Keep a listener process running (`ghostly listen --turns … --exec`) under something that
303
305
  outlives the session, and let it start the agent once per turn.
@@ -385,7 +387,7 @@ needs a person who holds the key: leave that to the owner.
385
387
  ## Rules the CLI enforces
386
388
 
387
389
  - Output is JSON. A failure is `{"error":{"code","message"}}` with exit 1 (failed), 2 (usage), 3 (not found),
388
- 4 (timed out) or 5 (needs `--force`, `--yes` or `--confirm-real`).
390
+ 4 (timed out), 5 (needs `--force`, `--yes` or `--confirm-real`) or 130 (stopped with Ctrl-C, `interrupted`).
389
391
  - `send` (and `ghostly engine sendMessage` and the other sends through `engine`) refuses text that looks like a recovery
390
392
  phrase, a private key or a Cashu token unless `--force`.
391
393
  - Spending real money (Mainnet) needs `--confirm-real`.
@@ -1,3 +1,3 @@
1
- import { c as findGroup, o as findChat } from "./apiKit-DJb9hulp.js";
2
- import { a as hideStateSecrets, i as groupSendRefused, n as SETTABLE, o as mentionsFor, r as callApi, s as redactSettings, t as API_METHODS } from "./api-tf-wAAnB.js";
1
+ import { c as findGroup, o as findChat } from "./apiKit-C-_PWZvy.js";
2
+ import { a as hideStateSecrets, i as groupSendRefused, n as SETTABLE, o as mentionsFor, r as callApi, s as redactSettings, t as API_METHODS } from "./api-I_KbuXHa.js";
3
3
  export { API_METHODS, SETTABLE, callApi, findChat, findGroup, groupSendRefused, hideStateSecrets, mentionsFor, redactSettings };