CLI Reference

The bloqade-bytecode CLI assembles, disassembles, and validates lane-move bytecode programs.

bloqade-bytecode <COMMAND>

Installation

Via the Python package (recommended)

The CLI is bundled in the bloqade-lanes Python wheel and placed on your PATH automatically:

pip install bloqade-lanes

After installation, bloqade-bytecode is available as a command.

Note: The CLI is only included in pre-built platform wheels, not in the source distribution (sdist). If no wheel is available for your platform, use the cargo install method instead.

From source (cargo)

Install the CLI directly from the repository using cargo:

cargo install --path crates/bloqade-lanes-bytecode-cli

This compiles the binary and places it in ~/.cargo/bin/, which is typically on your PATH. No Python installation is required.

Alternatively, build without installing:

just build-cli       # Output: target/release/bloqade-bytecode

The binary can be run in place (./target/release/bloqade-bytecode) or copied to a directory on your PATH.

Development install

For local development, this builds the CLI, stages it into the Python package, and installs everything:

just develop

Testing

just test-rust       # Run Rust tests (core + CLI crates)
just cli-smoke-test  # CLI bytecode validation tests

Commands

assemble

Assemble a text program (.sst) into binary format (.bin).

bloqade-bytecode assemble <INPUT> -o <OUTPUT>

Argument	Description
<INPUT>	Input text file (.sst)
-o, --output <OUTPUT>	Output binary file (required)

Example:

bloqade-bytecode assemble prog.sst -o prog.bin
# assembled 12 instructions -> prog.bin

---

disassemble

Disassemble a binary program (.bin) into human-readable text format.

bloqade-bytecode disassemble <INPUT> [-o <OUTPUT>]

Argument	Description
<INPUT>	Input binary file (.bin)
-o, --output <OUTPUT>	Output text file (omit to print to stdout)

Examples:

# Print to stdout
bloqade-bytecode disassemble prog.bin

# Write to file
bloqade-bytecode disassemble prog.bin -o prog.sst
# disassembled 12 instructions -> prog.sst

The conversion is semantically lossless: assembling and then disassembling a program preserves its instructions, and the disassembler’s canonical text output round-trips through text → binary → text.

---

validate

Validate a program for correctness. Accepts both text (.sst) and binary formats — the format is auto-detected from the file extension.

bloqade-bytecode validate <INPUT> [--arch <ARCH>] [--simulate-stack]

Argument	Description
<INPUT>	Input file (.sst = text, otherwise binary)
--arch <ARCH>	ArchSpec JSON file for address validation
--simulate-stack	Run stack type simulation (implied by --arch)

Validation levels:

Level	When	What it checks
Structural	Always	Arity bounds, initial_fill ordering
Address	--arch provided	Location, lane, zone, and bus validity against the architecture
Stack simulation	--simulate-stack or --arch provided	Type safety, stack balance, and (with an arch) the lane/location group checks — consistency, bus membership, AOD grid geometry

Examples:

# Structural validation only
bloqade-bytecode validate prog.sst
# valid (12 instructions)

# Full validation with architecture and stack simulation
bloqade-bytecode validate prog.sst --arch gemini-logical.json --simulate-stack
# valid (12 instructions)

# Validation failure
bloqade-bytecode validate bad.sst --arch gemini-logical.json
#   [0] initial_fill: invalid location address ...
# error: 1 validation error(s)

---

arch

Pretty-print an architecture specification.

bloqade-bytecode arch <INPUT>

Argument	Description
<INPUT>	ArchSpec JSON file

Example output:

ArchSpec v2.0

Words: 1 word(s), 5 sites/word
  Word 0: sites=[(0,0) (1,0) (2,0) (3,0) (4,0)]

Zones: 1 zone(s)
  Zone 0: 5x1 grid, 1 site bus(es), 0 word bus(es)
    Site bus 0: src=[SiteRef(0), SiteRef(1)] dst=[SiteRef(3), SiteRef(4)]
    words_with_site_buses: [0]
  modes: 1 mode(s)
    default: zones=[0]

Capabilities:
  feed_forward: false
  atom_reloading: false

The Paths section is only shown when the ArchSpec includes path data. Each path is identified by its 64-bit encoded lane address (in hex) and lists the AOD waypoints (physical coordinates) that define the transport trajectory.

arch validate

Validate an ArchSpec JSON file for internal consistency.

bloqade-bytecode arch validate <INPUT>

Argument	Description
<INPUT>	ArchSpec JSON file

Example:

bloqade-bytecode arch validate gemini-logical.json
# arch spec is valid: gemini-logical.json

---

File Formats

Extension	Format	Description
.sst	Text	Human-readable bytecode (one instruction per line, ; comments)
.bin	Binary	Compact binary encoding (BLQD magic header, 16 bytes per instruction)
.json	JSON	Architecture specification

See also the Instruction Quick Reference for a compact summary of all 24 instructions, or the full Instruction Set for encoding details.