⚡ Bolt CLI Installation & Setup Guide

⚡ Bolt CLI Wiki: Installation & Setup Guide

Welcome to the official installation guide for Bolt CLI — the universal, lightning-fast framework and build system for MIT App Inventor 2 extensions.

📑 Table of Contents

⚡ Bolt CLI Wiki: Installation & Setup Guide

📋 Prerequisites

Bolt CLI requires a Java Runtime Environment (JRE or JDK 11+, JDK 17 recommended) to execute.

Note

No Standalone javac or Android Studio Required! Bolt bundles its own Eclipse Compiler for Java (ecj.jar), Android SDK definitions (android.jar), D8 Dex compiler, and R8 toolchains. Any standard Java runtime (java) is sufficient to build extensions.

Verify your Java version:

java -version

If Java is not installed:

Windows: Download from Adoptium OpenJDK 17 or Microsoft OpenJDK.
Linux (Ubuntu/Debian): sudo apt update && sudo apt install -y openjdk-17-jdk
macOS: brew install openjdk@17
Android Termux: pkg install -y openjdk-17

⚙️🖥️ Manual Setup for Windows

Step 1: Download `bolt.zip`

Download the latest bolt.zip from the Bolt CLI GitHub Releases.

Step 2: Extract to Installation Directory

Create a folder named Bolt (e.g., C:\Bolt or %LOCALAPPDATA%\Bolt).
Extract the contents of bolt.zip into this folder.

Your folder structure should look like:

C:\Bolt\
├── bin\
│   ├── bolt.bat
│   ├── bolt
│   └── bolt.jar
├── libs\
│   ├── android.jar
│   └── tools\
└── icon.png

Step 3: Add to Environment Variables (PATH)

Option 1: Via Windows GUI

Press Win + R, type sysdm.cpl, and press Enter.
Go to the Advanced tab and click Environment Variables.
Under User variables (or System variables):
- (Optional) Click New, set Variable name: BOLT_HOME, Variable value: C:\Bolt.
- Select the Path variable and click Edit.
- Click New and add the path to the bin folder: C:\Bolt\bin.
Click OK on all dialogs to save changes.

Option 2: Via PowerShell

Run PowerShell as Administrator or standard user:

# Set BOLT_HOME
[Environment]::SetEnvironmentVariable("BOLT_HOME", "C:\Bolt", "User")

# Append bin folder to PATH
$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ($currentPath -notlike "*C:\Bolt\bin*") {
    [Environment]::SetEnvironmentVariable("Path", "$currentPath;C:\Bolt\bin", "User")
}

Step 4: Verify Installation

Open a new Command Prompt or PowerShell window and run:

bolt -v

You should see the installed Bolt CLI version and system information.

⚙️💻 Manual Setup for Linux & macOS

Step 1: Download and Extract

Open your terminal and run:

# Create directory
mkdir -p "$HOME/Bolt"

# Download the latest package
curl -L https://github.com/TechHamara/bolt-cli/releases/latest/download/bolt.zip -o "$HOME/Bolt/bolt.zip"

# Extract
unzip -o "$HOME/Bolt/bolt.zip" -d "$HOME/Bolt"
rm -f "$HOME/Bolt/bolt.zip"

Step 2: Clean Up Windows Batch File

Remove the Windows launcher script:

rm -f "$HOME/Bolt/bin/bolt.bat"

Step 3: Make Launcher Executable

chmod +x "$HOME/Bolt/bin/bolt"

Step 4: Configure Shell Profile (`.bashrc` or `.zshrc`)

Determine which shell you are using (echo $SHELL). If using Zsh (default on modern macOS), edit ~/.zshrc. If using Bash (default on Linux), edit ~/.bashrc.

For JDK 11 to 23:

Add the following lines to your profile:

# Bolt CLI Configuration
export BOLT_HOME="$HOME/Bolt"
export PATH="$PATH:$BOLT_HOME/bin"

bolt() {
    java -jar "$BOLT_HOME/bin/bolt.jar" "$@"
}

For JDK 24 and above:

JDK 24+ displays warnings on native access; add the --enable-native-access flag:

# Bolt CLI Configuration
export BOLT_HOME="$HOME/Bolt"
export PATH="$PATH:$BOLT_HOME/bin"

bolt() {
    java --enable-native-access=ALL-UNNAMED -jar "$BOLT_HOME/bin/bolt.jar" "$@"
}

Step 5: Reload Shell and Verify

source ~/.bashrc   # On Linux / Bash
# or
source ~/.zshrc    # On macOS / Zsh

bolt -v

⚙️📱 Setup Process for Android Termux

Compile extensions directly on your Android phone with zero computer requirement!

Step 1: Install Required Apps

Termux App: Download the latest release from Termux GitHub Releases (recommended: termux-app_v..._arm64-v8a.apk) or from F-Droid. (Do NOT install Termux from Google Play Store as that version is deprecated).
(Optional) MT Manager: Install MT Manager APK if you want a visual file manager for Android.

Step 2: Configure Termux Environment

Open the Termux app and execute the following commands:

# 1. Grant storage permissions (tap Allow on prompt)
termux-setup-storage

# 2. Upgrade Termux packages
pkg upgrade -y

# 3. Install OpenJDK 17, unzip, and curl
pkg install openjdk-17 unzip curl -y

Step 3: Extract Bolt CLI

Method A: Terminal Command (Recommended - Fast & Easy)

Run these commands inside Termux:

