@vention/vention-cli 0.38.39 → 0.38.40

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
@@ -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 18 or higher
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: prompts for design and app selection, creates a new folder
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
- - Prompts for design and app selection
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 agent's own CLI for Claude Code (2.1.277 or later) or Codex
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: The last push/pull wins. There's no conflict resolution or merging. We recommend using version control (Git) for your local copy.
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.