@bendyline/gezel-cli 1.2.3 → 1.2.4

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 CHANGED
@@ -104,6 +104,21 @@ gezel --home /path/to/another-home # standalone with an alternate home
104
104
  An explicit `--port 6228` remains available when you intentionally want a
105
105
  CLI-owned daemon on the canonical port.
106
106
 
107
+ ## One-shot prompts and pipelines
108
+
109
+ Use `gezel run -` to read a UTF-8 prompt from a pipe or redirected file. It
110
+ reads until EOF and preserves line breaks and indentation:
111
+
112
+ ```bash
113
+ printf 'Summarize these notes:\nThe launch is Friday.\n' | gezel run -
114
+ gezel run - < prompt.txt
115
+ ```
116
+
117
+ The reply goes to stdout, so you can redirect it to a file; diagnostics go to
118
+ stderr. Empty or whitespace-only input exits with status 1 before connecting
119
+ to a service. A sole `-` is required to read stdin; `gezel run "your prompt"`
120
+ continues to use its arguments, and bare `gezel run` shows usage.
121
+
107
122
  ## Provider credentials
108
123
 
109
124
  Manage provider keys through the service credential store, using stdin or an
@@ -112,7 +127,8 @@ existing environment variable so the value does not appear in command arguments:
112
127
  ```bash
113
128
  gezel secret list
114
129
  gezel secret set braveSearchApiKey --env BRAVE_SEARCH_API_KEY --use-for-search
115
- gezel secret set openaiApiKey --stdin < /path/to/private-key-file
130
+ gezel secret set openaiApiKey --env OPENAI_API_KEY
131
+ gezel secret set anthropicApiKey --env ANTHROPIC_API_KEY
116
132
  gezel secret remove openaiApiKey
117
133
  ```
118
134
 
@@ -125,6 +141,10 @@ This covers the built-in provider credentials, including webhooks; it is not an
125
141
  arbitrary environment-variable store. Storage uses the same native keyring or
126
142
  encrypted fallback as the application.
127
143
 
144
+ After saving an OpenAI or Anthropic key, run `gezel` and use `/model` to choose
145
+ one of that provider's available models. The desktop app and CLI share the same
146
+ daemon credential store, so a key saved in either interface is available to both.
147
+
128
148
  Search also requires the selected environment to allow external services.
129
149
  `gezel security external-services` shows that setting; append `on` or `off` to
130
150
  change it explicitly while preserving all other security capabilities. This
@@ -149,10 +169,24 @@ Both settings commands support `--json` and the ordinary connection/home flags.
149
169
 
150
170
  ## Batch craftbooks and repository workflows
151
171
 
152
- `do` accepts positional parameters in the recipe's `paramSchema.properties`
153
- order, `key=value` arguments, and repeatable `--param key=value` options:
172
+ `do` takes the craftbook, then its values. A bare value fills the next
173
+ required parameter the recipe asks people for, in `paramSchema.properties`
174
+ order. `key=value` and repeatable `--param key=value` set any parameter,
175
+ including ones launch forms hide, such as `workPath`. Every other word is your
176
+ request. It becomes the task description and, when the recipe declares one,
177
+ its main content parameter (`fromMessage`, else `topic`). Quoting is optional;
178
+ unquoted words are joined.
179
+
180
+ Any craftbook also runs by name: `gezel story-batch c23n` is
181
+ `gezel do story-batch c23n`. The name must match the craftbook's `command`
182
+ token (its id unless it declares one) exactly. Built-in commands always win.
183
+ A mistyped name reports an unknown command without creating a project, and
184
+ the expanded `gezel do …` line is printed to stderr. Workflow craftbooks
185
+ (below) run repository code, so they start only through `gezel do`.
154
186
 
