@vention/vention-cli 0.29.3 → 0.29.4

package/README.md

@@ -18,6 +18,7 @@
 - **Local IDE development**: Edit MachineLogic Python apps in your preferred IDE with full tooling support
 - **Bidirectional sync**: Pull apps from MachineBuilder and push changes back seamlessly
 - **Active design detection**: Automatically finds and connects to designs with MachineLogic tab open
+- **Application logs**: Fetch your application's logs from the digital twin without leaving the terminal
 - **Smart file handling**: Automatically ignores build artifacts, virtual environments, and common development files
 - **Session management**: Persistent authentication with secure token storage
 - **Multiple apps support**: Link and switch between different apps within the same design
@@ -52,7 +53,7 @@ OAuth-based authentication opens a browser window for secure login. Session toke
 ## ⚙️ Installation & Setup
 
 **Requirements:**
-- Node.js 16 or higher
+- Node.js 18 or higher
 - npm or yarn
 - Active MachineBuilder session with MachineLogic tab open
 
@@ -96,7 +97,7 @@ The CLI will:
 - Let you select a design
 - Display MachineLogic Python apps in that design
 - Let you select an app to pull
-- Create a folder named after the app with all source files
+- Create a folder named after the app with all source files (special characters in the name are replaced with underscores)
 
 **Step 4: Edit locally**
 Open the created folder in your IDE and edit files like `main.py` or `project.json`.
@@ -142,6 +143,16 @@ To link your current directory to a different app:
 1. Delete the `.machine-code-app-directory-info.json` file
 2. Run `vention link` or `vention pull` and select the new app
 
+### View your application's logs
+
+If your directory is linked and the design is active in MachineBuilder:
+
+```bash
+vention logs
+```
+
+This fetches the application's logs from the digital twin and prints them to your terminal.
+
 ### View help for any command
 
 ```bash
@@ -152,7 +163,7 @@ vention push --help
 
 ### Work with multiple environments
 
-The CLI stores the environment (e.g., `prod`, `staging`) in the link metadata file. To switch environments, re-link to the desired environment.
+The CLI stores the environment (`local`, `demo`, or `prod`) in the link metadata file. The environment is set when you log in and defaults to `prod`.
 
 ---
 
@@ -163,6 +174,7 @@ The CLI stores the environment (e.g., `prod`, `staging`) in the link metadata fi
 ```bash
 vention --help          # Display help information
 vention --version       # Display CLI version
+vention --verbose       # Enable verbose output for debugging (use with any command)
 ```
 
 ### `vention login`
@@ -177,7 +189,7 @@ vention login
 **Behavior:**
 - Opens a browser window for secure OAuth authentication
 - Stores session tokens in `~/.vention-cli-config.json`
-- Tokens persist across terminal sessions
+- Tokens persist across terminal sessions and are refreshed automatically
 
 **Exit codes:**
 - `0`: Authentication successful
@@ -198,6 +210,7 @@ vention pull
 - If the directory is not linked: prompts for design and app selection, creates a new folder
 - If the directory is already linked: updates files in place using stored link metadata
 - Downloads all source files except ignored patterns
+- Writes read-only `.vention-design-configuration.json` and `.vention-design-scene-assets.json` reference files (the latter only when the design has scene assets)
 - Writes/updates `.machine-code-app-directory-info.json`
 - Updates `lastPulledAt` timestamp
 
@@ -222,19 +235,19 @@ vention push
 ```
 
 **Behavior:**
+- If the directory is not linked: offers to link it to an application and continue the push
 - Reads `.machine-code-app-directory-info.json` to identify target design/app
 - Serializes all local files except ignored patterns
 - Uploads to MachineBuilder
 - Updates `lastPushedAt` timestamp
 
 **Prerequisites:**
-- Directory must be linked (contains `.machine-code-app-directory-info.json`)
 - User must be logged in
 - The same design must be active in MachineBuilder (MachineLogic tab open)
 
 **Exit codes:**
