@bendyline/gezel-cli 1.2.14 → 1.3.1

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
 
@@ -65,31 +65,35 @@ Run `gezel --help`, or `--help` on any command, for every option.
65
65
  | Command | What it does |
66
66
  |---|---|
67
67
  | `gezel` | Open the interactive terminal app for this folder's project |
68
- | `gezel run [prompt…]` | One prompt, one reply, using this project's crew lead unless you pass `--gezel <id>`. A sole `-` reads the prompt from stdin |
68
+ | `gezel run [prompt…]` | One prompt, one reply, using this project's crew lead unless you pass `--gezel <id>`. A sole `-` reads the prompt from stdin; with a prompt, piped or redirected text is sent after it |
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); `show` and `output-limit` take a crew member's id or name |
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` marks the one chats use and the ones another Gezel on this computer shares; `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, and downloads nothing when a shared copy is already here; `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
 
@@ -135,6 +140,18 @@ stderr. Empty input exits with status 1 before anything starts. Without a sole
135
140
  usage. Until a model is set up, `run` downloads nothing: it names the setup
136
141
  commands and exits.
137
142
 
143
+ With a prompt in its arguments, `run` also sends text piped or redirected to
144
+ it, after the prompt and a blank line:
145
+
146
+ ```bash
147
+ gezel run "Summarize these notes for the board" < notes.txt
148
+ git diff | gezel run "Write a commit message for this change"
149
+ ```
150
+
151
+ A terminal is never read, and a pipe that sends nothing within a moment is
152
+ left unread so a script that keeps stdin open never waits on it. For a slow
153
+ producer, put the whole prompt in the input and use `gezel run -`.
154
+
138
155
  ## Provider keys
139
156
 
140
157
  Provider keys go into the same credential store the desktop app uses, read from
@@ -180,7 +197,7 @@ Three settings help with long unattended batches:
180
197
 
181
198
  ## Craftbooks from the command line
182
199
 
183
- A craftbook is a recipe for a piece of work that gezels carry out as a task.
200
+ A craftbook is a recipe for a piece of work that Gezel carries out as a task.
184
201
  `gezel craftbook list` shows the ones you can start in the current folder's
185
202
  project, and `gezel craftbook list deck` narrows the list by command, title,
186
203
  and tags.
@@ -198,10 +215,11 @@ name (its id, unless it declares one) exactly, and built-in commands always
198
215
  win. A mistyped name reports an unknown command without creating a project.
199
216
 
200
217
  ```bash
201
- gezel do summarize-long "Summarize notes.txt for the board"
218
+ gezel do summarize-long "Summarize notes.txt for the board" --out ./board-summary
202
219
  gezel summarize-long "Summarize notes.txt for the board"
203
220
  gezel do powerpoint-deck "A deck about Delft" audience=investors --wait --json
204
221
  gezel task wait my-project/12 --timeout 7200 --json
222
+ gezel task wait my-project/12 --out ./board-summary
205
223
  gezel task resume my-project/12 --json
206
224
  gezel task notes my-project/12 --warnings --json
