@bendyline/gezel-cli 1.2.2 → 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
@@ -54,17 +54,26 @@ With no connection flags, the CLI follows this order:
54
54
  service that stops with the command. The interactive TUI
55
55
  retains ownership when it starts a daemon itself, so exiting the TUI runs
56
56
  the daemon's complete shutdown path and cleans up its local engine children.
57
- 3. On first use, the terminal waits while the Gezel app asks you to approve
58
- **Gezel CLI**. The terminal shows a six-character code that you enter in
59
- the app to confirm that you initiated the request. The resulting revocable,
60
- CLI-scoped credential is saved under `~/.gezel/cli/tokens/`. Its logical
61
- local key survives daemon port and certificate rotation.
57
+
58
+ For the per-user local daemon, the CLI connects with your same-user owner
59
+ credential from the protected runtime directory. This works on first use and
60
+ when adopting an already-running daemon, with no desktop approval prompt. The
61
+ npm package is sufficient for local CLI use; you do not need to install or open
62
+ the desktop app.
62
63
 
63
64
  `gezel run` has one deliberate lifecycle exception: if no user daemon exists,
64
65
  it starts a user-role service in-process for that one invocation and stops it
65
66
  afterward. It does not take that fallback after a denied grant or when a live
66
67
  daemon is unhealthy.
67
68
 
69
+ External service connections use a separate authorization path: an explicit
70
+ `--connect <url>`, or an older `legacy-full` machine service selected in step 1,
71
+ requires a CLI-scoped grant. If there is no valid saved grant or supplied
72
+ `--token`, the terminal shows a six-character code and waits for you to approve
73
+ **Gezel CLI** in the Gezel app. The resulting revocable credential is saved
74
+ under `~/.gezel/cli/tokens/` for that service. A valid saved grant or explicit
75
+ `--token` lets the connection proceed without that interaction.
76
+
68
77
  The per-user daemon owns gezels, projects, settings, credentials, and
69
78
  conversations with ordinary user filesystem permissions. It discovers the
70
79
  machine engine broker independently for centralized model downloads and local
@@ -95,6 +104,21 @@ gezel --home /path/to/another-home # standalone with an alternate home
95
104
  An explicit `--port 6228` remains available when you intentionally want a
96
105
  CLI-owned daemon on the canonical port.
97
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
+
98
122
  ## Provider credentials
99
123
 
100
124
  Manage provider keys through the service credential store, using stdin or an
@@ -103,7 +127,8 @@ existing environment variable so the value does not appear in command arguments:
103
127
  ```bash
104
128
  gezel secret list
105
129
  gezel secret set braveSearchApiKey --env BRAVE_SEARCH_API_KEY --use-for-search
106
- 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
107
132
  gezel secret remove openaiApiKey
108
133
  ```
109
134
 
@@ -116,6 +141,10 @@ This covers the built-in provider credentials, including webhooks; it is not an
116
141
  arbitrary environment-variable store. Storage uses the same native keyring or
117
142
  encrypted fallback as the application.
118
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
+
119
148
  Search also requires the selected environment to allow external services.
120
149
  `gezel security external-services` shows that setting; append `on` or `off` to
121
150
  change it explicitly while preserving all other security capabilities. This
@@ -140,10 +169,24 @@ Both settings commands support `--json` and the ordinary connection/home flags.
140
169
 
141
170
  ## Batch craftbooks and repository workflows
142
171
 
143
- `do` accepts positional parameters in the recipe's `paramSchema.properties`
144
- 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`.
145
186
 
146
187
  ```bash
188
+ gezel do summarize-long "Summarize notes.txt for the board"
189
+ gezel summarize-long "Summarize notes.txt for the board"
147
190
  gezel do story-batch c23n limit=3 --wait --json
148
191
  gezel task wait my-project/12 --timeout 7200 --json
149
192
  gezel task resume my-project/12 --json
@@ -206,13 +249,52 @@ also work: `gezel workflow ./pipeline/storyify.mjs c23n`.
206
249
 
207
250
  To expose that driver as one command, add
208
251
  `"cliWorkflow": { "module": ".gezel/workflows/storyify.mjs" }` to a project
209
- 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
210
254
  `gezel do my-batch c23n limit=200 --json`. Its module receives `craftbook` and
211
- 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
212
257
  parent creation, defaults, checkpoints, bounded child concurrency, and the
213
258
  final result. Modules must resolve inside the project workspace. Only project
214
259
  craftbooks can use this entry point; `--strict-sandbox` rejects it.
215
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
+
216
298
  These drivers run in the foreground even without `--wait`; keep the terminal
217
299
  open until completion. A timeout applies to each child wait. If the CLI exits,
218
300
  already-created daemon tasks survive, but further orchestration requires the
@@ -256,12 +338,12 @@ Add it where Gezel is installed (drop `-g` for a project install); the desktop
256
338
  app already includes it:
257
339
 
258
340
  ```bash
259
- npm install -g @huggingface/transformers@^3.8.1
341
+ npm install -g @huggingface/transformers@^4.3.1
260
342
  ```
261
343
 
262
344
  In a project install, also add the `overrides` from the
263
- [`@bendyline/gezel-service` README](https://www.npmjs.com/package/@bendyline/gezel-service):
264
- 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.
265
347
 
266
348
  ## Running models on your own machine
267
349
 
@@ -304,13 +386,14 @@ Run `gezel --help` for the full list. The most-used ones:
304
386
  | Command | What it does |
305
387
  |---|---|
306
388
  | `gezel` | Launch the interactive TUI |
307
- | `gezel run [prompt…]` | One-shot prompt in the current directory's project, using its voorman by default; optionally `--gezel <id>` / `--project <folder>` |
308
- | `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 |
309
392
  | `gezel workflow <name-or-file> [args…]` | Run an explicitly trusted repository workflow from `.gezel/workflows/<name>.mjs` or a module path |
310
393
  | `gezel secret list / set / remove` | Manage write-only provider credentials, including the Brave search key |
311
394
  | `gezel task wait <ref>` / `resume <ref>` | Follow a task to completion, or retry a paused task and follow it |
312
395
  | `gezel task notes <ref> --warnings` | Read task notes and runtime warnings from its recent sessions |
313
- | `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). |
314
397
  | `gezel doctor` | Report on the local install |
315
398
  | `gezel mode [read-only\|reactive\|reactive+tasks\|full-play]` | Show or change how much AI activity is allowed |
316
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)));