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.

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

Delete the .machine-code-app-directory-info.json file
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.

Command Line Interface (CLI)

Table of Contents

✨ Features

🧠 Concepts & Overview

Active Design

Link State

File Synchronization

Authentication Flow

⚙️ Installation & Setup

🚀 Quickstart Tutorial

🛠 How-to Guides

Link an existing directory without pulling files

Update an already-linked app

Switch between different apps

View help for any command

Work with multiple environments

📖 API Reference

Global Options

vention login

vention pull

vention push

vention link

Link Metadata File

🔍 Troubleshooting & FAQ

Common Errors

FAQ

`vention login`

`vention pull`

`vention push`

`vention link`