@bendyline/gezel-cli 1.2.13 → 1.3.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 CHANGED
@@ -1,7 +1,7 @@
1
1
  # @bendyline/gezel-cli
2
2
 
3
- The `gezel` command line: assemble a team of AI companions (*gezels*) and put
4
- them to work from your terminal.
3
+ The `gezel` command line: put AI to work on your files and projects from your
4
+ terminal.
5
5
 
6
6
  ## Quick start
7
7
 
@@ -69,27 +69,31 @@ Run `gezel --help`, or `--help` on any command, for every option.
69
69
  | `gezel do <craftbook…>` | Start a craftbook as a task in this folder's project: its name, then required values, `key=value` parameters, and your request. `--wait` follows it to the end |
70
70
  | `gezel <craftbook> …` | Shorthand for `gezel do <craftbook> …`, matched exactly on the craftbook's command name; built-in commands always win |
71
71
  | `gezel craftbook list [words…]` | List the craftbooks `gezel do` can start in this folder's project (command name, title, category); words filter by command, title, and tags. `--json` for scripts |
72
+ | `gezel craftbook show <craftbook>` | What one craftbook does, what it takes before your request, and where it saves |
72
73
  | `gezel workflow <name-or-file> [args…]` | Run a repository workflow from `.gezel/workflows/<name>.mjs` or a module path |
73
74
  | `gezel task list\|show\|create` | Tasks across every project |
74
- | `gezel task wait\|resume\|pause <ref>` | Follow a task to the end, retry a paused task and follow it, or pause one task |
75
+ | `gezel task wait\|resume\|pause <ref>` | Follow a task to the end, retry a paused task and follow it, or pause one task. Waiting prints where the result is; `--out <dir>` copies it |
75
76
  | `gezel task notes <ref>` | A task's notes, including pause reasons and failed checks (`--warnings` adds runtime warnings) |
