Command Reference

ALY provides a comprehensive CLI for all HDL development tasks.

Command Overview

Figure 24 CLI Command Structure

Global Options

These options are available for all commands:

--help, -h          Show help message and exit

Use aly --help or aly <command> --help for detailed command options.

init

Initialize a new ALY project.

Usage:

aly init [OPTIONS] [PATH]

Arguments:

PATH	Directory to create project in (default: current directory)

Options:

-t, --template	Template to use (default: rv64i)
--toolchain	Default firmware toolchain (default: riscv64)
--list-templates	List available templates
--no-git	Skip git initialization
--var KEY=VALUE	Set template variable (can be used multiple times)
--template-dir PATH	Custom templates directory (default: built-in templates)

Examples:

# Create project in current directory
aly init

# Create project in specified directory
aly init my_project

# Use specific template
aly init my_soc -t rv64i

# List available templates
aly init --list-templates

# Pass template variables
aly init my_cpu --var language=verilog --var toolchain=riscv32

# Use custom templates directory
aly init my_project --template-dir /path/to/templates --template custom

sim

Run RTL simulation.

Usage:

aly sim [OPTIONS]

Options:

--tool	Simulator to use (xsim, verilator, questa, modelsim, iverilog)
--top	Top-level testbench module
--waves	Enable waveform dumping
--gui	Open simulator GUI
--plusargs	Pass plusarg to simulator (KEY=VALUE format)
--timeout	Simulation timeout in seconds
--show-log	Display simulation log output
--gtkwave	Launch GTKWave after simulation
--regress	Run all tests in regression mode
--suite	Run a specific test suite
--test	Run a specific testbench by name
-j, --jobs	Number of parallel jobs (default: 1)
--stop-on-fail	Stop on first test failure
--list	List available testbenches
--list-tags	List tests by tag
--list-suites	List test suites

Examples:

# Basic simulation
aly sim --top tb_counter

# With waveforms using Verilator
aly sim --top tb_alu --tool verilator --waves

# Run test suite
aly sim --suite regression

# Run all tests in parallel
aly sim --regress -j 4

# With plusargs
aly sim --top tb_cpu --plusargs FIRMWARE=boot.hex

# List available tests
aly sim --list

Figure 25 Simulation Flow

synth

Synthesize design for FPGA or ASIC.

Usage:

aly synth [OPTIONS]

Options:

--module	RTL module to synthesize
--tool	Synthesis tool (vivado, yosys)
--top	Top-level module name
--part	FPGA part number
--constraints	Constraint files
-j, --jobs	Number of parallel jobs
--report	Show synthesis reports

Examples:

# Synthesize with default tool
aly synth --module cpu_core --top cpu_top

# Synthesize for specific FPGA
aly synth --tool vivado --part xc7a100tcsg324-1

# Use Yosys for ASIC
aly synth --tool yosys --top my_design

# Show reports
aly synth --module cpu_core --report

lint

Run linting and static analysis.

Usage:

aly lint [OPTIONS] [FILES...]

Arguments:

FILES

Specific files to lint (optional)

Options:

--tool	Linter to use (verilator, slang). Default: verilator
-m, --module	Lint specific module (required when no files given)
--top	Top-level module name for linting context
--no-warnings	Suppress warnings (errors only)

Note

Either --module or specific files must be provided.

Examples:

# Lint specific module
aly lint --module alu

# Lint with slang linter
aly lint --module cpu_core --tool slang

# Lint specific files
aly lint rtl/cpu.sv rtl/alu.sv

# Errors only (no warnings)
aly lint --module alu --no-warnings

firmware

Build embedded firmware.

Usage:

aly firmware [BUILD_NAME] [OPTIONS]

Arguments:

BUILD_NAME

Firmware build name from manifest (optional)

Options:

-o, --output	Output directory
--toolchain	Override toolchain
--no-mem	Skip memory file generation
--mem-format	Memory file format (mem, hex, coe)
--word-width	Memory word width (8, 16, 32, 64)
--byte-order	Byte order (little, big)
--list	List available builds

Examples:

# Build all firmware
aly firmware

# Build specific target
aly firmware bootloader

# Build with specific output directory
aly firmware bootloader -o build/fw

# List available builds
aly firmware --list

# Build with custom memory format
aly firmware bootloader --mem-format hex --word-width 32

program (still under development)

Program FPGA device.

Usage:

aly program [OPTIONS]

Options:

-l, --list	List available programming targets
-t, --target	Target board/device name
-b, --bitstream	Path to bitstream file
--tool	Programming tool (vivado, openocd)
-f, --flash	Program to flash memory
-v, --verify	Verify after programming

Examples:

# Program default board
aly program

# Specific bitstream
aly program -b build/synth/fpga_top.bit

# Program to flash
aly program -b bitstream.bit --flash

# List available targets
aly program --list

config

Manage project configuration.

Usage:

aly config [SUBCOMMAND] [OPTIONS]

Subcommands:

show	Display current configuration
validate	Validate configuration files
get	Get specific config value
set	Set config value
edit	Open config file in editor
init	Initialize config file
list	List config files

Examples:

# Show all config
aly config show

# Validate config
aly config validate

# Get specific value
aly config get defaults.simulator

# Set value
aly config set defaults.simulator verilator

# Edit config file
aly config edit

# List config files
aly config list

rtl

RTL management commands.

Usage:

aly rtl [SUBCOMMAND] [OPTIONS]

Subcommands:

init	Initialize RTL manifest
add	Add files to module
list	List RTL modules
show	Show module details
packages	List package files

Examples:

# Initialize RTL manifest
aly rtl init

# List all modules
aly rtl list

# Show module details
aly rtl show cpu_core

# Add files to module
aly rtl add --module cpu_core rtl/cpu/*.sv

# List packages
aly rtl packages

ip

IP block management.

Usage:

aly ip [SUBCOMMAND] [OPTIONS]

Subcommands:

init	Initialize IP manifest
list	List available IP blocks
show	Show IP details
add	Add IP to project
remove	Remove IP from project
create	Create new IP block
package	Package IP for distribution
update	Update IP version

Examples:

# List available IP
aly ip list

# Show IP details
aly ip show uart

# Create new IP block
aly ip create my_uart

# Add existing IP
aly ip add vendor/uart

# Package IP
aly ip package uart

constraints

Manage design constraints.

Usage:

aly constraints [SUBCOMMAND] [OPTIONS]

Subcommands:

init	Initialize constraints configuration
list	List constraint sets
show	Show constraint set details
validate	Validate constraint files

Examples:

# List constraint sets
aly constraints list

# Show specific constraint set
aly constraints show arty_a7

# Validate constraints
aly constraints validate

Exit Codes

ALY uses standard exit codes:

Code	Meaning
0	Success
1	General error
2	Command line usage error
3	Configuration error
4	Build/compilation error
5	Test failure

Utility Commands

Additional utility commands:

info	Show project information
clean	Clean build artifacts
refresh	Refresh project cache
version	Show ALY version

Examples:

# Show project info
aly info

# Clean build directory
aly clean

# Show version
aly version

Next Steps

• Configuration - Configuration options

• API Reference - Python API

• Examples - Example workflows