155
187
  ```bash
188
+ gezel do summarize-long "Summarize notes.txt for the board"
189
+ gezel summarize-long "Summarize notes.txt for the board"
156
190
  gezel do story-batch c23n limit=3 --wait --json
157
191
  gezel task wait my-project/12 --timeout 7200 --json
158
192
  gezel task resume my-project/12 --json
@@ -215,13 +249,52 @@ also work: `gezel workflow ./pipeline/storyify.mjs c23n`.
215
249
 
216
250
  To expose that driver as one command, add
217
251
  `"cliWorkflow": { "module": ".gezel/workflows/storyify.mjs" }` to a project
218
- craftbook and declare its inputs in `paramSchema`. Then run
252
+ craftbook and declare its inputs in `paramSchema`, listing the ones a bare
253
+ value should fill under `required`. Then run
219
254
  `gezel do my-batch c23n limit=200 --json`. Its module receives `craftbook` and
220
- validated explicit `params` in addition to the context above. The driver owns
255
+ validated explicit `params` in addition to the context above. A workflow
256
+ craftbook takes no request text. The driver owns
221
257
  parent creation, defaults, checkpoints, bounded child concurrency, and the
222
258
  final result. Modules must resolve inside the project workspace. Only project
223
259
  craftbooks can use this entry point; `--strict-sandbox` rejects it.
224
260
 
261
+ ### Declaring what a craftbook needs
262
+
263
+ A craftbook can declare the chat models it runs on and the capabilities it
264
+ cannot run without. `gezel do` checks them before anything starts:
265
+
266
+ ```json
267
+ "services": [{ "kind": "web-search", "reason": "research checks every fact" }],
268
+ "models": [
269
+ { "id": "qwen3.8-27b-q4", "reason": "writes the stories" },
270
+ { "id": "{{checkerModel}}", "provider": "llama-cpp", "reason": "checks every sentence" }
271
+ ]
272
+ ```
273
+
274
+ `web-search` means a keyed search provider (Brave): Wikipedia does not count,
275
+ and it implies `external-services`, which a book that only fetches pages can
276
+ declare on its own. A model `id` (or `provider`) may be a `{{param}}`
277
+ reference, resolved from the run's value or its `paramSchema` default; one
278
+ that resolves to nothing is skipped. `provider` defaults to this computer's
279
+ on-device engine.
280
+
281
+ At a terminal, each missing piece is one question: turn on External services
282
+ (naming the security level it moves to), paste a Brave Search API key (hidden,
283
+ then proven with one test search, and removed again if that fails), and
284
+ download the models (after a disk-space check, with the engine if it is
285
+ missing). Any "no", or a run without a terminal, stops before the run starts
286
+ and prints the commands that fix it:
287
+
288
+ ```text
289
+ gezel security external-services on
290
+ gezel secret set braveSearchApiKey --env BRAVE_SEARCH_API_KEY --use-for-search
291
+ gezel model pull qwen3.8-27b-q4 --provider llama-cpp
292
+ ```
293
+
294
+ A workflow module whose models depend on its own options asks at run time with
295
+ `ensureSetup({ services, models })` on its context, which behaves the same way.
296
+ `runCraftbook` checks the child book's declared needs too.
297
+
225
298
  These drivers run in the foreground even without `--wait`; keep the terminal
226
299
  open until completion. A timeout applies to each child wait. If the CLI exits,
227
300
  already-created daemon tasks survive, but further orchestration requires the
@@ -265,12 +338,12 @@ Add it where Gezel is installed (drop `-g` for a project install); the desktop
265
338
  app already includes it:
266
339
 
267
340
  ```bash
