--- title: "Command Line Interface (CLI)" slug: "command-line-interface-cli" updated: 2026-10-28T18:34:37Z published: 2026-10-28T18:34:37Z 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 > **⚠️ Upgrade required.** Vention CLI 0.37.0 or later is required to pull, push and read logs for your MachineLogic Python apps. Older versions report your design as not open. Run `npm install -g @vention/vention-cli@latest`, then `vention login`. See [Upgrade](/docs/command-line-interface-cli#upgrade). > A command-line tool that enables local development of MachineLogic Python applications with bidirectional sync between your IDE and MachineBuilder. --- ## Table of Contents - [✨ Features](/docs/command-line-interface-cli#-features) - [🧠 Concepts & Overview](/docs/command-line-interface-cli#-concepts--overview) - [⚙️ Installation & Setup](/docs/command-line-interface-cli#-installation--setup) - [Upgrade](/docs/command-line-interface-cli#upgrade) - [🚀 Quickstart Tutorial](/docs/command-line-interface-cli#-quickstart-tutorial) - [🛠 How-to Guides](/docs/command-line-interface-cli#-how-to-guides) - [📖 API Reference](/docs/command-line-interface-cli#-api-reference) - [🔍 Troubleshooting & FAQ](/docs/command-line-interface-cli#-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 - **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` ### Read-only Config & Scene Assets Every `vention pull` also writes two read-only reference files to the app directory, sourced from the active design: - `.vention-design-configuration.json`: the design's MachineMotion configuration - `.vention-design-scene-assets.json`: the design's library assets, if the design has a library (omitted otherwise) Both files are chmodded read-only (`0o444`) after writing, and are excluded from `push` via the ignored patterns above — they're a local snapshot for reference only, not something the CLI syncs back to MachineBuilder. ### 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 - Vention CLI 0.37.0 or later to pull, push and read logs for your MachineLogic Python apps (see [Upgrade](/docs/command-line-interface-cli#upgrade)) **Install globally via npm:** The CLI is published on npm as [`@vention/vention-cli`](https://www.npmjs.com/package/@vention/vention-cli). ``` npm install -g @vention/vention-cli ``` **Verify installation:** ``` vention --version ``` On Windows, if `vention` is not found after the install, the npm global folder is missing from your PATH. Add the folder `npm prefix -g` prints to your PATH and open a new terminal. Until then, `npx -y @vention/vention-cli <command>` runs the same commands. **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 ### Upgrade Install the latest version, check it, then log in again: ``` npm install -g @vention/vention-cli@latest vention --version vention login ``` `npm update -g` can leave you on an older version, because npm pins globally installed packages to a caret range. Always use the command above. --- ## 🚀 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 (the latter only when the design has scene assets) - 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 --- ### `vention skills` **Description:** Install the Vention skills for your coding agent, keep them up to date, and list the ones already installed. **Usage:** ``` vention skills install [--agent ] [--scope ] vention skills update vention skills status ``` **Behavior:** - `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` - `--scope` defaults to `user`; Codex always installs for your user account - `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 - `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 **Prerequisites:** - Node.js and npm, plus the agent's own CLI for Claude Code (2.1.277 or later) or Codex --- ### 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 allocations found …" or "Sorry, it seems you do not have that design open …"** - **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 **The same two messages although the design is open with the MachineLogic tab** - **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. - **Solution:** Run `vention --version`. Below 0.37.0, follow [Upgrade](/docs/command-line-interface-cli#upgrade) and retry. At 0.37.0 or later, contact Vention support with the output of the failing command run with `vention --verbose`. **"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: How do I check my CLI version and upgrade?** A: `vention --version` prints it. See [Upgrade](/docs/command-line-interface-cli#upgrade) for the one-line upgrade command. **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-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. **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.