@bendyline/gezel-cli 0.1.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Bendyline
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,163 @@
1
+ # @bendyline/gezel-cli
2
+
3
+ The `gezel` command line — assemble a team of AI companions (*gezellen*) and put
4
+ them to work from your terminal.
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.
9
+
10
+ ```bash
11
+ npm install -g @bendyline/gezel-cli
12
+ gezel
13
+ ```
14
+
15
+ On a clean machine, the TUI stays in first-time setup until you decide what to
16
+ install. It offers the verified native toolkit first, then device-ranked model
17
+ choices:
18
+
19
+ 1. The best chat model plus every recommended image, speech, reading, and video
20
+ helper that fits this device.
21
+ 2. The best chat model only.
22
+ 3. Other compatible chat-only models, ordered for this device.
23
+
24
+ Downloads show live progress and activate inside the running daemon, so setup
25
+ continues directly into the TUI without a restart.
26
+
27
+ ## Which Gezel service the CLI uses
28
+
29
+ With no connection flags, the CLI follows this order:
30
+
31
+ 1. During rolling-upgrade compatibility only, use an older `legacy-full`
32
+ machine service when one is present. A modern machine service on port
33
+ `6228` is an engine broker, not a product API, so the CLI never sends it
34
+ projects, credentials, tools, or terminal requests.
35
+ 2. Discover the logged-in user's product daemon through the Gezel app SDK.
36
+ Its actual dynamic port and pinned TLS certificate come from
37
+ `~/.gezel/runtime`; management commands may start that user-role daemon
38
+ when it is absent.
39
+ 3. On first use, the terminal waits while the Gezel app asks you to approve
40
+ **Gezel CLI**. The terminal shows a six-character code that you enter in
41
+ the app to confirm that you initiated the request. The resulting revocable,
42
+ CLI-scoped credential is saved under `~/.gezel/cli/tokens/`. Its logical
43
+ local key survives daemon port and certificate rotation.
44
+
45
+ `gezel run` has one deliberate lifecycle exception: if no user daemon exists,
46
+ it starts a user-role service in-process for that one invocation and stops it
47
+ afterward. It does not take that fallback after a denied grant or when a live
48
+ daemon is unhealthy.
49
+
50
+ The per-user daemon owns gezels, projects, settings, credentials, and
51
+ conversations with ordinary user filesystem permissions. It discovers the
52
+ machine engine broker independently for centralized model downloads and local
53
+ inference. The CLI does **not** open the machine service's private data
54
+ directory directly.
55
+
56
+ It may reuse two deliberately public asset surfaces:
57
+
58
+ - Immutable machine models under the installer-owned `assets/models/` tree.
59
+ User-owned models in `~/.gezel/engines/` take precedence; the CLI re-hashes
60
+ a machine model on first adoption, caches file identity/size/mtime locally,
61
+ and downloads replacements only into its user-owned home.
62
+ - Electron's `native-bin/` payload when its native release exactly matches the
63
+ CLI pin, every executable/loadable file matches the per-file hashes embedded
64
+ in the CLI, and platform signing checks pass. Any mismatch falls back to the
65
+ CLI's independently downloaded native cache.
66
+
67
+ The global overrides are:
68
+
69
+ ```bash
70
+ gezel --connect https://host:6228 # explicit service; approval on first use
71
+ gezel --connect https://host:6228 --token "$TOKEN"
72
+ gezel --standalone # skip legacy-full compatibility
73
+ gezel --home /path/to/another-home # standalone with an alternate home
74
+ ```
75
+
76
+ `--home` (and an explicitly set `GEZEL_HOME`) implies standalone operation.
77
+ An explicit `--port 6228` remains available when you intentionally want a
78
+ CLI-owned daemon on the canonical port.
79
+
80
+ ## What you get with no further setup
81
+
82
+ The install is pure JavaScript. Straight away you can use:
83
+
84
+ - The interactive TUI (`gezel`) and one-shot prompts (`gezel run "…"`)
85
+ - Cloud providers — OpenAI, Anthropic, GitHub Copilot, and any
86
+ OpenAI-compatible endpoint
87
+ - Gezel and project management (`gezel agent`, `gezel env`, `gezel task`)
88
+ - Skills and handbook export (`gezel skills convert`, `gezel handboek export`) —
89
+ these need no running daemon at all
90
+
91
+ ## Running models on your own machine
92
+
93
+ On-device chat, local image and video generation, and speech-to-text need
94
+ native engine binaries (llama.cpp, stable-diffusion.cpp, whisper.cpp, uv).
95
+ They are far too large to ship inside an npm package — the CUDA build alone is
96
+ over 700 MB — so they are downloaded once, on request:
97
+
98
+ ```bash
99
+ gezel native install # this platform's default backend
100
+ gezel native install --variant cuda # or cpu / vulkan / metal
101
+ gezel native status
102
+ ```
103
+
104
+ Downloads come from this repository's `native-v*` GitHub releases and are
105
+ verified before use. Every archive SHA256 is compiled into the published
106
+ package; the release's `SHA256SUMS` file must both match its own compiled
107
+ digest and agree with the selected compiled archive hash. The downloaded
108
+ archive is then hashed against that local value.
109
+
110
+ First-party Windows executables and loadable DLLs must carry a valid Bendyline
111
+ Authenticode signature, while macOS executable code must carry the expected
112
+ Developer ID.
113
+ Standalone macOS archives are accepted by Apple's notary service in release
114
+ CI before their hashes are pinned. Bare command-line binaries cannot carry a
115
+ stapled ticket or be assessed as app bundles, so runtime checks combine those
116
+ source-pinned hashes with Developer ID validation. Electron reuse separately
117
+ requires a `Notarized Developer ID` Gatekeeper assessment of the parent
118
+ `.app`. Linux has no equivalent native signing channel and remains anchored
119
+ by the compiled hashes. The upstream `uv.exe` is an explicit unsigned
120
+ exception, verified by its compiled
121
+ archive hash. Each CLI release resolves one exact native release rather than
122
+ following `latest`; the setup prompt shows that pinned version. Nothing is
123
+ fetched until you ask for it.
124
+
125
+ ## Commands
126
+
127
+ Run `gezel --help` for the full list. The most-used ones:
128
+
129
+ | Command | What it does |
130
+ |---|---|
131
+ | `gezel` | Launch the interactive TUI |
132
+ | `gezel run [prompt…]` | One-shot prompt, optionally `--gezel <id>` |
133
+ | `gezel start` / `stop` / `status` | Use or inspect the selected service; `stop` only stops a user-owned daemon (`--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). |
134
+ | `gezel doctor` | Report on the local install |
135
+ | `gezel agent list\|create\|show` | Manage your gezels |
136
+ | `gezel env list\|create\|install` | Manage projects and their packages |
137
+ | `gezel task list\|create\|show` | Manage tasks |
138
+ | `gezel model list\|pull` | Manage on-device chat models |
139
+ | `gezel native install\|list\|status` | Manage native engine binaries |
140
+ | `gezel create-image\|create-video\|create-audio` | Generate media |
141
+ | `gezel skills import\|convert` | Import and convert skills |
142
+ | `gezel handboek export --out <dir>` | Export the handbook |
143
+
144
+ Inside the interactive TUI, `/continue` processes due schedules and reconciles
145
+ gezel-owned active tasks for the current project. Night Shift is managed with
146
+ `/nightshift start`, `/nightshift stop`, and `/nightshift list`; the command
147
+ wordwheel exposes all three subcommands.
148
+
149
+ ## Stability
150
+
151
+ The supported public surface of this package is its **command line** — the
152
+ commands, their flags, and their output contracts. It ships no JavaScript API;
153
+ `import`ing from it is unsupported and its internal module layout will change
154
+ without a major version bump.
155
+
156
+ Breaking changes to commands or flags follow semver.
157
+
158
+ ## Documentation
159
+
160
+ - [Repository and full documentation](https://github.com/bendyline/gezel)
161
+ - [Release process](https://github.com/bendyline/gezel/blob/main/docs/npm-release.md)
162
+
163
+ MIT © Bendyline