268
- npm install -g @huggingface/transformers@^3.8.1
341
+ npm install -g @huggingface/transformers@^4.3.1
269
342
  ```
270
343
 
271
344
  In a project install, also add the `overrides` from the
272
- [`@bendyline/gezel-service` README](https://www.npmjs.com/package/@bendyline/gezel-service):
273
- Transformers still asks for a `sharp` release that `npm audit` flags.
345
+ [`@bendyline/gezel-service` README](https://www.npmjs.com/package/@bendyline/gezel-service),
346
+ which keep Kokoro on the same Transformers.js copy as the service.
274
347
 
275
348
  ## Running models on your own machine
276
349
 
@@ -313,13 +386,14 @@ Run `gezel --help` for the full list. The most-used ones:
313
386
  | Command | What it does |
314
387
  |---|---|
315
388
  | `gezel` | Launch the interactive TUI |
316
- | `gezel run [prompt…]` | One-shot prompt in the current directory's project, using its voorman by default; optionally `--gezel <id>` / `--project <folder>` |
317
- | `gezel do <craftbook…>` | Start a craftbook as an immediately dispatched task in the current directory's project; accepts its id or display name |
389
+ | `gezel run [prompt…]` | One-shot prompt (a sole `-` reads stdin) in the current directory's project, using its voorman by default; optionally `--gezel <id>` / `--project <folder>` |
390
+ | `gezel do <craftbook…>` | Start a craftbook as an immediately dispatched task in the current directory's project; accepts its id, command, or display name, then required values, `key=value` parameters, and your request |
391
+ | `gezel <craftbook> …` | Shorthand for `gezel do <craftbook> …`, matched exactly on the craftbook's command or id; built-in commands always win |
318
392
  | `gezel workflow <name-or-file> [args…]` | Run an explicitly trusted repository workflow from `.gezel/workflows/<name>.mjs` or a module path |
319
393
  | `gezel secret list / set / remove` | Manage write-only provider credentials, including the Brave search key |
320
394
  | `gezel task wait <ref>` / `resume <ref>` | Follow a task to completion, or retry a paused task and follow it |
321
395
  | `gezel task notes <ref> --warnings` | Read task notes and runtime warnings from its recent sessions |
322
- | `gezel start` / `stop` / `status` | Use or inspect the selected service. `stop` is the same hard stop as the desktop UX: cancel work, unload local engines, and switch to Reactive. `stop --daemon` shuts down a user-owned daemon process itself. `start --web` serves the browser UI. On hosts without a Gezel machine service, a started daemon prefers the canonical port 6228 (ephemeral fallback) so third-party OpenAI clients get a stable `https://127.0.0.1:6228/v1` base URL; with a machine service installed, the service owns 6228 and started daemons use an ephemeral port (`--port` pins one explicitly). |
396
+ | `gezel start` / `stop` / `status` | Use or inspect the selected service. `stop` is the same hard stop as the desktop UX: cancel work, unload local engines, and switch to Reactive. `stop --daemon` shuts down a user-owned daemon process itself. `start --web` serves the browser UI, reusing a daemon that already serves it; when a daemon is running without it, `start --web --restart` replaces that daemon (the same applies to `--port`). On hosts without a Gezel machine service, a started daemon prefers the canonical port 6228 (ephemeral fallback) so third-party OpenAI clients get a stable `https://127.0.0.1:6228/v1` base URL; with a machine service installed, the service owns 6228 and started daemons use an ephemeral port (`--port` pins one explicitly). |
323
397
  | `gezel doctor` | Report on the local install |
324
398
  | `gezel mode [read-only\|reactive\|reactive+tasks\|full-play]` | Show or change how much AI activity is allowed |
325
399
  | `gezel agent list\|create\|show` | Manage your gezels |
@@ -270,7 +270,7 @@ Working style: short, warm answers. When the user mentions something worth keepi
270
270
 
271
271
  // src/connection.ts
272
272
  import { createHash, randomUUID } from "crypto";
273
- import { chmod, mkdir, readFile, rm, writeFile } from "fs/promises";
273
+ import { chmod, mkdir, readFile, realpath, rm, writeFile } from "fs/promises";
274
274
  import { homedir } from "os";
275
275
  import { basename, dirname, join, resolve } from "path";
276
276
  import {
@@ -1,13 +1,13 @@
1
1
  #!/usr/bin/env node
2
2
 
3
3
  // src/app-command.ts
4
- import { readFile as readFile2, realpath } from "fs/promises";
4
+ import { readFile as readFile2, realpath as realpath2 } from "fs/promises";
5
5
  import { isAbsolute, join as join2, resolve as resolve2 } from "path";
6
6
  import { compareSemver } from "@bendyline/gezel";
7
7
 
8
8
  // src/connection.ts
9
9
  import { createHash, randomUUID } from "crypto";
10
- import { chmod, mkdir, readFile, rm, writeFile } from "fs/promises";
10
+ import { chmod, mkdir, readFile, realpath, rm, writeFile } from "fs/promises";
11
11
  import { homedir } from "os";
12
12
  import { basename, dirname, join, resolve } from "path";
13
13
  import {
@@ -307,7 +307,7 @@ async function runAppSetEnabled(client, appId, enabled) {
307
307
  }
308
308
  async function findProjectForFolder(projects, folder) {
309
309
  const requested = resolve2(folder);
310
- const real = await realpath(requested).catch(() => requested);
310
+ const real = await realpath2(requested).catch(() => requested);
311
311
  const fold = (p) => process.platform === "win32" || process.platform === "darwin" ? p.toLowerCase() : p;
312
312
  const wanted = /* @__PURE__ */ new Set([fold(requested), fold(real)]);
313
313
  return projects.find((project) => !!project.workingDir && wanted.has(fold(project.workingDir)));