CLI Overview

Overview of the Jolt CLI and common usage patterns

The Jolt CLI is the primary tool for working with the Jolt zkVM. It provides commands for creating projects, building guest programs, and running binaries on the Jolt emulator.

Installation

Install the Jolt CLI using cargo:

cargo +nightly install --git https://github.com/a16z/jolt --force --bins jolt

Verify the installation:

jolt --version

Available Commands

The Jolt CLI provides the following commands:

Command	Description
jolt new	Creates a new Jolt project with the specified name
jolt build	Build a guest program for Jolt zkVM
jolt run	Run an ELF binary on the Jolt emulator
jolt generate	Generate target specs or linker scripts
jolt build-wasm	Handles preprocessing and generates WASM compatible files

Common Workflows

Creating a New Project

Start by creating a new Jolt project:

jolt new my-project
cd my-project

This creates a workspace with:

• Host code in src/
• Guest code in guest/src/
• Pre-configured Cargo.toml files
• Rust toolchain configuration

Building Guest Programs

Build your guest program for the Jolt zkVM:

jolt build

For release builds with optimizations:

jolt build --release

Running on the Emulator

Execute a compiled guest binary on the Jolt emulator:

jolt run target/riscv-guest/riscv64imac-unknown-none-elf/release/guest

Environment Variables

The CLI respects several environment variables for configuration:

Build Configuration

JOLT_GUEST_OPT · string · default: "3"

Controls the optimization level for guest builds. Valid values: 0, 1, 2, 3, s, z.

JOLT_GUEST_OPT=s jolt build

JOLT_BACKTRACE · string

Enables backtrace support for guest panics. Preserves symbols in the ELF for debugging.

• 1 - Enable backtraces with function names and file:line info
• full - Include register snapshots and cycle counts per frame

JOLT_BACKTRACE=1 cargo run --release

Emulator Configuration

JOLT_EMU_PATH · path

Path to the jolt-emu binary. If not set, the CLI searches PATH and common locations.

export JOLT_EMU_PATH=/usr/local/bin/jolt-emu
jolt run guest.elf

Logging

RUST_LOG · string

Controls log level output. Set to info, debug, or trace for more verbose output.

RUST_LOG=info jolt build

Target Architecture

Jolt targets RISC-V 64-bit with the following extensions:

• RV64I - Base Integer Instruction Set
• M - Integer Multiplication and Division
• A - Atomic Instructions
• C - Compressed Instructions

The default target triple is riscv64imac-unknown-none-elf for no_std guests.

Build Modes

No-std Mode (Default)

Builds guest programs without the Rust standard library:

jolt build

Target: riscv64imac-unknown-none-elf

Std Mode

Builds with standard library support using musl libc:

jolt build --std

Target: riscv64imac-zero-linux-musl

This mode automatically installs or builds the required toolchain components (musl, gcc libs) if not already present.

Next Steps

jolt new

Create new Jolt projects

jolt build

Build guest programs with all options

jolt run

Run binaries on the emulator