mkdir -p "$HOME/Bolt"
curl -L https://github.com/TechHamara/bolt-cli/releases/latest/download/bolt.zip -o "$HOME/Bolt/bolt.zip"
unzip -o "$HOME/Bolt/bolt.zip" -d "$HOME/Bolt"
rm -f "$HOME/Bolt/bolt.zip"
chmod +x "$HOME/Bolt/bin/bolt"

Method B: MT Manager GUI

Download bolt.zip using your Android mobile browser.
Open MT Manager.
Add Termux storage: Click menu -> Add local storage -> Navigate to /data/data/com.termux/files/home.
Create a folder named Bolt in Termux home.
Extract the downloaded bolt.zip inside $HOME/Bolt.
Delete bolt.bat from bin/.

Step 4: Configure `~/.bashrc`

In Termux, append the Bolt configuration to .bashrc:

cat << 'EOF' >> ~/.bashrc

# Bolt CLI Configuration
export BOLT_HOME="$HOME/Bolt"
export PATH="$PATH:$BOLT_HOME/bin"

bolt() {
    java -jar "$BOLT_HOME/bin/bolt.jar" "$@"
}
EOF

Step 5: Reload and Verify

Reload your environment or restart Termux:

source ~/.bashrc

bolt -v

You are all set! You can now create and compile extensions on Android.

🚀 Quick Automated Installers (One-Line Setup)

If you prefer an automated installation that handles downloading, extracting, and configuring environment variables automatically:

Windows (PowerShell)

iwr https://raw.githubusercontent.com/TechHamara/bolt-cli/main/scripts/install/install.ps1 -useb | iex

Linux & macOS (Terminal)

curl https://raw.githubusercontent.com/TechHamara/bolt-cli/main/scripts/install/install.sh -fsSL | sh

Android Termux

termux-setup-storage
curl https://raw.githubusercontent.com/TechHamara/bolt-cli/main/scripts/install/install-termux.sh -fsSL | bash

🧠 How It Works Under The Hood

Architecture Diagram

                        ┌───────────────────────────────┐
                        │   User Command (e.g. `bolt`)  │
                        └───────────────┬───────────────┘
                                        │
                         Executes launcher shell/batch
                                        │
                                        ▼
                        ┌───────────────────────────────┐
                        │ java -jar $BOLT_HOME/bin/...  │
                        └───────────────┬───────────────┘
                                        │
                                        ▼
       ┌─────────────────────────────────────────────────────────────────┐
       │                   BoltLocator Auto-Discovery                    │
       │  1. Check explicit $BOLT_HOME environment variable              │
       │  2. Dynamic codeSource reflection from active bolt.jar location  │
       │  3. Fallback to platform standard paths (%LOCALAPPDATA%/Bolt)   │
       └────────────────────────────────┬────────────────────────────────┘
                                        │
                                        ▼
       ┌─────────────────────────────────────────────────────────────────┐
       │                   In-Process Compiler Engine                    │
       │  • Eclipse Compiler for Java (ECJ) -> compiles Java source      │
       │  • Kotlin Compiler Embeddable      -> compiles Kotlin source    │
       │  • Android SDK (libs/android.jar)  -> type & component binding  │
       │  • D8 / Desugar Engine             -> generates classes.dex     │
       │  • Mini-NDK Toolchain              -> builds C/C++ native .so   │
       │  • In-Process ZIP Archive Engine   -> packages final .aix       │
       └─────────────────────────────────────────────────────────────────┘

Key Components

Dynamic BoltLocator Engine: Bolt does not hardcode filesystem paths. When bolt.jar is launched, BoltLocator dynamically resolves its root folder by checking parent directories or the BOLT_HOME environment variable. This allows Bolt to be placed in any directory or portable USB drive.
Embedded ECJ (Eclipse Compiler for Java): Instead of requiring a heavy external JDK compiler (javac), Bolt bundles ecj.jar inside libs/tools/. Java source code is compiled directly in-process within milliseconds.
Pure Universal Bytecode: Because the entire compilation pipeline is written in Kotlin and Java bytecode, it runs natively on ARM64 (mobile phones, Apple Silicon M1/M2/M3) and x86_64 without needing platform-specific binary recompilation.

🧪 Test Your First Extension Build

Once installed, test that everything works end-to-end:

Create a test extension:
```
bolt create HelloBolt
```
Select Java or Kotlin when prompted.
Navigate into the project:
```
cd HelloBolt
```
Build the extension:
```
bolt build
```
Result: Your compiled extension .aix will be available in the out/ folder:
```
out/
└── com.example.HelloBolt.aix
```

❓ Troubleshooting & FAQ

Q1: `command not found: bolt`

Cause: The bin directory is not added to your PATH, or you have not reloaded your shell.
Fix:
- On Windows: Verify that C:\Bolt\bin is present in your User Path. Restart Command Prompt.
- On Linux/macOS/Termux: Run source ~/.bashrc or source ~/.zshrc. Ensure export PATH="$PATH:$BOLT_HOME/bin" is in your profile.

Q2: `Permission denied: /.../bin/bolt`

Fix: Run chmod +x $HOME/Bolt/bin/bolt.

Q3: `java: command not found`

Fix: Java is not installed or not in your system PATH.
- Windows: Install Adoptium OpenJDK 17.
- Linux: sudo apt install -y openjdk-17-jdk
- Termux: pkg install openjdk-17 -y

Q4: Upgrading Bolt CLI

To update an existing installation:

bolt upgrade

Or simply download the newest bolt.zip and extract it over your existing Bolt folder.