76
- | `gezel agent list\|create\|show\|output-limit` | Manage your gezels (the command name is historical) |
77
- | `gezel project list\|create\|install\|indexing` | Manage projects, their npm packages, and background indexing (`gezel env` is the same command) |
77
+ | `gezel agent list\|create\|show\|output-limit` | Manage your crew (the command name is historical) |
78
+ | `gezel project list\|create\|install\|indexing\|edits` | Manage projects, their npm packages, background indexing, and whether Gezel may change files in the folder (`gezel env` is the same command) |
79
+ | `gezel integrations list\|approve\|deny\|token` | The apps connected to this Gezel: answer one that asked to connect, or make and revoke app keys |
80
+ | `gezel integrations address` | Where other programs reach this Gezel's models |
81
+ | `gezel integrations ollama [on\|off]` | A plain-HTTP port on this computer that needs no key (`http://127.0.0.1:11434/v1`, and Ollama's own paths); off until you turn it on |
78
82
  | `gezel skills list\|import\|convert` | Find SKILL.md skills and turn them into craftbooks |
79
83
  | `gezel app …` | Build, install, apply, and serve AI Apps (`.gezapp`): `new`, `validate`, `pack`, `add`, `update`, `list`, `show`, `apply`, `status`, `serve`, `enable`, `disable`, `remove`, `schemas` |
80
- | `gezel model list\|pull\|use\|export` | On-device chat models. `list --available` shows the catalog models that fit this machine, with sizes; `use <id>` makes chats use a downloaded model (a pull does this itself when no working default is set); `export <id> [file]` writes a portable, checksum-verified `.gezmodel` |
84
+ | `gezel model list\|pull\|use\|export` | On-device chat models. `list --available` shows the catalog models that fit this machine, with sizes; `pull <id>` downloads one, plus the engine it runs on if that is missing; `use <id>` makes chats use a downloaded model (a pull does this itself when no working default is set); `export <id> [file]` writes a portable, checksum-verified `.gezmodel` |
81
85
  | `gezel model context\|concurrency` | A local model's context window, and how many requests a local engine serves at once |
82
86
  | `gezel native install\|list\|status` | The native engines that run models on this computer |
83
87
  | `gezel image status\|models\|pull\|rm` | Image-generation models |
84
88
  | `gezel create-image\|create-video\|create-audio` | Generate an image, a video, or spoken audio |
85
89
  | `gezel knowledge …` | Build, check, and search `.gezk` knowledge catalogs (`init`, `build`, `validate`, `inspect`, `export-parquet`, `search`, `nearby`), and manage the ones installed in Gezel (`available`, `install`, `list`, `remove`, `find`) |
86
90
  | `gezel secret list\|set\|remove` | Provider keys, stored write-only |
87
- | `gezel security external-services [on\|off]` | Whether gezels may use web search and other outside services |
91
+ | `gezel security external-services [on\|off]` | Whether Gezel may use web search and other outside services |
88
92
  | `gezel mode [mode]` | Show or set how active the AI may be: `read-only`, `reactive`, `reactive+tasks`, or `full-play` |
89
93
  | `gezel start` / `status` / `stop` | Start, check, or stop your Gezel service (see [Starting and stopping](#starting-and-stopping)) |
90
94
  | `gezel doctor` | Check the installation |
91
95
  | `gezel cleanup` | Show or reclaim the space Gezel uses on this device (`--redownloadable`, `--models`, `--dry-run`, …) |
92
- | `gezel backup <file>` / `restore <file>` | Write your gezels, projects, and documents to a backup file, or bring them back (`restore --list` looks first) |
96
+ | `gezel backup <file>` / `restore <file>` | Write your crew, projects, and documents to a backup file, or bring them back (`restore --list` looks first) |
93
97
  | `gezel handboek export --out <dir>` | Render the Handboek, Gezel's built-in documentation, as a static website |
94
98
 
95
99
  ## Starting and stopping
@@ -112,12 +116,13 @@ emergency brake on it and says the service is managed by the operating system.
112
116
 
113
117
  Inside the interactive app, `/mode` switches the same four activity levels and
114
118
  `/model` lists every installed model, with **Download a new model** to fetch
115
- another; the download is selected for the active gezel and starts a fresh chat.
119
+ another; the download is selected for the active crew member and starts a fresh
120
+ chat.
116
121
  `/continue` processes due schedules and picks up the current project's active
117
122
  tasks, and `/nightshift start|stop|list` manages Night Shift. `/allow edits` and
118
123
  `/disallow edits` let Gezel's own tools and background work edit the current
119
124
  project, or make it read-only for them; `codexedits` and `claudeedits` do the
120
- same for gezels that run on the Codex or Claude command-line tools.
125
+ same when Gezel runs on the Codex or Claude command-line tools.
121
126
 
122
127
  ## One-shot prompts and pipelines
123
128
 
@@ -180,7 +185,7 @@ Three settings help with long unattended batches:
180
185
 
181
186
  ## Craftbooks from the command line
182
187
 
183
- A craftbook is a recipe for a piece of work that gezels carry out as a task.
188
+ A craftbook is a recipe for a piece of work that Gezel carries out as a task.
184
189
  `gezel craftbook list` shows the ones you can start in the current folder's
185
190
  project, and `gezel craftbook list deck` narrows the list by command, title,
186
191
  and tags.
@@ -198,10 +203,11 @@ name (its id, unless it declares one) exactly, and built-in commands always
198
203
  win. A mistyped name reports an unknown command without creating a project.
199
204
 
200
205
  ```bash
201
- gezel do summarize-long "Summarize notes.txt for the board"
206
+ gezel do summarize-long "Summarize notes.txt for the board" --out ./board-summary
202
207
  gezel summarize-long "Summarize notes.txt for the board"
203
208
  gezel do powerpoint-deck "A deck about Delft" audience=investors --wait --json
204
209
  gezel task wait my-project/12 --timeout 7200 --json
210
+ gezel task wait my-project/12 --out ./board-summary
205
211
  gezel task resume my-project/12 --json
206
212
  gezel task notes my-project/12 --warnings --json
207
213
  ```
@@ -214,6 +220,35 @@ timeout leaves the task running. When a task is blocked, `--wait` prints why
214
220
  stderr; `--json` writes the result to stdout. `resume` retries a paused task
215
221
  with its saved recipe. Answer pending questions in Gezel before waiting again.
216
222
 
223
+ When a task completes, waiting prints where its result is:
224
+
225
+ ```text
226
+ work/1: complete
227
+ Result: /Users/you/.gezel/projects/work/artifacts/tasks/1/summary.md
228
+ Also made: scope.md, verdict.md
229
+ Folder: /Users/you/.gezel/projects/work/artifacts/tasks/1
230
+ ```
231
+
232
+ `--json` carries the same under `output`: each file's `relativePath`, its
233
+ absolute `path` on the computer running Gezel, whether this command can open it
234
+ (`readable`), and which one is the `deliverable`. When Gezel runs somewhere this
235
+ command cannot read (a remote service, a container, or a machine-wide service),
236
+ the paths are not yours to open; copy the files instead.
237
+
238
+ A folder's project starts read-only. Most craftbooks keep what they make in
239
+ the task's own folder, which `--out <dir>` copies out when the task finishes;
240
+ `gezel task wait <ref> --out <dir>` copies a finished task's.
241
+ Some save into the folder itself, such as a deck or a web page;
242
+ `gezel craftbook show <craftbook>` says which. At a terminal `gezel do` asks
243
+ before it starts one of those. In a script, add `--allow-edits`, or run
244
+ `gezel project edits on` once in the folder. A task that stops because the
245
+ folder is read-only prints that command and the `gezel task resume` that
246
+ continues it.
247
+
248
+ Some craftbooks need a file or a branch before the request.
249
+ `gezel craftbook show <craftbook>` prints the start line with those in place,
250
+ for example `gezel do meeting-notes-to-actions <source> "your request"`.
251
+
217
252
  ### Repository workflows
218
253
 
219
254
  For scripted orchestration around several craftbooks, add a module under
@@ -336,7 +371,7 @@ download only when you choose on-device models. Straight away you can use:
336
371
  first use, and one-shot prompts (`gezel run "…"`) once a model is set up.
337
372
  - Cloud providers: OpenAI, Anthropic, GitHub Copilot, and any OpenAI-compatible
338
373
  endpoint.
339
- - Your gezels, projects, and tasks (`gezel agent`, `gezel project`,
374
+ - Your crew, projects, and tasks (`gezel agent`, `gezel project`,
340
375
  `gezel task`).
341
376
  - `gezel skills convert` and `gezel handboek export`, which need no running
342
377
  service at all.
@@ -352,6 +387,11 @@ app already includes it:
352
387
  npm install -g @huggingface/transformers@^4.3.1
353
388
  ```
354
389
 
390
+ npm 12 then reports that the install scripts of `onnxruntime-node` and
391
+ `protobufjs` were blocked. That is expected and harmless: the first only
392
+ downloads CUDA libraries Gezel does not use, and the second only checks
393
+ versions.
394
+
355
395
  In a project install, also add the `overrides` from the
356
396
  [`@bendyline/gezel-service` README](https://www.npmjs.com/package/@bendyline/gezel-service),
357
397
  which keep Kokoro on the same Transformers.js copy as the service.
@@ -400,7 +440,7 @@ machine-wide service, that service owns 6228. A current machine-wide service
400
440
  only runs models: the CLI never sends it projects, keys, or tools, and your own
401
441
  service uses it for model downloads and inference. While you upgrade from an
402
442
  older desktop release, an older machine-wide service that still holds your
403
- gezels and projects is used instead; `--standalone` skips it.
443
+ crew and projects is used instead; `--standalone` skips it.
404
444
 
405
445
  Your own service may reuse two things the desktop app's machine install
406
446
  publishes, read-only: its downloaded models (your own models take precedence,
@@ -426,7 +466,7 @@ gezel --home /path/to/another-home # a separate Gezel home
426
466
 
427
467
  `--home <dir>` (or an explicit `GEZEL_HOME`) implies `--standalone`. A home you
428
468
  name with `--home` is also kept separate from what the Gezel desktop app's
429
- machine install publishes: its shared gezels and projects, and the models it
469
+ machine install publishes: its shared crew and projects, and the models it
430
470
  downloaded. Set `GEZEL_DISABLE_MACHINE_SHARED=0` to include them anyway. Your
431
471
  default home, `~/.gezel`, still sees them.
432
472
 
@@ -344,7 +344,7 @@ ${opts?.withPage ? `
344
344
  Run \`gezel app demo . --out ../${id}-demo\`, then open its
345
345
  \`pages/dashboard/index.html\` to try the standalone demo. Sample records stay in memory; **Reset demo** restores them.
346
346
  Inside Gezel the same page uses real project data and the page-only
347
- \`page_add_record\` alias. Names in \`pages.tools\` are excluded from the gezel's
347
+ \`page_add_record\` alias. Names in \`pages.tools\` are excluded from the keeper's
348
348
  tool roster, so keep its \`add_record\` alias separate. Both call \`records-store\`.
349
349
  The browser preview is read-only; embedded and shared-site modes can run actions
350
350
  when the host permits them. A host error never switches the page to demo data.
@@ -360,6 +360,7 @@ Authoring references:
360
360
  - [Building Gezel apps](https://github.com/bendyline/gezel/blob/main/docs/building-gezel-apps.md)
361
361
  - [Page APIs](https://github.com/bendyline/gezel/blob/main/docs/output-pane-api.md)
362
362
  - [Page style guide](https://github.com/bendyline/gezel/blob/main/docs/handboek/technical/gezel-app-page-style-guide.md)
363
+ - [App UX guide](https://github.com/bendyline/gezel/blob/main/docs/handboek/technical/gezel-app-ux-guide.md)
363
364
  `
364
365
  ],
365
366
  [
@@ -369,7 +370,7 @@ Authoring references:
369
370
  kind: "project-type",
370
371
  id,
371
372
  name,
372
- description: `A focused ${name} workspace with one gezel and a records store.`,
373
+ description: `A focused ${name} workspace with one keeper and a records store.`,
373
374
  tags: [],
374
375
  maintainer: { name: "Your name" },
375
376
  license: "MIT",
@@ -742,6 +743,7 @@ async function runAppNew(id, opts = {}) {
742
743
  }
743
744
  console.log(`Scaffolded ${id} (${files.length} files) in ${target}`);
744
745
  console.log("Next:");
746
+ console.log(" 0. Read the guide first (or give it to your AI agent): gezel app guide");
745
747
  console.log(" 1. Edit items/ \u2014 start with the two about.md files and the version manifest.");
746
748
  console.log(` 2. gezel app validate ${id}`);
747
749
  console.log(` 3. gezel app pack ${id}`);
@@ -299,7 +299,7 @@ async function runAppRemove(client, appId, opts) {
299
299
  console.log(`Uninstalled ${appId} (${versions}${kept}).`);
300
300
  if (removed.appliedProjects.length > 0) {
301
301
  console.log(
302
- `${removed.appliedProjects.length} project(s) were outfitted by this app \u2014 they keep their copied gezels, scripts, and files, but the app's pages and updates are gone.`
302
+ `${removed.appliedProjects.length} project(s) were outfitted by this app \u2014 they keep their copied crew members, scripts, and files, but the app's pages and updates are gone.`
303
303
  );
304
304
  }
305
305
  }
@@ -358,7 +358,7 @@ function printPlan(plan) {
358
358
  function printApplied(applied, projectName) {
359
359
  const parts = [];
360
360
  if (applied.gezelsCreated.length > 0) {
361
- parts.push(`${applied.gezelsCreated.length} gezel(s)`);
361
+ parts.push(`${applied.gezelsCreated.length} crew member(s)`);
362
362
  }
363
363
  if (applied.scriptsInstalled.length > 0) {
364
364
  parts.push(`${applied.scriptsInstalled.length} script(s)`);
@@ -482,8 +482,15 @@ async function runAppStatus(client, folder, opts) {
482
482
  if (status.updateAvailable) {
483
483
  console.log(`Update available: gezel app apply ${status.provenance.id}`);
484
484
  }
485
- } else {
485
+ } else if (status.provenance.source === "installed-ai-apps") {
486
486
  console.log(`App: ${applied} \u2014 no longer installed (project keeps its copies)`);
487
+ } else {
488
+ console.log(`App: ${applied} \u2014 from the ${status.provenance.source} catalog`);
489
+ if (status.latestVersion) {
490
+ console.log(
491
+ `Update available: ${status.latestVersion}. Gezel applies it on its own unless it would replace something changed here; then update from the project in Gezel.`
492
+ );
493
+ }
487
494
  }
488
495
  if (status.seeds.length > 0) {
489
496
  const counts = /* @__PURE__ */ new Map();
@@ -0,0 +1,128 @@
1
+ #!/usr/bin/env node
2
+
3
+ // src/app-guide.ts
4
+ import { createHandboekEngine, siteDeviceInfo } from "@bendyline/gezel-service/handboek";
5
+
6
+ // src/connection.ts
7
+ import { createHash, randomUUID } from "crypto";
8
+ import { chmod, mkdir, readFile, realpath, rm, writeFile } from "fs/promises";
9
+ import { homedir } from "os";
10
+ import { basename, dirname, join, resolve } from "path";
11
+ import { fileURLToPath } from "url";
12
+ import {
13
+ evaluateApiCompat,
14
+ getLogLevel,
15
+ getLogOutput,
16
+ gezelNamesInUse,
17
+ pickUnusedGezelName,
18
+ projectLeadGezelId,
19
+ roleForMatching,
20
+ setLogLevel,
21
+ setLogOutput
22
+ } from "@bendyline/gezel";
23
+ import {
24
+ GezelSdkError,
25
+ authorizeLocal,
26
+ authorizeLocalOwner
27
+ } from "@bendyline/gezel-app-sdk";
28
+ import {
29
+ DaemonInAnotherNamespaceError,
30
+ GezelApiError,
31
+ GezelClient,
32
+ LiveDaemonUnhealthyError,
33
+ createTrustingFetch,
34
+ discoverOrSpawn,
35
+ electronNativeBinCandidates,
36
+ ensureProjectForFolder as ensureClientProjectForFolder,
37
+ forbiddenProjectFolderName,
38
+ isProcessAlive,
39
+ readRuntime,
40
+ readSystemServiceEndpoint,
41
+ resolveDaemonEntry,
42
+ stopOwnedDaemon,
43
+ systemServiceRuntimeIsStale,
44
+ systemSharedAssetsDir
45
+ } from "@bendyline/gezel-client/node";
46
+ import { gezelHome, gezelPaths, nativePayloadVerificationPath } from "@bendyline/gezel/paths";
47
+ var CliError = class extends Error {
48
+ constructor(message) {
49
+ super(message);
50
+ this.name = "CliError";
51
+ }
52
+ };
53
+
54
+ // src/handboek-links.ts
55
+ var PUBLISHED_HANDBOEK = "https://gezel.com/docs/";
56
+ var up = (depth) => "../".repeat(depth);
57
+ function rewriteSiteLinks(markdown, pageId, ids, byStem, hasAsset = () => true, base) {
58
+ const prefix = base ?? up(pageId.split("/").length);
59
+ return markdown.replace(/\]\(([^()\s]+)\)/g, (whole, rawTarget) => {
60
+ if (/^[a-z][a-z0-9+.-]*:/i.test(rawTarget) || rawTarget.startsWith("//") || rawTarget.startsWith("#")) {
61
+ return whole;
62
+ }
63
+ const [path, suffix = ""] = splitLinkSuffix(rawTarget);
64
+ const candidate = path.replace(/^(\.\.?\/)+/, "");
65
+ if (candidate.startsWith("assets/")) {
66
+ return hasAsset(candidate) ? `](${prefix}${candidate}${suffix})` : `](${PUBLISHED_HANDBOEK}${candidate}${suffix})`;
67
+ }
68
+ const article = candidate.replace(/\.md$/, "");
69
+ const target = ids.has(article) ? article : byStem.get(article.split("/").pop() ?? "");
70
+ if (!target) return whole;
71
+ return `](${prefix}${target}/${suffix})`;
72
+ });
73
+ }
74
+ function siteLinkIndex(entryIds) {
75
+ const byStem = /* @__PURE__ */ new Map();
76
+ for (const id of entryIds) {
77
+ const stem = id.split("/").pop();
78
+ if (stem && !byStem.has(stem)) byStem.set(stem, id);
79
+ }
80
+ return { ids: new Set(entryIds), byStem };
81
+ }
82
+ function splitLinkSuffix(raw) {
83
+ const idx = raw.search(/[?#]/);
84
+ return idx === -1 ? [raw, ""] : [raw.slice(0, idx), raw.slice(idx)];
85
+ }
86
+
87
+ // src/app-guide.ts
88
+ var APP_GUIDE_ARTICLE_ID = "build-a-gezel-app";
89
+ var NO_CATALOG = {
90
+ list: async () => [],
91
+ get: async () => null
92
+ };
93
+ async function renderAppGuide(opts = {}) {
94
+ const engine = createHandboekEngine({
95
+ catalog: NO_CATALOG,
96
+ device: siteDeviceInfo,
97
+ ...opts.contentDir ? { contentDir: opts.contentDir } : {}
98
+ });
99
+ const article = await engine.article(APP_GUIDE_ARTICLE_ID, {
100
+ mode: "agent",
101
+ inlineIncludes: true
102
+ });
103
+ if (!article) {
104
+ throw new CliError(
105
+ `this install has no "${APP_GUIDE_ARTICLE_ID}" Help article; read ${PUBLISHED_HANDBOEK}${APP_GUIDE_ARTICLE_ID}.md`
106
+ );
107
+ }
108
+ const { areas } = await engine.toc();
109
+ const { ids, byStem } = siteLinkIndex(areas.flatMap((a) => a.entries.map((e) => e.id)));
110
+ const markdown = rewriteSiteLinks(
111
+ article.markdown,
112
+ article.id,
113
+ ids,
114
+ byStem,
115
+ () => true,
116
+ PUBLISHED_HANDBOEK
117
+ );
118
+ return `${markdown.trimEnd()}
119
+ `;
120
+ }
121
+ async function runAppGuide() {
122
+ process.stdout.write(await renderAppGuide());
123
+ }
124
+ export {
125
+ APP_GUIDE_ARTICLE_ID,
126
+ renderAppGuide,
127
+ runAppGuide
128
+ };