gasm-sdk/docs/cli.md

CLI Reference

Repository: sourcedock.dev/petrbalvin/gasm-devkit

gasm is a single binary with subcommands. Run gasm --help for an overview, or gasm <command> -h for a command's usage and flags.

Global Flags

Flag	Description
-h, --help	Show help
-V, --version	Print the version

gasm tokens <file>

Print the lexical token stream of FILE: position, token kind, and text, one token per line. FILE may be - to read standard input.

gasm parse <file>

Parse FILE and report syntax errors on stderr. On success, prints how many declarations and TEXT functions the file contains.

gasm fmt [-w] [path...]

Canonicalise the formatting of Plan 9 assembly sources: indentation, operand spacing, per-function mnemonic alignment, and blank-line layout.

Flag	Description
-w	Write result to the source file (default: print to stdout)

With no arguments, or with a directory argument, every .s file below it is reformatted in place and the names of changed files are listed (go fmt style). . and _ directories are skipped.

gasm lint <file...>

Run static checks and print diagnostics as file:line:col: severity: message [code]. Exit status is non-zero when an error-severity diagnostic is found.

Flag	Description
-disable	Comma-separated rule codes to disable

Rules: unknown-instruction, operand-count, undefined-label, duplicate-label, missing-ret, missing-textflag-include, abi-argsize, unreachable-code, register-clobber, funcdata-pcdata.

gasm asm [--format raw|elf|macho|goobj] [-p pkg] [-o out] <file>

Assemble FILE (amd64) to machine code.

Flag	Description
--format	Output format: raw (default), elf, macho, goobj
-p	Package path (required for --format goobj)
-o	Write output to file (default: hex dump to stdout)

gasm verify [flags] <file.s>

Assemble FILE, map it into executable memory, and run dynamic checks.

Flag	Description
--ground-truth	Compare machine code byte-for-byte against go tool asm
--fuzz	Differential fuzz: JIT both gasm and go-tool-asm, compare outputs
-n	Fuzz iterations per function (default: 1000)
--abi	Run ABI-checking calls (sentinel registers + red zone)
--profile	List basic-block structure per function
--smoke	Call each NOSPLIT function with zeroed args

The --fuzz mode runs each function in a subprocess; a partial function (e.g. a decoder that faults on malformed input) is reported as CRASH without killing the parent. Use --ground-truth for decoders.

gasm debug --func <name> <file.s>

Interactive debugger for JIT-assembled amd64 functions. Requires a compiled binary on $PATH (not go run).

Flag	Description
--func	Function to debug (required)

REPL commands:

Command	Description
break <label|addr>	Set a breakpoint
step [n]	Single-step n instructions
continue	Run until next breakpoint or exit
regs	Print general-purpose registers
x [addr] [len]	Hex-dump memory
labels	List function labels and offsets
quit	Kill the debuggee and exit

gasm lsp

Run the language server over standard input/output (JSON-RPC 2.0 with Content-Length framing). Point an LSP-capable editor at the binary and associate it with .s files. The target architecture is inferred from the file-name suffix (_amd64.s, _arm64.s, _riscv64.s, _loong64.s).

Provides: completion, hover, document symbols, diagnostics, and semantic-token highlighting.