CLI Reference

Romulan provides two interfaces: the standard workflow (build/upload flags) and the hardware subcommands (framed v1 protocol).

Standard workflow

uv run romulan [input] [--build] [--upload] [-o OUTPUT] [--port PORT]

Argument / Flag	Description	Default
input	Annotated hex dump file (required with --build)	—
--build	Build a .bin ROM image from the input file	—
--upload	Upload the ROM via the plain-text loadbin protocol	—
-o, --output	Output ROM binary path	bin/rom.bin
--port	Serial port (auto-detected if omitted)	auto-detect

At least one of --build or --upload is required.

Examples

# Build only
uv run romulan program.txt --build

# Build and upload
uv run romulan program.txt --build --upload

# Upload an existing binary
uv run romulan --upload

# Custom output path
uv run romulan program.txt --build -o output/rom.bin

Hardware subcommands

uv run romulan hardware <subcommand> [--port PORT] [--verbose]

Subcommand	Arguments	Description
upload	<bin_path>	Upload a ROM binary via the framed protocol
capture	--max-cycles N	Capture CPU bus cycles until STP or limit
monitor	--enable or --disable	Toggle ASCII monitor output
reset	--assert or --release	Hold or release CPU reset
request-addr	—	Read the current CPU address

Flag	Description
--verbose, -v	Print every JSON message sent and received

Examples

uv run romulan hardware upload bin/rom.bin --verbose
uv run romulan hardware capture --max-cycles 500
uv run romulan hardware reset --assert
uv run romulan hardware reset --release
uv run romulan hardware monitor --disable
uv run romulan hardware request-addr

Verbose output

When --verbose is set on a hardware command, each protocol exchange is logged to stderr:

[HW] Opened /dev/ttyACM0 @ 115200
[HW] CALL request_addr()
[HW] SEND: {"v":1,"cmd":"request_addr","id":"abc123"}
[HW] RECV: {"v":1,"ok":true,"addr":"8000"}
[HW] RET request_addr -> 32768

See Hardware API for protocol details.