@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 +99 -16
- package/dist/app-author-command.js +1 -1
- package/dist/app-command.js +3 -3
- package/dist/bin/gezel-main.js +995 -453
- package/dist/handboek-export.js +564 -8
- package/dist/knowledge-command.js +82 -7
- package/dist/tui/index.js +5 -2
- package/package.json +10 -10
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
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
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 --
|
|
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`
|
|
144
|
-
|
|
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
|
|
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.
|
|
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.
|
|
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
|
-
|
|
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 {
|
package/dist/app-command.js
CHANGED
|
@@ -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
|
|
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)));
|