-- `0`: Push successful
-- `1`: Not linked, not logged in, design not active, or push failed
+- `0`: Push successful, or push cancelled at the link prompt
+- `1`: Not logged in, design not active, or push failed
 
 ---
 
@@ -260,6 +273,31 @@ vention link
 
 ---
 
+### `vention logs`
+
+**Description:** Fetch application logs from the linked digital twin.
+
+**Usage:**
+```bash
+vention logs
+```
+
+**Behavior:**
+- Reads `.machine-code-app-directory-info.json` to identify the target design/app
+- Fetches the application's logs from the digital twin
+- Prints the logs to the terminal
+
+**Prerequisites:**
+- Directory must be linked (contains `.machine-code-app-directory-info.json`)
+- User must be logged in
+- The same design must be active in MachineBuilder (MachineLogic tab open)
+
+**Exit codes:**
+- `0`: Logs fetched successfully
+- `1`: Not linked, not logged in, design not active, or fetch failed
+
+---
+
 ### Link Metadata File
 
 **Location:** `.machine-code-app-directory-info.json` (project root)
@@ -282,8 +320,8 @@ vention link
 - `designId` (number): Unique design identifier
 - `applicationId` (string): Unique application identifier
 - `uuid` (string, optional): App UUID if available
-- `environment` (string): Target environment (e.g., `prod`, `staging`)
-- `lastPulledAt` (ISO 8601 timestamp): Last successful pull time
+- `environment` (string): Target environment (one of `local`, `demo`, `prod`)
+- `lastPulledAt` (ISO 8601 timestamp): Last successful pull time (also set when the directory is first linked)
 - `lastPushedAt` (ISO 8601 timestamp): Last successful push time
 
 ---
@@ -300,9 +338,9 @@ vention link
 - **Cause:** No designs have the MachineLogic tab open in MachineBuilder
 - **Solution:** Open your target design in MachineBuilder and click the MachineLogic tab to activate it
 
-**"This directory is not linked …" (during push)**
+**"This directory is not linked …"**
 - **Cause:** The directory doesn't have `.machine-code-app-directory-info.json`
-- **Solution:** Run `vention link` or `vention pull` to establish the link
+- **Solution:** Run `vention link` or `vention pull` to establish the link. During `push`, the CLI will offer to link the directory and continue automatically.
 
 **Push fails with authentication errors**
 - **Cause:** Session tokens expired
@@ -321,7 +359,7 @@ vention link
 A: No, only MachineLogic Python apps are supported.
 
 **Q: Do I need to keep MachineBuilder open while editing locally?**  
-A: No, you only need MachineBuilder open (with MachineLogic tab active) when running `pull` or `push` commands.
+A: No, you only need MachineBuilder open (with MachineLogic tab active) when running `pull`, `push`, or `logs` commands.
 
 **Q: Where are my authentication tokens stored?**  
 A: In `~/.vention-cli-config.json` in your home directory.
@@ -330,7 +368,7 @@ A: In `~/.vention-cli-config.json` in your home directory.
 A: Yes, each app folder maintains its own link metadata. You can have multiple linked directories.
 
 **Q: What files are ignored during push?**  
-A: `venv`, `node_modules`, `dist`, `build`, `__pycache__`, `*.egg-info`, `.machine-code-app-directory-info.json`, `.vention-design-scene-assets.json`, and `.vention-design-configuration.json`.
+A: `venv`, `.venv`, `node_modules`, `dist`, `build`, `__pycache__`, `*.egg-info`, `.machine-code-app-directory-info.json`, `.vention-design-scene-assets.json`, and `.vention-design-configuration.json`.
 
 **Q: Can I add custom ignore patterns?**  
 A: Not currently. The ignore list is built into the CLI.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vention/vention-cli",
-  "version": "0.29.3",
+  "version": "0.29.4",
   "description": "CLI tool for Vention applications",
   "type": "module",
   "engines": {