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
• 🧠 Concepts & Overview
• ⚙️ Installation & Setup
• 🚀 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
• 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, node_modules, dist, build, __pycache__, *.egg-info, .machine-code-app-directory-info.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 16 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.io/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

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 help for any command

vention --help
vention pull --help
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.

📖 API Reference

Global Options

vention --help          # Display help information
vention --version       # Display CLI version

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

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/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:

• 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

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

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 (e.g., prod, staging)
• lastPulledAt (ISO 8601 timestamp): Last successful pull time
• 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 …" (during push)

• Cause: The directory doesn't have .machine-code-app-directory-info.json
• Solution: Run vention link or vention pull to establish the link

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 or push 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, node_modules, dist, build, __pycache__, *.egg-info, and .machine-code-app-directory-info.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.