@vention/vention-cli 0.38.39 → 0.38.41
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 +100 -13
- package/main.esm.js +1423 -1129
- package/package.json +2 -2
- package/src/cli-helpers.d.ts +17 -9
- package/src/commands/login.d.ts +1 -0
- package/src/commands/skills.d.ts +1 -0
- package/src/commands/whoami.d.ts +2 -0
- package/src/machine-code-app-directory-info.d.ts +1 -0
- package/src/selection-options.d.ts +2 -0
- package/src/sync-state.d.ts +8 -0
package/README.md
CHANGED
|
@@ -26,6 +26,7 @@
|
|
|
26
26
|
- **Smart file handling**: Automatically ignores build artifacts, virtual environments, and common development files
|
|
27
27
|
- **Session management**: Persistent authentication with secure token storage
|
|
28
28
|
- **Multiple apps support**: Link and switch between different apps within the same design
|
|
29
|
+
- **Safe sync**: `pull` and `push` refuse to overwrite changes made on the other side since your last sync
|
|
29
30
|
|
|
30
31
|
---
|
|
31
32
|
|
|
@@ -43,7 +44,7 @@ When you pull or link an app, the CLI creates a `.machine-code-app-directory-inf
|
|
|
43
44
|
|
|
44
45
|
- **Pull**: Downloads the app's source files from MachineBuilder and writes them to your local directory
|
|
45
46
|
- **Push**: Serializes local files and uploads them to the active design in MachineBuilder
|
|
46
|
-
- **Ignored patterns**: `venv`, `.venv`, `node_modules`, `dist`, `build`, `__pycache__`, `.claude`, `.agents`, `.git`, `*.egg-info`, `.machine-code-app-directory-info.json`, `.vention-design-scene-assets.json`, `.vention-design-configuration.json`
|
|
47
|
+
- **Ignored patterns**: `venv`, `.venv`, `node_modules`, `dist`, `build`, `__pycache__`, `.claude`, `.agents`, `.git`, `.DS_Store`, `Thumbs.db`, `desktop.ini`, `*.egg-info`, `.machine-code-app-directory-info.json`, `.vention-design-scene-assets.json`, `.vention-design-configuration.json`
|
|
47
48
|
|
|
48
49
|
### Read-only Config & Scene Assets
|
|
49
50
|
|
|
@@ -64,7 +65,7 @@ OAuth-based authentication opens a browser window for secure login. Session toke
|
|
|
64
65
|
|
|
65
66
|
**Requirements:**
|
|
66
67
|
|
|
67
|
-
- Node.js
|
|
68
|
+
- Node.js 20 or higher
|
|
68
69
|
- npm or yarn
|
|
69
70
|
- Active MachineBuilder session with MachineLogic tab open
|
|
70
71
|
- Vention CLI 0.37.0 or later to pull, push and read logs for your MachineLogic Python apps (see [Upgrade](#upgrade))
|
|
@@ -131,7 +132,7 @@ The CLI will:
|
|
|
131
132
|
- Show available active designs
|
|
132
133
|
- Let you select a design
|
|
133
134
|
- Display MachineLogic Python apps in that design
|
|
134
|
-
- Let you select an app to pull
|
|
135
|
+
- Let you select an app to pull (a single open design or app is picked for you)
|
|
135
136
|
- Create a folder named after the app with all source files (special characters in the name are replaced with underscores)
|
|
136
137
|
|
|
137
138
|
**Step 4: Edit locally**
|
|
@@ -180,6 +181,30 @@ To link your current directory to a different app:
|
|
|
180
181
|
1. Delete the `.machine-code-app-directory-info.json` file
|
|
181
182
|
2. Run `vention link` or `vention pull` and select the new app
|
|
182
183
|
|
|
184
|
+
### Pull or link without a menu
|
|
185
|
+
|
|
186
|
+
Pass the design and app yourself. This is what Claude does when no terminal is available:
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
vention pull --design 12345 --app "My App"
|
|
190
|
+
vention link --design 12345 --app "My App"
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
### Overwrite changes on purpose
|
|
194
|
+
|
|
195
|
+
`vention pull` stops when files in the folder changed since your last pull or push, and `vention push` stops when files changed on the design since then. Both list the files. Run `vention push` first to keep local changes, or add `--force` to replace the other side:
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
vention pull --force
|
|
199
|
+
vention push --force
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### Check which account you are signed in with
|
|
203
|
+
|
|
204
|
+
```bash
|
|
205
|
+
vention whoami
|
|
206
|
+
```
|
|
207
|
+
|
|
183
208
|
### View your application's logs
|
|
184
209
|
|
|
185
210
|
If your directory is linked and the design is active in MachineBuilder:
|
|
@@ -226,6 +251,7 @@ vention login
|
|
|
226
251
|
|
|
227
252
|
**Behavior:**
|
|
228
253
|
|
|
254
|
+
- Prints a warning first when no web browser can open (for example in Claude Desktop's Chat or Cowork), telling you to use the Code tab or another computer
|
|
229
255
|
- Opens a browser window for secure OAuth authentication
|
|
230
256
|
- Stores session tokens in `~/.vention-cli-config.json`
|
|
231
257
|
- Tokens persist across terminal sessions and are refreshed automatically
|
|
@@ -237,6 +263,29 @@ vention login
|
|
|
237
263
|
|
|
238
264
|
---
|
|
239
265
|
|
|
266
|
+
### `vention whoami`
|
|
267
|
+
|
|
268
|
+
**Description:** Show which Vention account you are signed in with.
|
|
269
|
+
|
|
270
|
+
**Usage:**
|
|
271
|
+
|
|
272
|
+
```bash
|
|
273
|
+
vention whoami
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
**Behavior:**
|
|
277
|
+
|
|
278
|
+
- Prints `Signed in to Vention as <email> (<environment>).`
|
|
279
|
+
- If you signed in with an older CLI, the email is missing until you run `vention login` again
|
|
280
|
+
- Prints `Not signed in. Run 'vention login'.` or `Your Vention sign-in has expired. Run 'vention login'.` when there is no valid session
|
|
281
|
+
|
|
282
|
+
**Exit codes:**
|
|
283
|
+
|
|
284
|
+
- `0`: Signed in
|
|
285
|
+
- `1`: Not signed in, or the sign-in expired
|
|
286
|
+
|
|
287
|
+
---
|
|
288
|
+
|
|
240
289
|
### `vention pull`
|
|
241
290
|
|
|
242
291
|
**Description:** Fetch a MachineLogic Python app from your active design into the current directory.
|
|
@@ -244,13 +293,20 @@ vention login
|
|
|
244
293
|
**Usage:**
|
|
245
294
|
|
|
246
295
|
```bash
|
|
247
|
-
vention pull
|
|
296
|
+
vention pull [--design <id>] [--app <name>] [--force]
|
|
248
297
|
```
|
|
249
298
|
|
|
299
|
+
**Options:**
|
|
300
|
+
|
|
301
|
+
- `--design <id>`: ID of the open design to use. Must be a number
|
|
302
|
+
- `--app <name>`: Name or ID of the application to use
|
|
303
|
+
- `--force`: Overwrite files changed in this folder since the last pull or push
|
|
304
|
+
|
|
250
305
|
**Behavior:**
|
|
251
306
|
|
|
252
|
-
- If the directory is not linked:
|
|
253
|
-
- If the directory is already linked: updates files in place using stored link metadata
|
|
307
|
+
- If the directory is not linked: picks the design and app, creates a new folder. A single open design or app is used without a menu. Without a terminal and with several to choose from, it lists them, says which flag to pass, and exits with `1`
|
|
308
|
+
- If the directory is already linked: updates files in place using stored link metadata. If it is linked to a different app than the one you ask for, it refuses and tells you to pull into a new, empty folder
|
|
309
|
+
- Refuses to overwrite files changed locally since the last sync, and lists them. Run `vention push` first to keep them, or `vention pull --force` to throw them away. Folders last synced by an older CLI skip this check until their next pull or push. Generated files (the top-level `ui/` folder, `proto/app.proto` and `customui/src/gen/`) are not checked
|
|
254
310
|
- Downloads all source files except ignored patterns
|
|
255
311
|
- Writes read-only `.vention-design-configuration.json` and `.vention-design-scene-assets.json` reference files (the latter only when the design has scene assets)
|
|
256
312
|
- Writes/updates `.machine-code-app-directory-info.json`
|
|
@@ -276,12 +332,17 @@ vention pull
|
|
|
276
332
|
**Usage:**
|
|
277
333
|
|
|
278
334
|
```bash
|
|
279
|
-
vention push
|
|
335
|
+
vention push [--force]
|
|
280
336
|
```
|
|
281
337
|
|
|
338
|
+
**Options:**
|
|
339
|
+
|
|
340
|
+
- `--force`: Replace files changed on the design since the last pull or push
|
|
341
|
+
|
|
282
342
|
**Behavior:**
|
|
283
343
|
|
|
284
344
|
- If the directory is not linked: offers to link it to an application and continue the push
|
|
345
|
+
- Refuses to replace files changed on the design since the last sync, and lists them. To keep them, pull into a new, empty folder and copy your changes across; to replace them, run `vention push --force`. Folders from an older CLI skip this check until their next pull or push. Generated files (the top-level `ui/` folder, `proto/app.proto` and `customui/src/gen/`) are not checked
|
|
285
346
|
- Reads `.machine-code-app-directory-info.json` to identify target design/app
|
|
286
347
|
- Serializes all local files except ignored patterns
|
|
287
348
|
- Uploads to MachineBuilder
|
|
@@ -306,14 +367,20 @@ vention push
|
|
|
306
367
|
**Usage:**
|
|
307
368
|
|
|
308
369
|
```bash
|
|
309
|
-
vention link
|
|
370
|
+
vention link [--design <id>] [--app <name>]
|
|
310
371
|
```
|
|
311
372
|
|
|
373
|
+
**Options:**
|
|
374
|
+
|
|
375
|
+
- `--design <id>`: ID of the open design to use. Must be a number
|
|
376
|
+
- `--app <name>`: Name or ID of the application to use
|
|
377
|
+
|
|
312
378
|
**Behavior:**
|
|
313
379
|
|
|
314
|
-
-
|
|
380
|
+
- Picks the design and app the same way as `vention pull`: no menu for a single open design or app, and a list plus the flag to pass when there is no terminal
|
|
315
381
|
- Writes `.machine-code-app-directory-info.json` with link metadata
|
|
316
382
|
- Does not download or modify existing files
|
|
383
|
+
- Records the design's copy of the app as the last sync: a later `push` refuses to replace files changed on the design since the link, and a later `pull` refuses to overwrite files here that differ from that copy
|
|
317
384
|
|
|
318
385
|
**Use case:** Useful when you already have the app files and just want to establish the connection for push operations.
|
|
319
386
|
|
|
@@ -368,13 +435,16 @@ vention skills status
|
|
|
368
435
|
**Behavior:**
|
|
369
436
|
|
|
370
437
|
- `install` asks which agent you use unless `--agent` is given. Claude Code and Codex install the `vention` plugin through their own plugin managers from the `vention-skills` catalog at `https://assets.vention.com/vention-skills/marketplace.json`; Cursor and Copilot get the skills unpacked from the `@vention/vention-skills` npm package into `.agents/skills`
|
|
438
|
+
- When the `claude` command is missing (Claude Desktop bundles Claude Code without it), `install --agent claude-code` adds the `vention-skills` marketplace, with `autoUpdate` on, and the `vention` plugin to `~/.claude/settings.json`. This is always your user account, even with `--scope project`, because a plugin only enabled in a project's settings does not load. Start a new session in the Code tab to load them. On Windows a missing command is detected with `where`
|
|
439
|
+
- `install` with no `--agent` and no terminal to ask in prints the `--agent` choices and exits with code 1
|
|
371
440
|
- `--scope` defaults to `user`; Codex always installs for your user account
|
|
372
|
-
- `update` finds every agent that has the skills and updates it to the latest version on npm: `claude plugin update` for Claude Code, a rerun of the install for Codex, and a fresh unpack at the installed scope for Cursor and Copilot. It prints each agent's old and new version. Skills copied by hand into `.claude/skills` are left alone
|
|
441
|
+
- `update` finds every agent that has the skills and updates it to the latest version on npm: `claude plugin update` for Claude Code, a rerun of the install for Codex, and a fresh unpack at the installed scope for Cursor and Copilot. It prints each agent's old and new version. Without the `claude` command it says Claude Desktop updates the skills on its own, loading the new version in the next new session. Skills copied by hand into `.claude/skills` are left alone
|
|
373
442
|
- `status` lists every Vention skill on disk with its version and location, next to the latest version on npm. If npm can't be reached it still lists them and says the latest version couldn't be checked
|
|
374
443
|
|
|
375
444
|
**Prerequisites:**
|
|
376
445
|
|
|
377
|
-
- Node.js and npm, plus the
|
|
446
|
+
- Node.js and npm, plus the `codex` command for Codex
|
|
447
|
+
- Claude Code: the `claude` command (2.1.277 or later) installs through its plugin manager. Claude Desktop has no `claude` command and needs none: the CLI writes `~/.claude/settings.json` for your user account, and Claude Desktop keeps the skills updated on its own
|
|
378
448
|
|
|
379
449
|
---
|
|
380
450
|
|
|
@@ -392,7 +462,8 @@ vention skills status
|
|
|
392
462
|
"uuid": "optional-app-uuid",
|
|
393
463
|
"environment": "prod",
|
|
394
464
|
"lastPulledAt": "2025-01-01T12:34:56.789Z",
|
|
395
|
-
"lastPushedAt": "2025-01-02T09:10:11.123Z"
|
|
465
|
+
"lastPushedAt": "2025-01-02T09:10:11.123Z",
|
|
466
|
+
"syncedFiles": { "main.py": "<fingerprint>" }
|
|
396
467
|
}
|
|
397
468
|
```
|
|
398
469
|
|
|
@@ -405,6 +476,7 @@ vention skills status
|
|
|
405
476
|
- `environment` (string): Target environment (one of `local`, `demo`, `prod`)
|
|
406
477
|
- `lastPulledAt` (ISO 8601 timestamp): Last successful pull time (also set when the directory is first linked)
|
|
407
478
|
- `lastPushedAt` (ISO 8601 timestamp): Last successful push time
|
|
479
|
+
- `syncedFiles` (object, optional): A fingerprint per file as of the last pull or push. `pull` and `push` use it to detect changes made on the other side. Written by CLI versions that have the safe sync check; folders without it skip the check until their next pull or push
|
|
408
480
|
|
|
409
481
|
---
|
|
410
482
|
|
|
@@ -417,6 +489,11 @@ vention skills status
|
|
|
417
489
|
- **Cause:** Authentication tokens not found or expired
|
|
418
490
|
- **Solution:** Run `vention login` to re-authenticate
|
|
419
491
|
|
|
492
|
+
**"No design is open on its MachineLogic tab…"**
|
|
493
|
+
|
|
494
|
+
- **Cause:** `pull` or `link` found no design with the MachineLogic tab open, or the design was opened moments ago and is still starting
|
|
495
|
+
- **Solution:** Open the design in MachineBuilder, click its MachineLogic tab and keep that browser tab open. If you just opened it, wait about a minute, then run the command again
|
|
496
|
+
|
|
420
497
|
**"No active allocations found …" or "Sorry, it seems you do not have that design open …"**
|
|
421
498
|
|
|
422
499
|
- **Cause:** No designs have the MachineLogic tab open in MachineBuilder
|
|
@@ -427,6 +504,16 @@ vention skills status
|
|
|
427
504
|
- **Cause:** The CLI is older than 0.37.0. Older versions can no longer reach your MachineLogic Python apps, so they report the design as not open.
|
|
428
505
|
- **Solution:** Run `vention --version`. Below 0.37.0, follow [Upgrade](#upgrade) and retry. At 0.37.0 or later, contact Vention support with the output of the failing command run with `vention --verbose`.
|
|
429
506
|
|
|
507
|
+
**"These files changed here since your last pull:" or "These files changed on the design since your last pull:"**
|
|
508
|
+
|
|
509
|
+
- **Cause:** `pull` found files you changed locally, or `push` found files changed on the design, since the last sync
|
|
510
|
+
- **Solution:** Follow the message. To keep local changes, run `vention push` first. To keep design changes, pull into a new, empty folder and copy your work across. To overwrite on purpose, add `--force`
|
|
511
|
+
|
|
512
|
+
**"This folder is linked to … To pull a different application, run 'vention pull' in a new, empty folder."**
|
|
513
|
+
|
|
514
|
+
- **Cause:** `vention pull` ran in a folder linked to another app
|
|
515
|
+
- **Solution:** Run it in a new, empty folder
|
|
516
|
+
|
|
430
517
|
**"This directory is not linked …"**
|
|
431
518
|
|
|
432
519
|
- **Cause:** The directory doesn't have `.machine-code-app-directory-info.json`
|
|
@@ -469,7 +556,7 @@ A: `venv`, `.venv`, `node_modules`, `dist`, `build`, `__pycache__`, `*.egg-info`
|
|
|
469
556
|
A: Not currently. The ignore list is built into the CLI.
|
|
470
557
|
|
|
471
558
|
**Q: What happens if I edit the same app in both MachineBuilder and locally?**
|
|
472
|
-
A:
|
|
559
|
+
A: `pull` and `push` stop and list the files that changed on the other side since your last sync. There's no merging: use `--force` to overwrite, or copy your changes across first. We recommend using version control (Git) for your local copy.
|
|
473
560
|
|
|
474
561
|
**Q: Does this work with MachineMotion apps?**
|
|
475
562
|
A: The CLI specifically targets MachineLogic Python apps. For MachineMotion development, see the MachineMotion SDK documentation.
|