---
title: "Command Line Interface (CLI)"
slug: "command-line-interface-cli"
updated: 2025-10-29T00:13:47Z
published: 2025-10-29T00:13:47Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vention.io/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](/docs/command-line-interface-cli#-features)
- [🧠 Concepts & Overview](/docs/command-line-interface-cli#-concepts--overview)
- [⚙️ Installation & Setup](/docs/command-line-interface-cli#-installation--setup)
- [🚀 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
- **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.