207
225
  ```
@@ -214,6 +232,35 @@ timeout leaves the task running. When a task is blocked, `--wait` prints why
214
232
  stderr; `--json` writes the result to stdout. `resume` retries a paused task
215
233
  with its saved recipe. Answer pending questions in Gezel before waiting again.
216
234
 
235
+ When a task completes, waiting prints where its result is:
236
+
237
+ ```text
238
+ work/1: complete
239
+ Result: /Users/you/.gezel/projects/work/artifacts/tasks/1/summary.md
240
+ Also made: scope.md, verdict.md
241
+ Folder: /Users/you/.gezel/projects/work/artifacts/tasks/1
242
+ ```
243
+
244
+ `--json` carries the same under `output`: each file's `relativePath`, its
245
+ absolute `path` on the computer running Gezel, whether this command can open it
246
+ (`readable`), and which one is the `deliverable`. When Gezel runs somewhere this
247
+ command cannot read (a remote service, a container, or a machine-wide service),
248
+ the paths are not yours to open; copy the files instead.
249
+
250
+ A folder's project starts read-only. Most craftbooks keep what they make in
251
+ the task's own folder, which `--out <dir>` copies out when the task finishes;
252
+ `gezel task wait <ref> --out <dir>` copies a finished task's.
253
+ Some save into the folder itself, such as a deck or a web page;
254
+ `gezel craftbook show <craftbook>` says which. At a terminal `gezel do` asks
255
+ before it starts one of those. In a script, add `--allow-edits`, or run
256
+ `gezel project edits on` once in the folder. A task that stops because the
257
+ folder is read-only prints that command and the `gezel task resume` that
258
+ continues it.
259
+
260
+ Some craftbooks need a file or a branch before the request.
261
+ `gezel craftbook show <craftbook>` prints the start line with those in place,
262
+ for example `gezel do meeting-notes-to-actions <source> "your request"`.
263
+
217
264
  ### Repository workflows
218
265
 
219
266
  For scripted orchestration around several craftbooks, add a module under
@@ -336,7 +383,7 @@ download only when you choose on-device models. Straight away you can use:
336
383
  first use, and one-shot prompts (`gezel run "…"`) once a model is set up.
337
384
  - Cloud providers: OpenAI, Anthropic, GitHub Copilot, and any OpenAI-compatible
338
385
  endpoint.
339
- - Your gezels, projects, and tasks (`gezel agent`, `gezel project`,
386
+ - Your crew, projects, and tasks (`gezel agent`, `gezel project`,
340
387
  `gezel task`).
341
388
  - `gezel skills convert` and `gezel handboek export`, which need no running
342
389
  service at all.
@@ -405,7 +452,7 @@ machine-wide service, that service owns 6228. A current machine-wide service
405
452
  only runs models: the CLI never sends it projects, keys, or tools, and your own
406
453
  service uses it for model downloads and inference. While you upgrade from an
407
454
  older desktop release, an older machine-wide service that still holds your
408
- gezels and projects is used instead; `--standalone` skips it.
455
+ crew and projects is used instead; `--standalone` skips it.
409
456
 
410
457
  Your own service may reuse two things the desktop app's machine install
411
458
  publishes, read-only: its downloaded models (your own models take precedence,
@@ -431,7 +478,7 @@ gezel --home /path/to/another-home # a separate Gezel home
431
478
 
432
479
  `--home <dir>` (or an explicit `GEZEL_HOME`) implies `--standalone`. A home you
433
480
  name with `--home` is also kept separate from what the Gezel desktop app's
434
- machine install publishes: its shared gezels and projects, and the models it
481
+ machine install publishes: its shared crew and projects, and the models it
435
482
  downloaded. Set `GEZEL_DISABLE_MACHINE_SHARED=0` to include them anyway. Your
436
483
  default home, `~/.gezel`, still sees them.
437
484
 
@@ -336,7 +336,7 @@ The loop:
336
336
  1. Edit the files under \`items/\` (schemas: \`gezel app schemas --out schemas\`).
337
337
  2. \`gezel app validate .\`
338
338
  3. \`gezel app pack .\`
339
- 4. \`gezel app add ${id}-1.0.0.gezapp --yes\` then \`gezel app apply ${id}\` in a project folder.
339
+ 4. \`gezel app add ${id}-1.0.0.gezapp --yes\` then \`gezel app apply ${id} --yes\` in a project folder.
340
340
 
341
341
  The keeper uses \`add_record\` to update the seeded \`data.json\` through
342
342
  \`records-store\`. Read failures are errors; they never reset existing data.
@@ -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.
@@ -370,7 +370,7 @@ Authoring references:
370
370
  kind: "project-type",
371
371
  id,
372
372
  name,
373
- 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.`,
374
374
  tags: [],
375
375
  maintainer: { name: "Your name" },
376
376
  license: "MIT",
@@ -747,7 +747,7 @@ async function runAppNew(id, opts = {}) {
747
747
  console.log(" 1. Edit items/ \u2014 start with the two about.md files and the version manifest.");
748
748
  console.log(` 2. gezel app validate ${id}`);
749
749
  console.log(` 3. gezel app pack ${id}`);
750
- console.log(` 4. gezel app add ${id}-1.0.0.gezapp --yes && gezel app apply ${id}`);
750
+ console.log(` 4. gezel app add ${id}-1.0.0.gezapp --yes && gezel app apply ${id} --yes`);
751
751
  }
752
752
  async function runAppSchemas(opts = {}) {
753
753
  const files = renderGezappAuthoringSchemaFiles();
@@ -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();
package/dist/app-guide.js CHANGED
@@ -102,7 +102,7 @@ async function renderAppGuide(opts = {}) {
102
102
  });
103
103
  if (!article) {
104
104
  throw new CliError(
105
- `this install has no "${APP_GUIDE_ARTICLE_ID}" Handboek article; read ${PUBLISHED_HANDBOEK}${APP_GUIDE_ARTICLE_ID}.md`
105
+ `this install has no "${APP_GUIDE_ARTICLE_ID}" Help article; read ${PUBLISHED_HANDBOEK}${APP_GUIDE_ARTICLE_ID}.md`
106
106
  );
107
107
  }
108
108
  const { areas } = await engine.toc();