@bendyline/gezel-cli 1.1.1 → 1.2.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 +124 -3
- package/dist/app-author-command.js +1 -0
- package/dist/app-command.js +16 -24
- package/dist/bin/gezel-main.js +901 -106
- package/dist/handboek-export.js +1 -0
- package/dist/knowledge-command.js +1 -0
- package/dist/tui/index.js +26 -14
- package/package.json +10 -10
package/README.md
CHANGED
|
@@ -89,16 +89,133 @@ gezel --home /path/to/another-home # standalone with an alternate home
|
|
|
89
89
|
An explicit `--port 6228` remains available when you intentionally want a
|
|
90
90
|
CLI-owned daemon on the canonical port.
|
|
91
91
|
|
|
92
|
+
## Provider credentials
|
|
93
|
+
|
|
94
|
+
Manage provider keys through the service credential store, using stdin or an
|
|
95
|
+
existing environment variable so the value does not appear in command arguments:
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
gezel secret list
|
|
99
|
+
gezel secret set braveSearchApiKey --env BRAVE_SEARCH_API_KEY --use-for-search
|
|
100
|
+
gezel secret set openaiApiKey --stdin < /path/to/private-key-file
|
|
101
|
+
gezel secret remove openaiApiKey
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
`--use-for-search` (with `braveSearchApiKey`) also selects Brave as the
|
|
105
|
+
search provider while preserving its other settings. Without it, setting a
|
|
106
|
+
credential leaves provider selection unchanged. `secret list` gives the supported
|
|
107
|
+
names and whether each is configured; credentials are write-only and never
|
|
108
|
+
printed. All three commands support `--json`, and honor `--home` / `--connect`.
|
|
109
|
+
This covers the built-in provider credentials, including webhooks; it is not an
|
|
110
|
+
arbitrary environment-variable store. Storage uses the same native keyring or
|
|
111
|
+
encrypted fallback as the application.
|
|
112
|
+
|
|
113
|
+
Search also requires the selected environment to allow external services.
|
|
114
|
+
`gezel security external-services` shows that setting; append `on` or `off` to
|
|
115
|
+
change it explicitly while preserving all other security capabilities. This
|
|
116
|
+
permission covers model-initiated external services, including web search.
|
|
117
|
+
Saving a credential does not silently enable it.
|
|
118
|
+
|
|
119
|
+
`gezel model context <id> 65536` sets a local model's context window for its next
|
|
120
|
+
launch; omit the token count to inspect it, or use `auto` to clear the override.
|
|
121
|
+
Use `--provider llama-cpp|mlx|ds4` to select an engine (defaults to the platform's
|
|
122
|
+
local engine). This can bound memory use for unattended batch tasks.
|
|
123
|
+
|
|
124
|
+
`gezel model concurrency 1` limits the local engine to one inference slot and
|
|
125
|
+
reduces its context-cache reservation. This is useful for serial batches with
|
|
126
|
+
large models. It preserves other providers' limits; `--provider` selects an
|
|
127
|
+
engine, and `auto` restores automatic sizing. Omit the value to inspect it.
|
|
128
|
+
|
|
129
|
+
`gezel env indexing off` disables optional background workspace indexing in
|
|
130
|
+
the current directory's project (or `--project` target). Artifact-driven batch
|
|
131
|
+
workflows over large generated datasets can use this to avoid unnecessary
|
|
132
|
+
indexing. `on` restores it; omitting the value reports its current state.
|
|
133
|
+
Both settings commands support `--json` and the ordinary connection/home flags.
|
|
134
|
+
|
|
135
|
+
## Batch craftbooks and repository workflows
|
|
136
|
+
|
|
137
|
+
`do` accepts positional parameters in the recipe's `paramSchema.properties`
|
|
138
|
+
order, `key=value` arguments, and repeatable `--param key=value` options:
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
gezel do story-batch c23n limit=3 --wait --json
|
|
142
|
+
gezel task wait my-project/12 --timeout 7200 --json
|
|
143
|
+
gezel task resume my-project/12 --json
|
|
144
|
+
gezel task notes my-project/12 --warnings --json
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Only explicit values are sent; the service resolves defaults such as
|
|
148
|
+
`{{task.dir}}` after allocating the task. Waiting exits with 0 for completion,
|
|
149
|
+
1 for cancellation, 2 for a paused task or pending user question, and 3 for a
|
|
150
|
+
timeout. A timeout leaves the daemon task running. Progress goes to stderr;
|
|
151
|
+
`--json` emits the result on stdout. `resume` retries a paused task using its
|
|
152
|
+
saved recipe. Answer pending questions in Gezel before waiting again.
|
|
153
|
+
|
|
154
|
+
For deterministic orchestration around several craftbooks, create
|
|
155
|
+
`.gezel/workflows/storyify.mjs`:
|
|
156
|
+
|
|
157
|
+
```js
|
|
158
|
+
export async function run({ client, projectId, workspace, args, log, runCraftbook }) {
|
|
159
|
+
const [region] = args;
|
|
160
|
+
log(`Working on ${region} in ${workspace}`);
|
|
161
|
+
return runCraftbook('story-batch', { region });
|
|
162
|
+
}
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Run it with `gezel workflow storyify c23n --json`. The module receives the
|
|
166
|
+
public `GezelClient`, the directory's project id, its absolute workspace,
|
|
167
|
+
arguments, a stderr logger, and `runCraftbook(id, params, options)`. That helper
|
|
168
|
+
starts a **project** craftbook and waits; options include `timeoutMs`, a saved
|
|
169
|
+
`taskRef` to follow, `parentTaskRef` to link the child to its batch, and
|
|
170
|
+
`onCreated(task)` to checkpoint the new reference.
|
|
171
|
+
For drivers that generate craftbook documents, `validateCraftbook(document)`
|
|
172
|
+
checks the same schema and step contracts as the daemon and returns the runtime
|
|
173
|
+
craftbook. Call it before installing files or freezing a batch checkpoint;
|
|
174
|
+
invalid documents throw actionable authoring errors without creating a task.
|
|
175
|
+
Returning an object with `exitCode` sets the shell exit status. Module paths
|
|
176
|
+
also work: `gezel workflow ./pipeline/storyify.mjs c23n`.
|
|
177
|
+
|
|
178
|
+
To expose that driver as one command, add
|
|
179
|
+
`"cliWorkflow": { "module": ".gezel/workflows/storyify.mjs" }` to a project
|
|
180
|
+
craftbook and declare its inputs in `paramSchema`. Then run
|
|
181
|
+
`gezel do my-batch c23n limit=200 --json`. Its module receives `craftbook` and
|
|
182
|
+
validated explicit `params` in addition to the context above. The driver owns
|
|
183
|
+
parent creation, defaults, checkpoints, bounded child concurrency, and the
|
|
184
|
+
final result. Modules must resolve inside the project workspace. Only project
|
|
185
|
+
craftbooks can use this entry point; `--strict-sandbox` rejects it.
|
|
186
|
+
|
|
187
|
+
These drivers run in the foreground even without `--wait`; keep the terminal
|
|
188
|
+
open until completion. A timeout applies to each child wait. If the CLI exits,
|
|
189
|
+
already-created daemon tasks survive, but further orchestration requires the
|
|
190
|
+
workflow's resume command. `gezel task wait` observes a parent and its children;
|
|
191
|
+
it does not restart a repository driver.
|
|
192
|
+
|
|
193
|
+
Project recipes live in `.gezel/craftbooks/<id>/manifest.json` (identity) and
|
|
194
|
+
`versions/<version>/craftbook.json` (the complete recipe, including embedded
|
|
195
|
+
scripts). Legacy version manifests plus `scripts/*.ts` remain supported.
|
|
196
|
+
Changing a recipe affects new tasks; running tasks retain their snapshots.
|
|
197
|
+
|
|
198
|
+
CLI craftbook launches, including TUI `/do`, authorize the exact embedded
|
|
199
|
+
script contents in that task snapshot. On Windows and other platforms without
|
|
200
|
+
an enforceable OS network boundary, those scripts use best-effort network
|
|
201
|
+
isolation. Declared capabilities and project/security policies still apply.
|
|
202
|
+
Use `gezel do ... --strict-sandbox` to require the OS boundary instead. Edited
|
|
203
|
+
scripts do not inherit the old source's trust, and a model session cannot
|
|
204
|
+
grant trust. Workflow modules themselves run as ordinary local Node code,
|
|
205
|
+
with the invoking user's permissions, like an npm script.
|
|
206
|
+
|
|
92
207
|
## What you get with no further setup
|
|
93
208
|
|
|
94
209
|
The CLI does not bundle model weights or native inference engines; those are
|
|
95
210
|
downloaded only on demand when you opt into on-device models. Straight away
|
|
96
211
|
you can use:
|
|
97
212
|
|
|
98
|
-
- The interactive TUI (`gezel`)
|
|
213
|
+
- The interactive TUI (`gezel`), which walks you through choosing a model on
|
|
214
|
+
first use, and one-shot prompts (`gezel run "…"`) once a model is set up.
|
|
215
|
+
Until then `run` downloads nothing: it names the setup commands and exits.
|
|
99
216
|
- Cloud providers — OpenAI, Anthropic, GitHub Copilot, and any
|
|
100
217
|
OpenAI-compatible endpoint
|
|
101
|
-
- Gezel and project management (`gezel agent`, `gezel
|
|
218
|
+
- Gezel and project management (`gezel agent`, `gezel project`, `gezel task`)
|
|
102
219
|
- Skills and handbook export (`gezel skills convert`, `gezel handboek export`) —
|
|
103
220
|
these need no running daemon at all
|
|
104
221
|
|
|
@@ -145,11 +262,15 @@ Run `gezel --help` for the full list. The most-used ones:
|
|
|
145
262
|
| `gezel` | Launch the interactive TUI |
|
|
146
263
|
| `gezel run [prompt…]` | One-shot prompt in the current directory's project, using its voorman by default; optionally `--gezel <id>` / `--project <folder>` |
|
|
147
264
|
| `gezel do <craftbook…>` | Start a craftbook as an immediately dispatched task in the current directory's project; accepts its id or display name |
|
|
265
|
+
| `gezel workflow <name-or-file> [args…]` | Run an explicitly trusted repository workflow from `.gezel/workflows/<name>.mjs` or a module path |
|
|
266
|
+
| `gezel secret list / set / remove` | Manage write-only provider credentials, including the Brave search key |
|
|
267
|
+
| `gezel task wait <ref>` / `resume <ref>` | Follow a task to completion, or retry a paused task and follow it |
|
|
268
|
+
| `gezel task notes <ref> --warnings` | Read task notes and runtime warnings from its recent sessions |
|
|
148
269
|
| `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). |
|
|
149
270
|
| `gezel doctor` | Report on the local install |
|
|
150
271
|
| `gezel mode [read-only\|reactive\|reactive+tasks\|full-play]` | Show or change how much AI activity is allowed |
|
|
151
272
|
| `gezel agent list\|create\|show` | Manage your gezels |
|
|
152
|
-
| `gezel
|
|
273
|
+
| `gezel project list\|create\|install` | Manage projects and their packages (`gezel env` is the same command) |
|
|
153
274
|
| `gezel task list\|create\|show` | Manage tasks |
|
|
154
275
|
| `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 |
|
|
155
276
|
| `gezel native install\|list\|status` | Manage native engine binaries |
|
package/dist/app-command.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
|
|
3
3
|
// src/app-command.ts
|
|
4
|
-
import { readFile as readFile2 } from "fs/promises";
|
|
4
|
+
import { readFile as readFile2, realpath } from "fs/promises";
|
|
5
5
|
import { isAbsolute, join as join2, resolve as resolve2 } from "path";
|
|
6
6
|
import { compareSemver } from "@bendyline/gezel";
|
|
7
7
|
|
|
@@ -23,6 +23,7 @@ import {
|
|
|
23
23
|
createTrustingFetch,
|
|
24
24
|
discoverOrSpawn,
|
|
25
25
|
electronNativeBinCandidates,
|
|
26
|
+
ensureProjectForFolder as ensureClientProjectForFolder,
|
|
26
27
|
isProcessAlive,
|
|
27
28
|
readRuntime,
|
|
28
29
|
readSystemServiceEndpoint,
|
|
@@ -39,25 +40,15 @@ var CliError = class extends Error {
|
|
|
39
40
|
};
|
|
40
41
|
async function ensureProjectForFolder(client, folderPath) {
|
|
41
42
|
const wd = resolve(folderPath);
|
|
42
|
-
const eq = (a, b) => !!a && (process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b);
|
|
43
|
-
const { projects } = await client.listProjects();
|
|
44
|
-
const exact = projects.find((p) => eq(p.workingDir, wd));
|
|
45
|
-
if (exact) return exact.id;
|
|
46
43
|
const name = basename(wd) || "workspace";
|
|
47
|
-
const
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
return orphan.id;
|
|
51
|
-
}
|
|
52
|
-
const created = await client.createProject({
|
|
53
|
-
name,
|
|
44
|
+
const result = await ensureClientProjectForFolder(client, wd, {
|
|
45
|
+
mode: "solo",
|
|
46
|
+
source: "cli",
|
|
54
47
|
description: `CLI workspace at ${wd}`,
|
|
55
48
|
about: `${name} \u2014 working directory ${wd}. Fill in who this project is for, what's in scope, and what's explicitly out of scope.`,
|
|
56
|
-
missionObjectives: `${name} \u2014 fill in concrete success criteria for this project
|
|
57
|
-
mode: "solo",
|
|
58
|
-
workingDir: wd
|
|
49
|
+
missionObjectives: `${name} \u2014 fill in concrete success criteria for this project.`
|
|
59
50
|
});
|
|
60
|
-
return
|
|
51
|
+
return result.projectId;
|
|
61
52
|
}
|
|
62
53
|
|
|
63
54
|
// src/app-command.ts
|
|
@@ -306,11 +297,12 @@ async function runAppSetEnabled(client, appId, enabled) {
|
|
|
306
297
|
throw new CliError(apiMessage(err));
|
|
307
298
|
}
|
|
308
299
|
}
|
|
309
|
-
function findProjectForFolder(projects, folder) {
|
|
310
|
-
const
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
);
|
|
300
|
+
async function findProjectForFolder(projects, folder) {
|
|
301
|
+
const requested = resolve2(folder);
|
|
302
|
+
const real = await realpath(requested).catch(() => requested);
|
|
303
|
+
const fold = (p) => process.platform === "win32" || process.platform === "darwin" ? p.toLowerCase() : p;
|
|
304
|
+
const wanted = /* @__PURE__ */ new Set([fold(requested), fold(real)]);
|
|
305
|
+
return projects.find((project) => !!project.workingDir && wanted.has(fold(project.workingDir)));
|
|
314
306
|
}
|
|
315
307
|
function parseParamFlags(flags) {
|
|
316
308
|
const params = {};
|
|
@@ -398,7 +390,7 @@ async function runAppApply(client, appId, folder, opts) {
|
|
|
398
390
|
}
|
|
399
391
|
const params = parseParamFlags(opts.param ?? []);
|
|
400
392
|
const { projects } = await client.listProjects();
|
|
401
|
-
const existing = findProjectForFolder(projects, folder);
|
|
393
|
+
const existing = await findProjectForFolder(projects, folder);
|
|
402
394
|
const projectId = existing?.id ?? await ensureProjectForFolder(client, folder);
|
|
403
395
|
const project = await client.getProject(projectId);
|
|
404
396
|
if (!opts.json) {
|
|
@@ -453,7 +445,7 @@ async function runAppApply(client, appId, folder, opts) {
|
|
|
453
445
|
}
|
|
454
446
|
async function runAppStatus(client, folder, opts) {
|
|
455
447
|
const { projects } = await client.listProjects();
|
|
456
|
-
const project = findProjectForFolder(projects, folder);
|
|
448
|
+
const project = await findProjectForFolder(projects, folder);
|
|
457
449
|
if (!project) {
|
|
458
450
|
console.log(`No gezel project is linked to ${resolve2(folder)}.`);
|
|
459
451
|
console.log("Apply an app here with: gezel app apply <appId>");
|
|
@@ -509,7 +501,7 @@ async function openUrlInBrowser(url) {
|
|
|
509
501
|
async function resolveServeProject(client, appId, folder) {
|
|
510
502
|
const { projects } = await client.listProjects();
|
|
511
503
|
if (!appId) {
|
|
512
|
-
const existing = findProjectForFolder(projects, folder);
|
|
504
|
+
const existing = await findProjectForFolder(projects, folder);
|
|
513
505
|
const projectId = existing?.id ?? await ensureProjectForFolder(client, folder);
|
|
514
506
|
const project = await client.getProject(projectId);
|
|
515
507
|
if (!project.projectType) {
|