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.

A command-line tool that enables local development of MachineLogic Python applications with bidirectional sync between your IDE and MachineBuilder.

Table of Contents

• ✨ Features
• 🧠 Concepts & Overview
• ⚙️ Installation & Setup
  • Upgrade
• 🚀 Quickstart Tutorial
• 🛠 How-to Guides
• 📖 API Reference
• 🔍 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)

Install globally via npm:

The CLI is published on npm as @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 <claude-code|codex|cursor|copilot>] [--scope <user|project>]
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 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 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.