> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/a16z/jolt/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
cargo +nightly install --git https://github.com/a16z/jolt --force --bins jolt
```

Verify the installation:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
jolt build
```

For release builds with optimizations:

```bash theme={null}
jolt build --release
```

### Running on the Emulator

Execute a compiled guest binary on the Jolt emulator:

```bash theme={null}
jolt run target/riscv-guest/riscv64imac-unknown-none-elf/release/guest
```

## Environment Variables

The CLI respects several environment variables for configuration:

### Build Configuration

<ParamField path="JOLT_GUEST_OPT" type="string" default="3">
  Controls the optimization level for guest builds. Valid values: `0`, `1`, `2`, `3`, `s`, `z`.

  ```bash theme={null}
  JOLT_GUEST_OPT=s jolt build
  ```
</ParamField>

<ParamField path="JOLT_BACKTRACE" type="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

  ```bash theme={null}
  JOLT_BACKTRACE=1 cargo run --release
  ```
</ParamField>

### Emulator Configuration

<ParamField path="JOLT_EMU_PATH" type="path">
  Path to the `jolt-emu` binary. If not set, the CLI searches `PATH` and common locations.

  ```bash theme={null}
  export JOLT_EMU_PATH=/usr/local/bin/jolt-emu
  jolt run guest.elf
  ```
</ParamField>

### Logging

<ParamField path="RUST_LOG" type="string">
  Controls log level output. Set to `info`, `debug`, or `trace` for more verbose output.

  ```bash theme={null}
  RUST_LOG=info jolt build
  ```
</ParamField>

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

```bash theme={null}
jolt build
```

Target: `riscv64imac-unknown-none-elf`

### Std Mode

Builds with standard library support using musl libc:

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="jolt new" icon="folder-plus" href="/cli/new">
    Create new Jolt projects
  </Card>

  <Card title="jolt build" icon="hammer" href="/cli/build">
    Build guest programs with all options
  </Card>

  <Card title="jolt run" icon="play" href="/cli/run">
    Run binaries on the emulator
  </Card>
</CardGroup>