--- title: "Command Line Interface (CLI)" slug: "command-line-interface-cli" updated: 2026-08-14T19:25:13Z published: 2026-08-14T19:25:13Z canonical: "docs.vention.com/command-line-interface-cli" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.vention.com/llms.txt > Use this file to discover all available pages before exploring further. # Command Line Interface (CLI) # Vention CLI > A command-line tool that enables local development of MachineLogic Python applications with bidirectional sync between your IDE and MachineBuilder. --- ## Table of Contents - [✨ Features](/technicaldocumentation/docs/command-line-interface-cli#%E2%9C%A8-features) - [🧠 Concepts & Overview](/technicaldocumentation/docs/command-line-interface-cli#%F0%9F%A7%A0-concepts-overview) - [⚙️ Installation & Setup](/technicaldocumentation/docs/command-line-interface-cli#%E2%9A%99%EF%B8%8F-installation-setup) - [🚀 Quickstart Tutorial](/technicaldocumentation/docs/command-line-interface-cli#%F0%9F%9A%80-quickstart-tutorial) - [🛠 How-to Guides](/technicaldocumentation/docs/command-line-interface-cli#%F0%9F%9B%A0-howto-guides) - [📖 API Reference](/technicaldocumentation/docs/command-line-interface-cli#%F0%9F%93%96-api-reference) - [🔍 Troubleshooting & FAQ](/technicaldocumentation/docs/command-line-interface-cli#%F0%9F%94%8D-troubleshooting-faq) ## ✨ Features - **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 --- ## 🧠 Concepts & Overview ### Active Design The Vention CLI connects to **active designs** — designs where you have the MachineLogic tab open in MachineBuilder. This active session enables the CLI to discover available designs and apps for sync operations. ### Link State When you pull or link an app, the CLI creates a `.machine-code-app-directory-info.json` file in your project root. This file maintains the connection between your local directory and a specific design/app combination, enabling seamless push/pull operations without re-selection. ### File Synchronization - **Pull**: Downloads the app's source files from MachineBuilder and writes them to your local directory - **Push**: Serializes local files and uploads them to the active design in MachineBuilder - **Design reference files**: Pull also writes read-only `.vention-design-configuration.json` and `.vention-design-scene-assets.json` files describing the design's configuration and scene assets — these are for reference only and are never pushed - **Ignored patterns**: `venv`, `.venv`, `node_modules`, `dist`, `build`, `__pycache__`, `*.egg-info`, `.machine-code-app-directory-info.json`, `.vention-design-configuration.json`, `.vention-design-scene-assets.json` ### Authentication Flow OAuth-based authentication opens a browser window for secure login. Session tokens are stored in `~/.vention-cli-config.json` for subsequent CLI operations. --- ## ⚙️ Installation & Setup **Requirements:** - Node.js 18 or higher - npm or yarn - Active MachineBuilder session with MachineLogic tab open **Install globally via npm:** ``` npm install -g @vention/vention-cli ``` **Verify installation:** ``` vention --version ``` **Command aliases:** Use either `vention` or `vn` as the command prefix. **Learn more about MachineLogic Python app structure:** https://docs.vention.com/docs/machinelogic-python-programming-guide --- ## 🚀 Quickstart Tutorial This tutorial shows the complete workflow from authentication to syncing your first app. **Step 1: Open your design** Open your design in MachineBuilder and select the **MachineLogic tab**. This activates the design for CLI access. **Step 2: Authenticate** ``` vention login ``` This opens a browser window for secure OAuth login. **Step 3: Pull your app locally** ``` vention pull ``` The CLI will: - Show available active designs - 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 (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`. **Step 5: Push changes back** ``` vention push ``` Your changes are now uploaded to MachineBuilder. **Step 6: Run in MachineBuilder** Use the MachineLogic panel in MachineBuilder to run and test your updated app. --- ## 🛠 How-to Guides ### Link an existing directory without pulling files If you already have the app files locally and just want to establish the link: ``` cd my-existing-app vention link ``` This writes `.machine-code-app-directory-info.json` without overwriting your files. ### Update an already-linked app If your directory is already linked, simply run pull again to update files in place: ``` vention pull ``` The CLI detects the existing link and updates the project without creating a new folder. ### Switch between different apps 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: ``` vention logs ``` This fetches the application's logs from the digital twin and prints them to your terminal. ### View help for any command ``` vention --help vention pull --help vention push --help ``` ### Work with multiple environments 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`. --- ## 📖 API Reference ### Global Options ``` vention --help # Display help information vention --version # Display CLI version vention --verbose # Enable verbose output for debugging (use with any command) ``` ### `vention login` **Description:** Authenticate with your Vention account using OAuth. **Usage:** ``` vention login ``` **Behavior:** - Opens a browser window for secure OAuth authentication - Stores session tokens in `~/.vention-cli-config.json` - Tokens persist across terminal sessions and are refreshed automatically **Exit codes:** - `0`: Authentication successful - `1`: Authentication failed or cancelled --- ### `vention pull` **Description:** Fetch a MachineLogic Python app from your active design into the current directory. **Usage:** ``` vention pull ``` **Behavior:** - 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 - Writes/updates `.machine-code-app-directory-info.json` - Updates `lastPulledAt` timestamp **Prerequisites:** - User must be logged in (`vention login`) - Target design must have MachineLogic tab open in MachineBuilder - Target app must be a MachineLogic Python app (code-free apps not supported) **Exit codes:** - `0`: Pull successful - `1`: Not logged in, no active design found, or pull failed --- ### `vention push` **Description:** Upload local changes from the linked directory to your active design. **Usage:** ``` 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:** - User must be logged in - The same design must be active in MachineBuilder (MachineLogic tab open) **Exit codes:** - `0`: Push successful, or push cancelled at the link prompt - `1`: Not logged in, design not active, or push failed --- ### `vention link` **Description:** Link the current directory to a design + app without pulling files. **Usage:** ``` vention link ``` **Behavior:** - Prompts for design and app selection - Writes `.machine-code-app-directory-info.json` with link metadata - Does not download or modify existing files **Use case:** Useful when you already have the app files and just want to establish the connection for push operations. **Exit codes:** - `0`: Link successful - `1`: Not logged in, no active design found, or link failed --- ### `vention logs` **Description:** Fetch application logs from the linked digital twin. **Usage:** ``` 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) **Schema:** ``` { "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" } ``` **Fields:** - `appName` (string): Human-readable app name - `designId` (number): Unique design identifier - `applicationId` (string): Unique application identifier - `uuid` (string, optional): App UUID if available - `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 --- ## 🔍 Troubleshooting & FAQ ### Common Errors **"Not logged in. Please run 'vention login' first."** - **Cause:** Authentication tokens not found or expired - **Solution:** Run `vention login` to re-authenticate **"No active design found …" or "Please open the design and navigate to MachineLogic …"** - **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 …"** - **Cause:** The directory doesn't have `.machine-code-app-directory-info.json` - **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 - **Solution:** Run `vention login` to refresh authentication **"Directory already exists" (during pull)** - **Cause:** A folder with the app name already exists - **Solution:** Either: - `cd` into the existing directory and run `vention pull` (updates in place) - Rename or delete the conflicting folder - Run `vention link` instead to link without creating a new folder ### FAQ **Q: Can I use this with code-free MachineLogic programs?** 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`, `push`, or `logs` commands. **Q: Where are my authentication tokens stored?** A: In `~/.vention-cli-config.json` in your home directory. **Q: Can I work on multiple apps simultaneously?** 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`, `.venv`, `node_modules`, `dist`, `build`, `__pycache__`, `*.egg-info`, `.machine-code-app-directory-info.json`, `.vention-design-configuration.json`, and `.vention-design-scene-assets.json`. **Q: Can I add custom ignore patterns?** A: Not currently. The ignore list is built into the CLI. **Q: What happens if I edit the same app in both MachineBuilder and locally?** A: The last push/pull wins. There's no conflict resolution or merging. We recommend using version control (Git) for your local copy. **Q: Does this work with MachineMotion apps?** A: The CLI specifically targets MachineLogic Python apps. For MachineMotion development, see the MachineMotion SDK documentation.