gasm-sdk/docs/cli.md

# CLI Reference

Repository: [sourcedock.dev/petrbalvin/gasm-devkit](https://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.