@bendyline/gezel-cli 1.2.5 → 1.2.7

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,113 +1,120 @@
1
1
  # @bendyline/gezel-cli
2
2
 
3
- The `gezel` command line — assemble a team of AI companions (*gezellen*) and put
3
+ The `gezel` command line: assemble a team of AI companions (*gezels*) and put
4
4
  them to work from your terminal.
5
5
 
6
- Gezel is local-first. Everything you create lives on your disk under `~/.gezel/`
7
- as ordinary files you can `cat` and `grep`, and talks to whichever LLM provider
8
- you point it at. No cloud service of ours stands between you and the model.
6
+ ## Quick start
7
+
8
+ Install the CLI globally. It needs Node.js 24 or newer:
9
9
 
10
10
  ```bash
11
- npm install @bendyline/gezel-cli
12
- npx gezel
11
+ npm install -g @bendyline/gezel-cli
13
12
  ```
14
13
 
15
- On a clean machine, the TUI stays in first-time setup until you decide what to
16
- install. It offers the verified Gezel native toolkit first, downloaded from
17
- the [Gezel GitHub Releases](https://github.com/bendyline/gezel/releases/), then
18
- device-ranked model choices:
19
-
20
- 1. The best chat model for this device, by itself. This is the recommended
21
- default and keeps the first download small.
22
- 2. An optional complete workshop set that adds every recommended image,
23
- speech, reading, and video helper that fits this device.
24
- 3. Other compatible chat-only models, ordered for this device.
25
-
26
- Downloads show live progress and activate inside the running daemon, so setup
27
- continues directly into the TUI without a restart. Setup only offers helpers
28
- whose runtime is present: the lean npm install omits the in-process Kokoro TTS
29
- stack, while desktop and relocatable distributions include its reviewed
30
- runtime.
31
-
32
- If the per-user or machine-shared store already has the configured model, the
33
- TUI uses it without downloading another copy. A stale recommendation never
34
- counts merely because some other shared model exists: setup asks you to use an
35
- available model or download the recommendation instead.
36
-
37
- ## Which Gezel service the CLI uses
38
-
39
- With no connection flags, the CLI follows this order:
40
-
41
- 1. During rolling-upgrade compatibility only, use an older `legacy-full`
42
- machine service when one is present. A modern machine service on port
43
- `6228` is an engine broker, not a product API, so the CLI never sends it
44
- projects, credentials, tools, or terminal requests.
45
- 2. Discover the logged-in user's product daemon through the same pinned
46
- runtime discovery used by the Gezel app SDK. Its actual dynamic port and
47
- pinned TLS certificate come from `~/.gezel/runtime`; management commands
48
- may start that user-role daemon when it is absent, and say so on stderr
49
- because it keeps running afterwards (`gezel stop --daemon` ends it). A
50
- daemon the CLI starts keeps its own log in
51
- `~/.gezel/logs/service-YYYY-MM-DD.log` (rolled at 10 MB, kept 7 days).
52
- Read-only diagnostics such as `gezel native status` and `native list`
53
- never leave one behind: with no daemon running they answer from a
54
- service that stops with the command. The interactive TUI
55
- retains ownership when it starts a daemon itself, so exiting the TUI runs
56
- the daemon's complete shutdown path and cleans up its local engine children.
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.
63
-
64
- `gezel run` has one deliberate lifecycle exception: if no user daemon exists,
65
- it starts a user-role service in-process for that one invocation and stops it
66
- afterward. It does not take that fallback after a denied grant or when a live
67
- daemon is unhealthy.
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.
14
+ Then choose where the AI runs.
15
+
16
+ **On this computer.** See which chat models fit your machine, download one,
17
+ and make chats use it:
76
18
 
77
- The per-user daemon owns gezels, projects, settings, credentials, and
78
- conversations with ordinary user filesystem permissions. It discovers the
79
- machine engine broker independently for centralized model downloads and local
80
- inference. The CLI does **not** open the machine service's private data
81
- directory directly.
19
+ ```bash
20
+ gezel model list --available
21
+ gezel model pull <id>
22
+ gezel model use <id>
23
+ ```
82
24
 
83
- It may reuse two deliberately public asset surfaces:
25
+ **With a cloud provider.** Save your API key without putting it on the command
26
+ line, then pick one of that provider's models with `/model` inside `gezel`:
84
27
 
85
- - Immutable machine models under the installer-owned `assets/models/` tree.
86
- User-owned models in `~/.gezel/engines/` take precedence; the CLI re-hashes
87
- a machine model on first adoption, caches file identity/size/mtime locally,
88
- and downloads replacements only into its user-owned home.
89
- - Electron's `native-bin/` payload when its native release exactly matches the
90
- CLI pin, every executable/loadable file matches the per-file hashes embedded
91
- in the CLI, and platform signing checks pass. Any mismatch falls back to the
92
- CLI's independently downloaded native cache.
28
+ ```bash
29
+ gezel secret set openaiApiKey --env OPENAI_API_KEY
30
+ gezel secret set anthropicApiKey --stdin < anthropic-key.txt
31
+ ```
93
32
 
94
- The global overrides are:
33
+ Now start working:
95
34
 
96
35
  ```bash
97
- gezel --connect https://host:6228 # explicit service; approval on first use
98
- gezel --connect https://host:6228 --token "$TOKEN"
99
- gezel --standalone # skip legacy-full compatibility
100
- gezel --home /path/to/another-home # standalone with an alternate home
36
+ gezel # the interactive terminal app
37
+ gezel run "Summarize this project" # one prompt, one reply
101
38
  ```
102
39
 
103
- `--home` (and an explicitly set `GEZEL_HOME`) implies standalone operation.
104
- An explicit `--port 6228` remains available when you intentionally want a
105
- CLI-owned daemon on the canonical port.
40
+ The first time you run `gezel` on a new machine, it walks you through the same
41
+ choices: it offers the verified Gezel native toolkit, then the best chat model
42
+ for this device (recommended, and the smallest first download), an optional
43
+ complete set of image, speech, reading, and video helpers that fit, or other
44
+ compatible chat models. Downloads show live progress and take effect without a
45
+ restart. A model you already have, in your own store or one the desktop app
46
+ shares on this machine, is used without downloading another copy.
47
+
48
+ Gezel is local-first. Everything you create lives on your disk under
49
+ `~/.gezel/` as ordinary files you can `cat` and `grep`, and talks to whichever
50
+ model provider you point it at. No cloud service of ours stands between you and
51
+ the model. The npm package is all you need; the desktop app is optional.
52
+
53
+ ## Commands
54
+
55
+ Run `gezel --help`, or `--help` on any command, for every option.
56
+
57
+ | Command | What it does |
58
+ |---|---|
59
+ | `gezel` | Open the interactive terminal app for this folder's project |
60
+ | `gezel run [prompt…]` | One prompt, one reply, using this project's voorman unless you pass `--gezel <id>`. A sole `-` reads the prompt from stdin |
61
+ | `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 |
62
+ | `gezel <craftbook> …` | Shorthand for `gezel do <craftbook> …`, matched exactly on the craftbook's command name; built-in commands always win |
63
+ | `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 |
64
+ | `gezel workflow <name-or-file> [args…]` | Run a repository workflow from `.gezel/workflows/<name>.mjs` or a module path |
65
+ | `gezel task list\|show\|create` | Tasks across every project |
66
+ | `gezel task wait\|resume\|pause <ref>` | Follow a task to the end, retry a paused task and follow it, or pause one task |
67
+ | `gezel task notes <ref>` | A task's notes, including pause reasons and failed checks (`--warnings` adds runtime warnings) |
68
+ | `gezel agent list\|create\|show\|output-limit` | Manage your gezels (the command name is historical) |
69
+ | `gezel project list\|create\|install\|indexing` | Manage projects, their npm packages, and background indexing (`gezel env` is the same command) |
70
+ | `gezel skills list\|import\|convert` | Find SKILL.md skills and turn them into craftbooks |
71
+ | `gezel app …` | Build, install, apply, and serve AI Apps (`.gezapp`): `new`, `validate`, `pack`, `add`, `update`, `list`, `show`, `apply`, `status`, `serve`, `enable`, `disable`, `remove`, `schemas` |
72
+ | `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` |
73
+ | `gezel model context\|concurrency` | A local model's context window, and how many requests a local engine serves at once |
74
+ | `gezel native install\|list\|status` | The native engines that run models on this computer |
75
+ | `gezel image status\|models\|pull\|rm` | Image-generation models |
76
+ | `gezel create-image\|create-video\|create-audio` | Generate an image, a video, or spoken audio |
77
+ | `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`) |
78
+ | `gezel secret list\|set\|remove` | Provider keys, stored write-only |
79
+ | `gezel security external-services [on\|off]` | Whether gezels may use web search and other outside services |
80
+ | `gezel mode [mode]` | Show or set how active the AI may be: `read-only`, `reactive`, `reactive+tasks`, or `full-play` |
81
+ | `gezel start` / `status` / `stop` | Start, check, or stop your Gezel service (see [Starting and stopping](#starting-and-stopping)) |
82
+ | `gezel doctor` | Check the installation |
83
+ | `gezel cleanup` | Show or reclaim the space Gezel uses on this device (`--redownloadable`, `--models`, `--dry-run`, …) |
84
+ | `gezel backup <file>` / `restore <file>` | Write your gezels, projects, and documents to a backup file, or bring them back (`restore --list` looks first) |
85
+ | `gezel handboek export --out <dir>` | Render the Handboek, Gezel's built-in documentation, as a static website |
86
+
87
+ ## Starting and stopping
88
+
89
+ - `gezel start` makes sure your Gezel service is running. `--port <n>` pins a
90
+ port, and `--foreground` keeps it attached to the terminal (Ctrl+C stops it).
91
+ - `gezel start --web` also serves the browser interface on this computer and
92
+ prints a browser URL carrying a sign-in token that is valid until the service
93
+ restarts. `--open` opens it for you. When a running service was started
94
+ without the web interface, `gezel start --web --restart` replaces it.
95
+ - `gezel status` reports whether the service is up and where; it exits 1 when
96
+ it is not running or not healthy.
97
+ - `gezel stop` cancels any AI work and shuts down your per-user Gezel service.
98
+ - `gezel stop --keep-running` is the emergency brake: cancel AI work, unload
99
+ engines, switch to Reactive, and leave the service running. (`--daemon` is
100
+ still accepted as an alias of the plain stop.)
101
+
102
+ If the desktop app's machine-wide service is in use, `gezel stop` does the
103
+ emergency brake on it and says the service is managed by the operating system.
104
+
105
+ Inside the interactive app, `/mode` switches the same four activity levels and
106
+ `/model` lists every installed model, with **Download a new model** to fetch
107
+ another; the download is selected for the active gezel and starts a fresh chat.
108
+ `/continue` processes due schedules and picks up the current project's active
109
+ tasks, and `/nightshift start|stop|list` manages Night Shift. `/allow edits` and
110
+ `/disallow edits` let Gezel's own tools and background work edit the current
111
+ project, or make it read-only for them; `codexedits` and `claudeedits` do the
112
+ same for gezels that run on the Codex or Claude command-line tools.
106
113
 
107
114
  ## One-shot prompts and pipelines
108
115
 
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:
116
+ `gezel run -` reads a UTF-8 prompt from a pipe or redirected file. It reads
117
+ until EOF and keeps line breaks and indentation:
111
118
 
112
119
  ```bash
113
120
  printf 'Summarize these notes:\nThe launch is Friday.\n' | gezel run -
@@ -115,113 +122,124 @@ gezel run - < prompt.txt
115
122
  ```
116
123
 
117
124
  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.
125
+ stderr. Empty input exits with status 1 before anything starts. Without a sole
126
+ `-`, `gezel run "your prompt"` uses its arguments, and bare `gezel run` shows
127
+ usage. Until a model is set up, `run` downloads nothing: it names the setup
128
+ commands and exits.
121
129
 
122
- ## Provider credentials
130
+ ## Provider keys
123
131
 
124
- Manage provider keys through the service credential store, using stdin or an
125
- existing environment variable so the value does not appear in command arguments:
132
+ Provider keys go into the same credential store the desktop app uses, read from
133
+ an environment variable or from stdin so the value never appears in your
134
+ command arguments or shell history:
126
135
 
127
136
  ```bash
128
137
  gezel secret list
129
- gezel secret set braveSearchApiKey --env BRAVE_SEARCH_API_KEY --use-for-search
130
138
  gezel secret set openaiApiKey --env OPENAI_API_KEY
131
139
  gezel secret set anthropicApiKey --env ANTHROPIC_API_KEY
140
+ gezel secret set braveSearchApiKey --env BRAVE_SEARCH_API_KEY --use-for-search
132
141
  gezel secret remove openaiApiKey
133
142
  ```
134
143
 
135
- `--use-for-search` (with `braveSearchApiKey`) also selects Brave as the
136
- search provider while preserving its other settings. Without it, setting a
137
- credential leaves provider selection unchanged. `secret list` gives the supported
138
- names and whether each is configured; credentials are write-only and never
139
- printed. All three commands support `--json`, and honor `--home` / `--connect`.
140
- This covers the built-in provider credentials, including webhooks; it is not an
141
- arbitrary environment-variable store. Storage uses the same native keyring or
142
- encrypted fallback as the application.
144
+ `--stdin` reads the value from a pipe or redirected file instead. The supported
145
+ names are `openaiApiKey`, `openaiOrganization`, `anthropicApiKey`,
146
+ `googleAiApiKey`, `githubToken`, `braveSearchApiKey`, `tavilyApiKey`,
147
+ `webhookBearerToken`, and `webhookBasicAuth`; `gezel secret list` shows them and
148
+ whether each is set, but never prints a value. All three commands accept
149
+ `--json`. Storage uses your system keyring, or an encrypted file where there is
150
+ none.
151
+
152
+ `--use-for-search` (with `braveSearchApiKey`) also makes Brave the web search
153
+ provider. Web search also needs outside services to be allowed:
154
+ `gezel security external-services` shows that setting, and `on` or `off`
155
+ changes it. Saving a key never turns it on for you.
143
156
 
144
157
  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
-
148
- Search also requires the selected environment to allow external services.
149
- `gezel security external-services` shows that setting; append `on` or `off` to
150
- change it explicitly while preserving all other security capabilities. This
151
- permission covers model-initiated external services, including web search.
152
- Saving a credential does not silently enable it.
153
-
154
- `gezel model context <id> 65536` sets a local model's context window for its next
155
- launch; omit the token count to inspect it, or use `auto` to clear the override.
156
- Use `--provider llama-cpp|mlx|ds4` to select an engine (defaults to the platform's
157
- local engine). This can bound memory use for unattended batch tasks.
158
-
159
- `gezel model concurrency 1` limits the local engine to one inference slot and
160
- reduces its context-cache reservation. This is useful for serial batches with
161
- large models. It preserves other providers' limits; `--provider` selects an
162
- engine, and `auto` restores automatic sizing. Omit the value to inspect it.
163
-
164
- `gezel env indexing off` disables optional background workspace indexing in
165
- the current directory's project (or `--project` target). Artifact-driven batch
166
- workflows over large generated datasets can use this to avoid unnecessary
167
- indexing. `on` restores it; omitting the value reports its current state.
168
- Both settings commands support `--json` and the ordinary connection/home flags.
169
-
170
- ## Batch craftbooks and repository workflows
171
-
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`.
158
+ one of that provider's models. A key saved in the desktop app or the CLI is
159
+ available to both.
160
+
161
+ Three settings help with long unattended batches:
162
+
163
+ - `gezel model context <id> 65536` sets a local model's context window for its
164
+ next launch; omit the number to see it, or use `auto` to clear it.
165
+ - `gezel model concurrency 1` limits the local engine to one request at a time,
166
+ which also reserves less memory; `auto` restores automatic sizing.
167
+ - `gezel env indexing off` pauses optional background indexing in this folder's
168
+ project (or `--project` target); `on` resumes it.
169
+
170
+ `--provider llama-cpp|mlx|ds4` picks the engine for the model commands
171
+ (default: this platform's on-device engine), and all three accept `--json`.
172
+
173
+ ## Craftbooks from the command line
174
+
175
+ A craftbook is a recipe for a piece of work that gezels carry out as a task.
176
+ `gezel craftbook list` shows the ones you can start in the current folder's
177
+ project, and `gezel craftbook list deck` narrows the list by command, title,
178
+ and tags.
179
+
180
+ `gezel do` takes the craftbook, then its values. A bare value fills the next
181
+ required parameter, in the order the craftbook lists them. `key=value` and
182
+ repeatable `--param key=value` set any parameter, including ones the app's
183
+ launch forms hide. Every other word is your request: it becomes the task
184
+ description and, when the craftbook takes one, its main content. Quoting is
185
+ optional.
186
+
187
+ Any craftbook also runs by name, so `gezel summarize-long "…"` is
188
+ `gezel do summarize-long "…"`. The name must match the craftbook's command
189
+ name (its id, unless it declares one) exactly, and built-in commands always
190
+ win. A mistyped name reports an unknown command without creating a project.
186
191
 
187
192
  ```bash
188
193
  gezel do summarize-long "Summarize notes.txt for the board"
189
194
  gezel summarize-long "Summarize notes.txt for the board"
190
- gezel do story-batch c23n limit=3 --wait --json
195
+ gezel do powerpoint-deck "A deck about Delft" audience=investors --wait --json
191
196
  gezel task wait my-project/12 --timeout 7200 --json
192
197
  gezel task resume my-project/12 --json
193
198
  gezel task notes my-project/12 --warnings --json
194
199
  ```
195
200
 
196
- Only explicit values are sent; the service resolves defaults such as
197
- `{{task.dir}}` after allocating the task. Waiting exits with 0 for completion,
198
- 1 for cancellation, 2 for a paused task or pending user question, and 3 for a
199
- timeout. A timeout leaves the daemon task running. Progress goes to stderr;
200
- `--json` emits the result on stdout. `resume` retries a paused task using its
201
- saved recipe. Answer pending questions in Gezel before waiting again.
201
+ Only the values you give are sent; the service fills in the defaults after it
202
+ creates the task. Waiting exits with 0 when the task completes, 1 when it is
203
+ canceled, 2 when it is paused or waiting for your answer, and 3 on timeout. A
204
+ timeout leaves the task running. When a task is blocked, `--wait` prints why
205
+ (its latest note) and points to `gezel task notes <ref>`. Progress goes to
206
+ stderr; `--json` writes the result to stdout. `resume` retries a paused task
207
+ with its saved recipe. Answer pending questions in Gezel before waiting again.
208
+
209
+ ### Repository workflows
202
210
 
203
- For deterministic orchestration around several craftbooks, create
204
- `.gezel/workflows/storyify.mjs`:
211
+ For scripted orchestration around several craftbooks, add a module under
212
+ `.gezel/workflows/`, for example `.gezel/workflows/quarterly-reports.mjs`:
205
213
 
206
214
  ```js
207
- export async function run({ client, projectId, workspace, args, log, runCraftbook }) {
208
- const [region] = args;
209
- log(`Working on ${region} in ${workspace}`);
210
- return runCraftbook('story-batch', { region });
215
+ export async function run({ args, log, runCraftbook }) {
216
+ const results = [];
217
+ for (const region of args) {
218
+ log(`Writing the ${region} report`);
219
+ results.push(await runCraftbook('region-report', { region }));
220
+ }
221
+ return results;
211
222
  }
212
223
  ```
213
224
 
214
- Run it with `gezel workflow storyify c23n --json`. The module receives the
215
- public `GezelClient`, the directory's project id, its absolute workspace,
216
- arguments, a stderr logger, `complete(request)` (below), and
217
- `runCraftbook(id, params, options)`. That helper
218
- starts a **project** craftbook and waits; options include `timeoutMs`, a saved
219
- `taskRef` to follow, `parentTaskRef` to link the child to its batch, and
220
- `onCreated(task)` to checkpoint the new reference.
221
- When a step needs model judgment on input the driver already holds — extract
222
- the facts in this page, check this paragraph against these quotations — use
223
- `complete(request)` instead of a craftbook. It makes one bounded call on the
224
- project's engine queue and returns `{ content, json?, jsonError?, elapsedMs }`:
225
+ Run it with `gezel workflow quarterly-reports north south --json`, or give a
226
+ module path: `gezel workflow ./pipeline/quarterly-reports.mjs north`. The
227
+ module receives the public `GezelClient` (`client`), the folder's project id
228
+ (`projectId`), its absolute `workspace`, your `args`, a stderr `log`, and:
229
+
230
+ - `runCraftbook(id, params, options)` starts a **project** craftbook (one under
231
+ `.gezel/craftbooks/`) and waits for it. Options include `timeoutMs`, a saved
232
+ `taskRef` to follow, `parentTaskRef` to link the child to its batch, and
233
+ `onCreated(task)` to checkpoint the new reference. It checks the craftbook's
234
+ declared needs first (see below).
235
+ - `complete(request)` makes one bounded model call on the project's engine
236
+ queue, for judgment on input the module already holds. No tools, session, or
237
+ transcript are involved; the module validates the answer and saves what it
238
+ keeps.
239
+ - `validateCraftbook(document)` checks a generated craftbook against the same
240
+ schema and step rules as the service before you install it.
241
+ - `ensureSetup({ services, models })` asks for setup the module decides on at
242
+ run time, the same way `gezel do` does.
225
243
 
226
244
  ```js
227
245
  const { json } = await complete({
@@ -232,31 +250,28 @@ const { json } = await complete({
232
250
  thinking: false, // skip a local model's reasoning phase
233
251
  maxTokens: 4000,
234
252
  timeoutMs: 300_000,
235
- label: 'check · Taylorville ¶3',
253
+ label: 'fact-check, paragraph 3',
236
254
  });
237
255
  ```
238
256
 
239
- No tools, session or transcript are involved, so there is nothing to read
240
- back and nothing to save: the driver validates the answer and persists what it
241
- keeps. Use a craftbook when the work genuinely needs tools or a person.
242
-
243
- For drivers that generate craftbook documents, `validateCraftbook(document)`
244
- checks the same schema and step contracts as the daemon and returns the runtime
245
- craftbook. Call it before installing files or freezing a batch checkpoint;
246
- invalid documents throw actionable authoring errors without creating a task.
247
- Returning an object with `exitCode` sets the shell exit status. Module paths
248
- also work: `gezel workflow ./pipeline/storyify.mjs c23n`.
249
-
250
- To expose that driver as one command, add
251
- `"cliWorkflow": { "module": ".gezel/workflows/storyify.mjs" }` to a project
252
- craftbook and declare its inputs in `paramSchema`, listing the ones a bare
253
- value should fill under `required`. Then run
254
- `gezel do my-batch c23n limit=200 --json`. Its module receives `craftbook` and
255
- validated explicit `params` in addition to the context above. A workflow
256
- craftbook takes no request text. The driver owns
257
- parent creation, defaults, checkpoints, bounded child concurrency, and the
258
- final result. Modules must resolve inside the project workspace. Only project
259
- craftbooks can use this entry point; `--strict-sandbox` rejects it.
257
+ `complete` returns `{ content, json?, jsonError?, elapsedMs }`. Returning an
258
+ object with `exitCode` from `run` sets the shell exit status.
259
+
260
+ To expose a workflow as a craftbook command, add
261
+ `"cliWorkflow": { "module": ".gezel/workflows/quarterly-reports.mjs" }` to a
262
+ project craftbook and declare its inputs in `paramSchema`, listing the ones a
263
+ bare value should fill under `required`. Then `gezel do quarterly-reports north
264
+ --json` runs it, and the module also receives `craftbook` and the validated
265
+ `params`. A workflow craftbook takes no request text, and the module owns
266
+ creating the parent task, defaults, checkpoints, and how many children run at
267
+ once. Modules must live inside the project workspace; `--strict-sandbox`
268
+ refuses them.
269
+
270
+ Workflows run in the foreground even without `--wait`, so keep the terminal
271
+ open. A timeout applies to each child wait. If the CLI exits, tasks already
272
+ created keep running, but the rest of the workflow needs to be run again;
273
+ `gezel task wait` follows a parent and its children but does not restart a
274
+ workflow.
260
275
 
261
276
  ### Declaring what a craftbook needs
262
277
 
@@ -266,24 +281,22 @@ cannot run without. `gezel do` checks them before anything starts:
266
281
  ```json
267
282
  "services": [{ "kind": "web-search", "reason": "research checks every fact" }],
268
283
  "models": [
269
- { "id": "qwen3.8-27b-q4", "reason": "writes the stories" },
284
+ { "id": "qwen3.8-27b-q4", "reason": "writes the report" },
270
285
  { "id": "{{checkerModel}}", "provider": "llama-cpp", "reason": "checks every sentence" }
271
286
  ]
272
287
  ```
273
288
 
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
289
+ `web-search` means a keyed search provider (Brave); Wikipedia does not count.
290
+ It implies `external-services`, which a craftbook that only fetches pages can
276
291
  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.
292
+ reference, filled from the run's value or its default; one that resolves to
293
+ nothing is skipped. `provider` defaults to this computer's on-device engine.
280
294
 
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:
295
+ At a terminal, each missing piece is one question: turn on outside services
296
+ (naming the security level that moves to), paste a Brave Search API key
297
+ (hidden, then proven with one test search), and download the models (after a
298
+ disk-space check, with the engine if it is missing). Any "no", or a run without
299
+ a terminal, stops before the run starts and prints the commands that fix it:
287
300
 
288
301
  ```text
289
302
  gezel security external-services on
@@ -291,46 +304,36 @@ gezel secret set braveSearchApiKey --env BRAVE_SEARCH_API_KEY --use-for-search
291
304
  gezel model pull qwen3.8-27b-q4 --provider llama-cpp
292
305
  ```
293
306
 
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
-
298
- These drivers run in the foreground even without `--wait`; keep the terminal
299
- open until completion. A timeout applies to each child wait. If the CLI exits,
300
- already-created daemon tasks survive, but further orchestration requires the
301
- workflow's resume command. `gezel task wait` observes a parent and its children;
302
- it does not restart a repository driver.
303
-
304
- Project recipes live in `.gezel/craftbooks/<id>/manifest.json` (identity) and
305
- `versions/<version>/craftbook.json` (the complete recipe, including embedded
306
- scripts). Legacy version manifests plus `scripts/*.ts` remain supported.
307
- Changing a recipe affects new tasks; running tasks retain their snapshots.
308
-
309
- CLI craftbook launches, including TUI `/do`, authorize the exact embedded
310
- script contents in that task snapshot. On Windows and other platforms without
311
- an enforceable OS network boundary, those scripts use best-effort network
312
- isolation. Declared capabilities and project/security policies still apply.
313
- Use `gezel do ... --strict-sandbox` to require the OS boundary instead. Edited
314
- scripts do not inherit the old source's trust, and a model session cannot
315
- grant trust. Workflow modules themselves run as ordinary local Node code,
316
- with the invoking user's permissions, like an npm script.
317
-
318
- ## What you get with no further setup
319
-
320
- The CLI does not bundle model weights or native inference engines; those are
321
- downloaded only on demand when you opt into on-device models. Straight away
322
- you can use:
323
-
324
- - The interactive TUI (`gezel`), which walks you through choosing a model on
307
+ ### Project craftbooks and their scripts
308
+
309
+ Project craftbooks live in `.gezel/craftbooks/<id>/manifest.json` (identity)
310
+ and `versions/<version>/craftbook.json` (the complete recipe, including its
311
+ scripts). Changing a recipe affects new tasks; running tasks keep their copy.
312
+
313
+ A launch from the CLI, including `/do` in the interactive app, trusts the exact
314
+ script contents in that task's copy of the recipe. Edited scripts do not
315
+ inherit that trust, and a model can never grant it. On platforms without an
316
+ enforceable operating-system network boundary, such as Windows, those scripts
317
+ run with best-effort network isolation; `gezel do … --strict-sandbox` requires
318
+ the operating-system boundary instead. Declared capabilities and project and
319
+ security policies still apply. Workflow modules themselves run as ordinary
320
+ local Node code with your permissions, like an npm script.
321
+
322
+ ## What works with no further setup
323
+
324
+ The CLI does not bundle model weights or native inference engines; those
325
+ download only when you choose on-device models. Straight away you can use:
326
+
327
+ - The interactive app (`gezel`), which walks you through choosing a model on
325
328
  first use, and one-shot prompts (`gezel run "…"`) once a model is set up.
326
- Until then `run` downloads nothing: it names the setup commands and exits.
327
- - Cloud providers — OpenAI, Anthropic, GitHub Copilot, and any
328
- OpenAI-compatible endpoint
329
- - Gezel and project management (`gezel agent`, `gezel project`, `gezel task`)
330
- - Skills and handbook export (`gezel skills convert`, `gezel handboek export`) —
331
- these need no running daemon at all
332
- - Knowledge catalogs you already have: `gezel knowledge validate`, `inspect`
333
- and full-text `search` work offline, with no daemon
329
+ - Cloud providers: OpenAI, Anthropic, GitHub Copilot, and any OpenAI-compatible
330
+ endpoint.
331
+ - Your gezels, projects, and tasks (`gezel agent`, `gezel project`,
332
+ `gezel task`).
333
+ - `gezel skills convert` and `gezel handboek export`, which need no running
334
+ service at all.
335
+ - Knowledge catalogs you already have: `gezel knowledge validate`, `inspect`,
336
+ and full-text `search` work offline, with no service.
334
337
 
335
338
  Building a catalog (`gezel knowledge build`) and `gezel knowledge search
336
339
  --semantic` also need the embedding runtime, which an npm install leaves out.
@@ -348,9 +351,9 @@ which keep Kokoro on the same Transformers.js copy as the service.
348
351
  ## Running models on your own machine
349
352
 
350
353
  On-device chat, local image and video generation, and speech-to-text need
351
- native engine binaries (llama.cpp, stable-diffusion.cpp, whisper.cpp, uv).
352
- They are far too large to ship inside an npm package — the CUDA build alone is
353
- over 700 MB — so they are downloaded once, on request:
354
+ native engines (llama.cpp, stable-diffusion.cpp, whisper.cpp, uv). They are far
355
+ too large for an npm package (the CUDA build alone is over 700 MB), so they
356
+ download once, when you ask:
354
357
 
355
358
  ```bash
356
359
  gezel native install # this platform's default backend
@@ -358,79 +361,79 @@ gezel native install --variant cuda # or cpu / vulkan / metal
358
361
  gezel native status
359
362
  ```
360
363
 
361
- Downloads come from this repository's `native-v*` GitHub releases and are
362
- verified before use. Every archive SHA256 is compiled into the published
363
- package; the release's `SHA256SUMS` file must both match its own compiled
364
- digest and agree with the selected compiled archive hash. The downloaded
365
- archive is then hashed against that local value.
366
-
367
- First-party Windows executables and loadable DLLs must carry a valid Bendyline
368
- Authenticode signature, while macOS executable code must carry the expected
369
- Developer ID.
370
- Standalone macOS archives are accepted by Apple's notary service in release
371
- CI before their hashes are pinned. Bare command-line binaries cannot carry a
372
- stapled ticket or be assessed as app bundles, so runtime checks combine those
373
- source-pinned hashes with Developer ID validation. Electron reuse separately
374
- requires a `Notarized Developer ID` Gatekeeper assessment of the parent
375
- `.app`. Linux has no equivalent native signing channel and remains anchored
376
- by the compiled hashes. The upstream `uv.exe` is an explicit unsigned
377
- exception, verified by its compiled
378
- archive hash. Each CLI release resolves one exact native release rather than
379
- following `latest`; the setup prompt shows that pinned version. Nothing is
380
- fetched until you ask for it.
364
+ Downloads come from the `native-v*` releases on
365
+ [GitHub](https://github.com/bendyline/gezel/releases/) and are verified before
366
+ use. Each CLI release pins one exact native release, and every archive's
367
+ SHA-256 is compiled into the package. Gezel's own Windows binaries must also
368
+ carry Bendyline's Authenticode signature and its macOS binaries the expected
369
+ Developer ID; Linux binaries are checked against the compiled hashes. Nothing
370
+ is fetched until you ask for it.
371
+
372
+ ## How the CLI finds Gezel
373
+
374
+ With no connection flags, the CLI uses your own per-user Gezel service. It
375
+ finds it through `~/.gezel/runtime` (its port and pinned TLS certificate) and
376
+ connects as you, so there is no approval prompt and no need for the desktop
377
+ app.
378
+
379
+ - Management commands start that service when it is not running and say so on
380
+ stderr. It keeps running afterward, until `gezel stop`, and logs to
381
+ `~/.gezel/logs/service-YYYY-MM-DD.log` (rolled at 10 MB, kept 7 days).
382
+ - Read-only diagnostics such as `gezel native status` never leave a service
383
+ behind.
384
+ - The interactive app shuts down a service it started when you exit.
385
+ - `gezel run` with no service running starts one for that prompt and stops it
386
+ afterward. It does not do that when a running service is unhealthy.
387
+
388
+ A service the CLI starts listens on port 6228 when it is free, so other apps
389
+ get a stable OpenAI-compatible address (`https://127.0.0.1:6228/v1`), and on a
390
+ free port otherwise; `--port` pins one. When the desktop app has installed its
391
+ machine-wide service, that service owns 6228. A current machine-wide service
392
+ only runs models: the CLI never sends it projects, keys, or tools, and your own
393
+ service uses it for model downloads and inference. While you upgrade from an
394
+ older desktop release, an older machine-wide service that still holds your
395
+ gezels and projects is used instead; `--standalone` skips it.
396
+
397
+ Your own service may reuse two things the desktop app's machine install
398
+ publishes, read-only: its downloaded models (your own models take precedence,
399
+ and a shared model is re-hashed before its first use), and its native engines
400
+ when they match the CLI's pinned release file for file and pass the signature
401
+ checks. Anything else is downloaded into your own home. The CLI never reads the
402
+ machine service's private data.
403
+
404
+ The connection flags are:
381
405
 
382
- ## Commands
406
+ ```bash
407
+ gezel --connect https://host:6228 # another Gezel; approve on first use
408
+ gezel --connect https://host:6228 --token "$TOKEN"
409
+ gezel --standalone # skip an older machine-wide service
410
+ gezel --home /path/to/another-home # a separate Gezel home
411
+ ```
383
412
 
384
- Run `gezel --help` for the full list. The most-used ones:
413
+ `--connect` needs a CLI grant from that Gezel. Without a saved grant or
414
+ `--token`, the terminal shows a six-character code and waits for you to approve
415
+ **Gezel CLI** in that Gezel app. The revocable credential is saved under
416
+ `~/.gezel/cli/tokens/`. `gezel stop` cannot shut down a service you reach with
417
+ `--connect`; `gezel stop --keep-running` stops its AI work.
385
418
 
386
- | Command | What it does |
387
- |---|---|
388
- | `gezel` | Launch the interactive TUI |
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 |
392
- | `gezel workflow <name-or-file> [args…]` | Run an explicitly trusted repository workflow from `.gezel/workflows/<name>.mjs` or a module path |
393
- | `gezel secret list / set / remove` | Manage write-only provider credentials, including the Brave search key |
394
- | `gezel task wait <ref>` / `resume <ref>` | Follow a task to completion, or retry a paused task and follow it |
395
- | `gezel task notes <ref> --warnings` | Read task notes and runtime warnings from its recent sessions |
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). |
397
- | `gezel doctor` | Report on the local install |
398
- | `gezel mode [read-only\|reactive\|reactive+tasks\|full-play]` | Show or change how much AI activity is allowed |
399
- | `gezel agent list\|create\|show` | Manage your gezels |
400
- | `gezel project list\|create\|install` | Manage projects and their packages (`gezel env` is the same command) |
401
- | `gezel task list\|create\|show` | Manage tasks |
402
- | `gezel model list\|pull\|export` | Manage on-device chat models. `export <id> [file]` downloads the catalog model if needed, then writes a portable, checksum-verified `.gezmodel` you can move to another machine |
403
- | `gezel native install\|list\|status` | Manage native engine binaries |
404
- | `gezel create-image\|create-video\|create-audio` | Generate media |
405
- | `gezel skills import\|convert` | Import and convert skills |
406
- | `gezel handboek export --out <dir>` | Export the handbook |
407
-
408
- Inside the interactive TUI, `/continue` processes due schedules and reconciles
409
- gezel-owned active tasks for the current project. Night Shift is managed with
410
- `/nightshift start`, `/nightshift stop`, and `/nightshift list`; the command
411
- wordwheel exposes all three subcommands. `/mode` opens a picker for the same
412
- four activity levels as the one-shot command; `/mode reactive+tasks` (for
413
- example) switches directly. `/model` lists every installed user/shared model
414
- and includes **Download a new model**; `/model download` opens that device-ranked
415
- download list directly. A completed download is selected for the active gezel
416
- and starts a fresh chat. Project edit permissions are available through
417
- `/allow` and `/disallow`: use `edits` for built-in tools and background work,
418
- `codexedits` for Codex sessions, or `claudeedits` for Claude sessions. For
419
- example, `/disallow edits` makes Gezel-managed access to the current project
420
- read-only, while `/allow codexedits` puts Codex in project-scoped edit mode.
419
+ `--home <dir>` (or an explicit `GEZEL_HOME`) implies `--standalone`. A home you
420
+ name with `--home` is also kept separate from what the Gezel desktop app's
421
+ machine install publishes: its shared gezels and projects, and the models it
422
+ downloaded. Set `GEZEL_DISABLE_MACHINE_SHARED=0` to include them anyway. Your
423
+ default home, `~/.gezel`, still sees them.
421
424
 
422
425
  ## Stability
423
426
 
424
- The supported public surface of this package is its **command line** — the
425
- commands, their flags, and their output contracts. It ships no JavaScript API;
426
- `import`ing from it is unsupported and its internal module layout will change
427
- without a major version bump.
427
+ The supported public surface of this package is its **command line**: the
428
+ commands, their flags, and their output. It ships no JavaScript API; importing
429
+ from it is unsupported, and its internal modules can change in any release.
428
430
 
429
431
  Breaking changes to commands or flags follow semver.
430
432
 
431
433
  ## Documentation
432
434
 
433
435
  - [Repository and full documentation](https://github.com/bendyline/gezel)
434
- - [Release process](https://github.com/bendyline/gezel/blob/main/docs/npm-release.md)
436
+ - [The gezel command line](https://github.com/bendyline/gezel/blob/main/docs/handboek/technical/cli-reference.md)
437
+ in the Handboek
435
438
 
436
439
  MIT © Bendyline