@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 +312 -309
- package/dist/app-author-command.js +4 -2
- package/dist/app-command.js +4 -2
- package/dist/bin/gezel-main.js +718 -62
- package/dist/knowledge-command.js +4 -2
- package/dist/tui/index.js +63 -28
- package/package.json +11 -11
package/README.md
CHANGED
|
@@ -1,113 +1,120 @@
|
|
|
1
1
|
# @bendyline/gezel-cli
|
|
2
2
|
|
|
3
|
-
The `gezel` command line
|
|
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
|
-
|
|
7
|
-
|
|
8
|
-
|
|
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
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
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
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
19
|
+
```bash
|
|
20
|
+
gezel model list --available
|
|
21
|
+
gezel model pull <id>
|
|
22
|
+
gezel model use <id>
|
|
23
|
+
```
|
|
82
24
|
|
|
83
|
-
|
|
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
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
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
|
-
|
|
33
|
+
Now start working:
|
|
95
34
|
|
|
96
35
|
```bash
|
|
97
|
-
gezel
|
|
98
|
-
gezel
|
|
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
|
-
|
|
104
|
-
|
|
105
|
-
|
|
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
|
-
|
|
110
|
-
|
|
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
|
|
119
|
-
|
|
120
|
-
|
|
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
|
|
130
|
+
## Provider keys
|
|
123
131
|
|
|
124
|
-
|
|
125
|
-
|
|
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
|
-
`--
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
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
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
`gezel
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
`gezel
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
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
|
|
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
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
timeout
|
|
200
|
-
|
|
201
|
-
|
|
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
|
|
204
|
-
`.gezel/workflows/
|
|
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({
|
|
208
|
-
const
|
|
209
|
-
|
|
210
|
-
|
|
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
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
`
|
|
218
|
-
|
|
219
|
-
`
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
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
|
|
253
|
+
label: 'fact-check, paragraph 3',
|
|
236
254
|
});
|
|
237
255
|
```
|
|
238
256
|
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
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
|
|
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)
|
|
275
|
-
|
|
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,
|
|
278
|
-
|
|
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
|
|
282
|
-
(naming the security level
|
|
283
|
-
then proven with one test search, and
|
|
284
|
-
|
|
285
|
-
|
|
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
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
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
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
-
|
|
331
|
-
|
|
332
|
-
- Knowledge catalogs you already have: `gezel knowledge validate`, `inspect
|
|
333
|
-
and full-text `search` work offline, with no
|
|
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
|
|
352
|
-
|
|
353
|
-
|
|
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
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
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
|
|
425
|
-
commands, their flags, and their output
|
|
426
|
-
|
|
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
|
-
- [
|
|
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
|