@vention/vention-cli 0.9.0 → 0.10.0

package/README.md

@@ -1,39 +1,119 @@
-# @vention/vention-cli
+# Vention CLI — Work locally with MachineLogic Python apps
 
-A command-line interface Tool to interact with MachineCode applications from your local setup
+The Vention CLI lets you pull MachineLogic Python applications from an active design into your local IDE, edit them, and push changes back — without leaving MachineBuilder.
+
+Important:
+- Supports MachineLogic Python apps only. Code-free MachineLogic programs are not supported.
+- You must have the MachineLogic tab open for your design in MachineBuilder. Opening that tab makes the design active for the CLI.
+- Learn about MachineLogic Python app structure (main.py, project.json, HMI, etc.): https://docs.vention.io/docs/machinelogic-python-programming-guide
 
 ## Installation
 
 ```bash
 # Install from npm
 npm install -g @vention/vention-cli
+```
+
+Use either `vention` or `vn` as the command.
+
+## Quick start
 
-# Or install locally for development
-nx build vention-cli
-cd dist/projects/machine-code/apps/vention-cli
-npm link
+1) Open your design in MachineBuilder and select the MachineLogic tab (this makes your design active).
+2) Authenticate:
+```bash
+vention login
+```
+3) Pull your app locally (creates a folder named after the app):
+```bash
+vention pull
 ```
+4) Edit code in your IDE (e.g., update `main.py`, `project.json`).
+5) Push changes back to your active design:
+```bash
+vention push
+```
+6) In MachineBuilder, use the MachineLogic panel to run/simulate your updated app.
+
+## How it works
 
-## Usage
+- Active design: The CLI finds designs where the MachineLogic tab is open and connects to your active design.
+- App selection: When pulling/linking, choose one of the design’s MachineLogic Python apps.
+- Local state: The CLI writes `.machine-code-app-directory-info.json` at the project root to remember the selected design/app and environment.
+- File sync:
+  - Pull: Downloads the app’s source files and writes them to disk.
+  - Push: Serializes local files and uploads them to your active design.
+- Ignored items when pushing: `venv`, `node_modules`, `dist`, `build`, `__pycache__`, `*.egg-info`, `.machine-code-app-directory-info.json`.
 
-After installation, you can use either `vention` or `vn` as the command:
+## Commands
 
 ```bash
-# Show help
-vention --help
-# or
-vn --help
+vention --help          # Show help
+vention --version       # Show version
+```
 
-# Run the hello command
-vention hello
-# or
-vn hello
+- login: Authenticate and select environment
+```bash
+vention login
+# Choose environment:
+# - prod: most users
+# - demo: testing/sandboxes
+```
 
-# Show version
-vention --version
-# or
-vn --version
+- pull: Fetch a MachineLogic Python app from your active design into the current directory
+```bash
+vention pull
+# If the current folder isn’t linked yet, select a design (with MachineLogic open) and then an app.
+# If linked, the CLI updates the existing project in place.
 ```
 
-Both commands (`vention` and `vn`) do exactly the same thing - use whichever you prefer!
+- link: Link the current directory to a design + app without pulling files
+```bash
+vention link
+# Writes .machine-code-app-directory-info.json so future push/pull operations know what to target.
+```
+
+- push: Upload local changes from the linked directory to your active design
+```bash
+vention push
+# Requires the same design to be open in MachineBuilder (MachineLogic tab selected).
+```
+
+## Project metadata file
+
+The CLI stores link info in `.machine-code-app-directory-info.json` at the project root:
+```json
+{
+  "appName": "My App",
+  "designId": 12345,
+  "applicationId": "abcdef",
+  "uuid": "optional-app-uuid",
+  "environment": "prod",
+  "lastPulledAt": "2025-01-01T12:34:56.789Z",
+  "lastPushedAt": "2025-01-02T09:10:11.123Z"
+}
+```
+
+## Requirements and limitations
+
+- The MachineLogic tab must be open for the target design (the design must be active) when running pull or push.
+- Only MachineLogic Python apps are supported.
+- The CLI ignores common build artifacts and environments when pushing (see list above).
+- Session storage: Login data is saved to `~/.vention-cli-config.json`.
+
+## Typical workflow
+
+- Create your app in the web IDE first (MachineLogic Python).
+- Keep MachineBuilder open with the MachineLogic tab selected (design active).
+- Use `vention pull` to get the app locally, edit in your IDE, then `vention push` to update the running app in your active design.
+- Use the MachineLogic UI to run and test.
+
+For app structure, deployment, multi-process `project.json`, and HMI guidance see: https://docs.vention.io/docs/machinelogic-python-programming-guide
+
+## Troubleshooting
+
+- “Not logged in. Please run 'vention login' first.” → Run `vention login`.
+- “No active design found …” or “Please open the design and navigate to MachineLogic …” → Open your design in MachineBuilder and select the MachineLogic tab.
+- “This directory is not linked …” during push → Run `vention link` or pull the app first.
+- Push fails with auth errors → Re-run `vention login` (tokens may have expired).
+- Directory already exists when pulling → Either run pull inside the existing project directory or rename/delete the conflicting folder.