CLI reference

Every sub-command of the fantasm CLI, generated directly from the Click definitions used by the binary so this page never goes stale. Use it as a lookup; for narrative shape (when to reach for which command), see Workflows.

The top-level fantasm group accepts the universal options below; each sub-command inherits them. Output-formatting options (--as, --report, --header, --detailed) come from asyoulikeit — see its documentation for the cross-cutting formatting controls.

fantasm

Fantasm — the Fantastic (dis-/re-)Assembly tools for 6502 code.

Usage

fantasm [OPTIONS] COMMAND [ARGS]...

Options

--version

Show the version and exit.

--project-root <project_root_dirpath>

Project root directory. Overrides FANTASM_PROJECT_ROOT. If neither is given, fantasm searches upwards from the current directory for a fantasm.toml.

Environment variables

FANTASM_PROJECT_ROOT

Provide a default for --project-root

addresses

Address translation across versions.

Usage

fantasm addresses [OPTIONS] COMMAND [ARGS]...

map

Map addresses from SOURCE_VERSION to TARGET_VERSION via opcode-level matching. With no –addr arguments, emits the full mapping (large for real binaries — pipe through –as tsv). With –addr, only the specified source addresses are mapped.

Usage

fantasm addresses map [OPTIONS] SOURCE_VERSION TARGET_VERSION

Options

--addr <addrs>

Source address to map (hex, with or without 0x/$/&). Repeatable.

--threshold <threshold>

Minimum anchored shared-block length (in opcodes) for a mapping to be emitted. Defaults to 5 to match fantasm backfill; lower deliberately when working with tiny binaries or fixtures.

Default:

5

--cpu <cpu>

CPU override; defaults to [binary] cpu (or “6502”).

--base-address, --rom-base <rom_base>

Load address; defaults to the target’s load address ([binary] base_address, or 0x8000, unless configured per target).

--include-supplementary, --primary-only

Include the seed-and-extend supplementary mappings (catches reordered blocks the LCS misses). –primary-only restricts to the LCS-derived mappings only.

Default:

True

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: map.

Options:

map

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

SOURCE_VERSION

Required argument

TARGET_VERSION

Required argument

annotations

Cross-version annotation diff and management.

Usage

fantasm annotations [OPTIONS] COMMAND [ARGS]...

diff

Diff annotations (comment / label / subroutine) between two versions’ driver scripts. Walks the version graph to map addresses across versions, then reports source-side annotations whose mapped target is missing, differs, or can’t be reached.

Usage

fantasm annotations diff [OPTIONS] SOURCE_VERSION TARGET_VERSION

Options

--source-driver <source_driver>

Override the auto-resolved source driver path.

--target-driver <target_driver>

Override the auto-resolved target driver path.

--threshold <threshold>

Minimum address-map confidence (block_length) for a comparison.

Default:

5

--cpu <cpu>

CPU override; defaults to [binary] cpu (or “6502”).

--base-address, --rom-base <rom_base>

Load address; defaults to the target’s load address ([binary] base_address, or 0x8000, unless configured per target).

--kind <kind>

Restrict to one or more annotation kinds. Repeatable.

Options:

comment | label | subroutine

--status <status>

Restrict to one or more diff statuses. Repeatable.

Options:

differs | missing_in_target | no_mapping

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: diffs.

Options:

diffs

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

SOURCE_VERSION

Required argument

TARGET_VERSION

Required argument

asm

Assembly-source extraction and inspection.

Usage

fantasm asm [OPTIONS] COMMAND [ARGS]...

extract

Extract a section of the target’s .asm file by address or label, with line numbers.

Usage

fantasm asm extract [OPTIONS] [TARGET] START_TARGET [END_TARGET]

Options

--window <window>

Default lines to capture when no end target is given.

Default:

40

Arguments

[TARGET]

Required argument

START_TARGET

Required argument

END_TARGET

Optional argument

audit

Subroutine annotation audit.

Usage

fantasm audit [OPTIONS] COMMAND [ARGS]...

detail

Show the full audit report for one subroutine.

Usage

fantasm audit detail [OPTIONS] [TARGET] TARGET

Options

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: branch_entries, called_by, escaping_branches, info.

Options:

branch_entries | called_by | escaping_branches | info

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

TARGET

Required argument

placeholders

List tracer-auto-discovered routines still carrying hex-tail placeholder names (e.g. .sub_cXXXX, .loop_cXXXX, .lXXXX, .cXXXX) in the asm output. Each one is a routine the disassembler traced via code-flow analysis but the driver script has not declared with a meaningful name; they’re invisible to audit summary because they never reach the JSON’s subroutines list. Exit code is non-zero only on argument / I/O errors — use the row count for CI gating.

Usage

fantasm audit placeholders [OPTIONS] [TARGET]

Options

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: placeholders.

Options:

placeholders

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

summary

List every subroutine with its computed flags.

Usage

fantasm audit summary [OPTIONS] [TARGET]

Options

--flag <flag>

Restrict to subroutines carrying this flag.

Options:

FALL_THROUGH | FALL_THROUGH_ENTRY | NO_REFS | BRANCH_ESCAPE | DATA_ONLY | AUTO_NAME | NO_DESCRIPTION

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: placeholders, summary.

Options:

placeholders | summary

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

undeclared

List JSR targets that lack subroutine() declarations.

Usage

fantasm audit undeclared [OPTIONS] [TARGET]

Options

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: undeclared.

Options:

undeclared

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

backfill

Propose annotation propagations from SOURCE_VERSION to TARGET_VERSION via the project’s version graph. Walks the shortest path between the two versions, builds a per-hop opcode-level confidence map, composes them with min-confidence, and reports source-driver annotations (comments / labels / subroutines) that map to target addresses above THRESHOLD and don’t conflict with annotations already in the target driver. First-pass output is report-only — copy the suggested lines into the target driver yourself.

Usage

fantasm backfill [OPTIONS] SOURCE_VERSION TARGET_VERSION

Options

--source-driver <source_driver>

Path to the source driver script. Defaults to the path computed from [versions] driver_dirname/driver_filename for the source version.

--target-driver <target_driver>

Path to the target driver script. Defaults to the path computed from [versions] driver_dirname/driver_filename for the target version.

--threshold <threshold>

Minimum composed block_length to accept a propagation.

Default:

5

--cpu <cpu>

CPU override; defaults to [binary] cpu (or “6502”).

--base-address, --rom-base <rom_base>

Load address; defaults to the target’s load address ([binary] base_address, or 0x8000, unless configured per target).

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: candidates.

Options:

candidates

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

SOURCE_VERSION

Required argument

TARGET_VERSION

Required argument

bytes

Byte-signature search across binaries.

Usage

fantasm bytes [OPTIONS] COMMAND [ARGS]...

find

Find every occurrence of HEX_SEQUENCE in the TARGET’s binary. The pattern is hex bytes optionally separated by spaces or $/0x prefixes; ‘??’ matches any single byte. With –cross VID, the same search runs against the named version too (repeatable) — useful for confirming a routine has moved or been removed in another release.

Usage

fantasm bytes find [OPTIONS] [TARGET] HEX_SEQUENCE

Options

--base-address, --rom-base <rom_base>

Load address; defaults to [binary] base_address (or [rom], or 0x8000).

--cross <TARGET>

Also search this target’s binary for the same pattern. Repeatable: ‘–cross 4.18 –cross 4.21’ searches both.

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: matches, summary.

Options:

matches | summary

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

HEX_SEQUENCE

Required argument

cfg

Inter-procedural call-graph queries.

Usage

fantasm cfg [OPTIONS] COMMAND [ARGS]...

blocks

Identify basic blocks within a target’s disassembly. Without –sub, surveys every subroutine. With –sub, shows only the named subroutine’s blocks. –uncommented-only filters to blocks with zero inline comments and at least two items, the typical annotation-gap-finding workflow.

Usage

fantasm cfg blocks [OPTIONS] [TARGET]

Options

--sub <sub_target>

Restrict to one subroutine (hex address or name).

--uncommented-only

Only show blocks with zero comments and >= 2 items.

--min-items <min_items>

Minimum item count for a block to be included.

Default:

2

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: blocks.

Options:

blocks

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

depth

List subroutines by call-graph depth (leaves first).

Usage

fantasm cfg depth [OPTIONS] [TARGET]

Options

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: depth.

Options:

depth

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

dot-call-graph

Emit the inter-procedural call graph as graphviz dot (or GraphML). Pipe into dot -Tpng / dot -Tsvg for an image, or use –render to do that in one step. Filters let you focus on a neighbourhood; the whole graph for a real program is usually too dense to read.

Usage

fantasm cfg dot-call-graph [OPTIONS] [TARGET]

Options

-f, --format <output_format>

Graph source format.

Default:

'dot'

Options:

dot | graphml

-o, --output <output_filepath>

Write source / rendered image to this file (default: stdout for source).

--render <render_format>

Shell out to dot and write a rendered image instead of source.

Options:

png | svg | pdf

-F, --focus <focus>

Centre on this subroutine (hex addr or name). Repeatable.

--depth <depth>

Neighbourhood radius (both ancestors and descendants).

--up-depth <up_depth>

Ancestor radius (callers of –focus). Overrides –depth.

--down-depth <down_depth>

Descendant radius (callees of –focus). Overrides –depth.

--exclude-external

Drop OS / external-entry nodes (those above the binary’s range).

--include-pattern <include_pattern>

Keep nodes whose name matches this regex.

--exclude-pattern <exclude_pattern>

Drop nodes whose name matches this regex.

--min-degree <min_degree>

Drop nodes whose total degree is below this threshold (focus exempt).

Default:

0

Arguments

[TARGET]

Required argument

dot-flow

Emit the basic-block control-flow graph for ONE subroutine as graphviz dot (or GraphML). Each block becomes a node listing its instructions; edges are coloured by exit kind (branch / fall / jump). Use –render to produce a png/svg/pdf in one step.

Usage

fantasm cfg dot-flow [OPTIONS] [TARGET] TARGET

Options

-f, --format <output_format>

Graph source format.

Default:

'dot'

Options:

dot | graphml

-o, --output <output_filepath>

Write source / rendered image to this file (default: stdout for source).

--render <render_format>

Shell out to dot and write a rendered image instead of source.

Options:

png | svg | pdf

Arguments

[TARGET]

Required argument

TARGET

Required argument

leaves

List leaf subroutines (no internal callees).

Usage

fantasm cfg leaves [OPTIONS] [TARGET]

Options

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: leaves.

Options:

leaves

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

roots

List root subroutines (in-degree 0, internal).

Usage

fantasm cfg roots [OPTIONS] [TARGET]

Options

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: roots.

Options:

roots

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

sub

Show callers and callees of one subroutine.

Usage

fantasm cfg sub [OPTIONS] [TARGET] TARGET

Options

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: callees, callers.

Options:

callees | callers

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

TARGET

Required argument

sub-context

Show calling-convention context for one subroutine: body lines, every call site with surrounding context, and every exit point. Complements cfg sub, which shows the call graph view.

Usage

fantasm cfg sub-context [OPTIONS] [TARGET] TARGET

Options

--body-window <body_window>

Lines of body to show.

Default:

20

--caller-context <caller_context>

Lines before each call site.

Default:

3

--after-context <after_context>

Lines after each call site.

Default:

2

--exit-context <exit_context>

Lines before each exit instruction.

Default:

3

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: body, call_sites, exits, info.

Options:

body | call_sites | exits | info

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

TARGET

Required argument

comments

Comment / annotation consistency checks.

Usage

fantasm comments [OPTIONS] COMMAND [ARGS]...

check

Run the comment-vs-code consistency checks against the target’s JSON output. When the target’s driver script is present, also flags inline comments keyed to an address inside an instruction or data item. When the version has parents in the version graph, also flags comments copied from a parent at the same numeric address onto a different instruction.

Usage

fantasm comments check [OPTIONS] [TARGET]

Options

--sub <sub_target>

Restrict to the subroutine starting at this hex address.

--strict

Exit non-zero if any HIGH-confidence finding is reported. Use as a CI gate: HIGH findings (wrong register / wrong branch target / wrong CR / wrong tube register / Markdown link inside a backtick code span / lo-hi byte of the wrong address / inline comment inside an instruction) almost certainly disagree with the code.

--parents, --no-parents

Compare against the version’s parents in the version graph (default on). –no-parents skips the comparison, which also skips building the parent-to-child address map.

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: findings.

Options:

findings

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

suggest

Generate pattern-based comment suggestions for uncommented code items. Combines generic 6502 instruction-pattern heuristics (PHA → ‘Save A on stack’, etc.) with project-specific workspace label hints from [comments.suggest.label_hints] in fantasm.toml. The rendered py_line column is paste-ready Python for the driver script.

Usage

fantasm comments suggest [OPTIONS] [TARGET]

Options

--start <start_addr>

Start address (hex, inclusive). Defaults to the start of the binary.

--end <end_addr>

End address (hex, exclusive). Defaults to the end of the binary.

--label-hint <extra_label_hints>

Add a label hint, format “PATTERN=description” (e.g. –label-hint “wksp_drive=current drive”). Merges with hints from fantasm.toml. Repeatable.

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: suggestions.

Options:

suggestions

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

compare

Compare two versions’ binaries at byte / opcode / full-instruction granularity and print a diff report.

Usage

fantasm compare [OPTIONS] VERSION_A VERSION_B

Options

--cpu <cpu>

CPU override; defaults to [binary] cpu (or “6502”).

--base-address, --rom-base <rom_base>

Load address; defaults to the target’s load address ([binary] base_address, or 0x8000, unless configured per target).

Arguments

VERSION_A

Required argument

VERSION_B

Required argument

context

Code context queries (depth, sub-context, uncommented gaps).

Usage

fantasm context [OPTIONS] COMMAND [ARGS]...

uncommented

Find subroutines below a comment-density threshold and report named callees + workspace label references. Useful for inferring the purpose of unannotated code from its relationships with already-understood code.

Usage

fantasm context uncommented [OPTIONS] [TARGET]

Options

--threshold-pct <threshold_pct>

Density threshold; subs at or above this are skipped.

Default:

30.0

--min-items <min_items>

Minimum code-item count for a sub to be considered.

Default:

20

--label-pattern <label_patterns>

Substring to match against item labels for the “workspace_refs” column. Repeatable. Common BBC patterns: wksp_, fsm_, zp_, nmi_.

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: uncommented.

Options:

uncommented

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

coverage

Report the disassembly’s inline-comment coverage as a single headline percentage (commented code items / total code items) plus the supporting counts. Pass –by page for a per-256-byte breakdown or –by sub for a per-subroutine breakdown.

Usage

fantasm coverage [OPTIONS] [TARGET]

Options

--by <group_by>

Group the breakdown by memory page (256 bytes) or by subroutine.

Options:

page | sub

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: groups, summary.

Options:

groups | summary

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

data

Data-declaration review (runs, heuristic reclassification).

Usage

fantasm data [OPTIONS] COMMAND [ARGS]...

classify

Apply heuristic classifiers (padding / string / hi_bytes_table / code) to runs of byte-typed data items, listing spans that might be reclassifiable as something more specific.

Usage

fantasm data classify [OPTIONS] [TARGET]

Options

--cpu <cpu>

CPU override; defaults to [binary] cpu in fantasm.toml (or “6502”).

--target-type <target_types>

Item types whose runs the classifiers will examine. Repeatable. Default: byte.

Options:

byte | word | string

--min-string <min_string>

Minimum length of a printable-ASCII run to flag as string.

Default:

4

--min-code <min_code>

Minimum length of a valid-opcode sweep to flag as code.

Default:

8

--min-padding <min_padding>

Minimum length of a repeating-pattern run to flag as padding.

Default:

4

--min-hi-bytes <min_hi_bytes>

Minimum length of a contiguous run of bytes in the project’s ROM-page range to flag as a high-byte address table. The range is derived from the JSON’s meta.load_addr / meta.end_addr.

Default:

8

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: candidates.

Options:

candidates

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

runs

List contiguous runs of same-type data items (byte / word / string), longest first. The default filter shows runs of at least 8 bytes; –min-bytes adjusts.

Usage

fantasm data runs [OPTIONS] [TARGET]

Options

--min-bytes <min_bytes>

Minimum byte length for a run to be reported.

Default:

8

--type <type_filters>

Restrict to one or more item types. Repeatable (–type byte –type word). Defaults to all three.

Options:

byte | word | string

--annotated, --unannotated

Show only annotated (label / inline comment) or only un-annotated runs. Default: show both.

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: runs.

Options:

runs

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

disassemble

Run the target’s disassembly driver script to (re-)generate the .asm and .json disassembly artefacts. The driver is run with FANTASM_TARGET, FANTASM_BINARY (and its FANTASM_ROM back-compat alias), FANTASM_IMAGES, FANTASM_ASM, FANTASM_JSON and FANTASM_OUTPUT_DIR describing the target’s configured paths.

Usage

fantasm disassemble [OPTIONS] [TARGET]

Arguments

[TARGET]

Required argument

driver

Driver-script housekeeping (sorting, formatting). Operates on the dasmos / py8dis Python driver files that produce a target’s disassembly output.

Usage

fantasm driver [OPTIONS] COMMAND [ARGS]...

sort

Sort the statements in DRIVER_FILEPATH into the canonical address order. Imports / Disassembler.create / d.load / d.add_move are pinned to the top by Python execution constraints; the render block (ir = d.disassemble() and everything after it, including a contiguous import sys directly above) is pinned to the bottom. Between them, use_environment calls cluster ahead of the address-keyed run; add_move floats to its dest range; hook_subroutine, format_hint, constant, and the address-keyed annotations (label / comment / subroutine / banner / entry / byte / word / string / expr / expr_label / rts_code_ptr) all sort by their literal first-arg address; for / if / while blocks anchor at their first iteration’s literal. Statement text is moved byte-for-byte; hex literals are not normalised.

Usage

fantasm driver sort [OPTIONS] DRIVER_FILEPATH

Options

-i, --in-place

Rewrite DRIVER_FILEPATH in place. Without this flag, the sorted text is printed to stdout.

--check

Don’t write anything. Exit 0 if the file is already sorted; exit 1 with a unified diff on stderr otherwise. Useful for pre-commit / CI.

Arguments

DRIVER_FILEPATH

Required argument

fingerprint

Fingerprint each block of a target’s binary and report any duplicate blocks (a quick cross-check for relocated code).

Usage

fantasm fingerprint [OPTIONS] [TARGET]

Options

--block-size <block_size>

Block size in bytes.

Default:

64

--cpu <cpu>

CPU override; defaults to [binary] cpu (or “6502”).

--base-address, --rom-base <rom_base>

Load address; defaults to the target’s load address ([binary] base_address, or 0x8000, unless configured per target).

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: duplicates.

Options:

duplicates

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

hooks

hook_subroutine() discovery and review. The hook_subroutine() name is shared between dasmos and py8dis driver APIs.

Usage

fantasm hooks [OPTIONS] COMMAND [ARGS]...

suggest

Find JSR targets that look like unhooked print-inline helpers (stringz / stringcr / stringhi). For each call site to a candidate target, the post-call pattern is checked: a string item followed by a byte run that decodes as valid 6502 code. Targets with multiple matching call sites are reported in a paste-ready hook_subroutine() form.

Usage

fantasm hooks suggest [OPTIONS] [TARGET]

Options

--cpu <cpu>

CPU override; defaults to [binary] cpu in fantasm.toml (or “6502”).

--min-call-sites <min_call_sites>

Minimum matching call sites to a target before it’s reported.

Default:

2

--min-resume-code-bytes <min_resume_code_bytes>

Minimum bytes of valid-6502 decode required after the post-JSR string item to count as the missing-hook signature.

Default:

4

--min-confidence <min_confidence>

Minimum (matching call sites / total call sites) ratio for a target to be reported. 1.0 means every call to the target matches the missing-hook pattern.

Default:

0.5

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: candidates, paste.

Options:

candidates | paste

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

info

Show the resolved project context.

Usage

fantasm info [OPTIONS]

Options

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: project.

Options:

project

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

labels

Auto-generated label classification and renaming.

Usage

fantasm labels [OPTIONS] COMMAND [ARGS]...

apply

Apply a renames TOML file to a disassembly driver script. The TOML file should declare a renames array of inline tables, each with addr (integer) and name (string).

Default (inline) mode rewrites each scattered label(0xXXXX, …) or d.label(0xXXXX, …) declaration in place wherever it sits in the driver, and errors if any requested address has no matching declaration. Pass –section for the legacy override-cluster behaviour that operates only on a # Code label renames block.

Pass –update-refs to also rewrite textual references to the old name in d.comment(”…”) arguments, description=”””…””” blocks, and Markdown [`name](address:…)` anchors. Other occurrences are left alone.

Writes the rewritten driver to stdout by default; pass –in-place or –output to write to a file.

Usage

fantasm labels apply [OPTIONS] DRIVER_FILEPATH RENAMES_FILEPATH

Options

--section

Use the legacy section-based rewrite that targets a # Code label renames block. Default is inline rewrite of scattered declarations.

--update-refs

Also rewrite textual references to the renamed labels in d.comment(”…”) args, description=”””…””” blocks, and Markdown [name](address:…) anchors. Inline mode only.

--in-place

Rewrite DRIVER_FILEPATH in place.

--output <output_filepath>

Write the rewritten driver to OUTPUT instead of stdout.

--dry-run

Show a unified diff of the changes without writing anything.

Arguments

DRIVER_FILEPATH

Required argument

RENAMES_FILEPATH

Required argument

classify

Classify auto-generated labels (c#### / l#### / loop_c#### / sub_c####) into categories: subroutine, shared_tail, data, internal_loop, internal_conditional.

Usage

fantasm labels classify [OPTIONS] [TARGET]

Options

--category <category>

Restrict to one category.

Options:

subroutine | shared_tail | data | internal_loop | internal_conditional

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: labels.

Options:

labels

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

list

Inventory every label declared in a target’s disassembly. By default shows name, address, source (driver vs env), length, inbound reference count, and — from dasmos >= 2.0 schema-v2 JSON — the direct vs indexing-base split of those references plus a code-item caveat flag. Filter with –match / –min-length / –max-length / –source / –index-base-only; sort with –sort / –reverse.

The Direct column counts plain lda addr references and Idx counts indexing-base lda addr,X references; a label whose references are exclusively indexing-base (Idx == Refs, Direct == 0) is a d.index_base() conversion candidate, listed on its own with –index-base-only. The Code column flags candidates whose address is a code item (a genuine entry point a loop happens to read as lda entry,X) so they can be excluded from conversion.

Usage

fantasm labels list [OPTIONS] [TARGET]

Options

--sort <sort_key>

Sort key.

Default:

'name'

Options:

name | addr | len | refs | direct | idx

--reverse

Reverse the sort order.

--min-length <min_length>

Only labels at least N characters long.

--max-length <max_length>

Only labels at most N characters long.

--match <match_pattern>

Only labels whose name matches this regular expression.

--source <source>

Restrict to driver-defined labels, environment-supplied constants, or both.

Default:

'all'

Options:

driver | env | all

--index-base-only

Only labels whose references are exclusively indexing-base accesses (lda addr,X / sta addr,Y) — the d.index_base() conversion candidates. Labels with no references are excluded.

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: labels.

Options:

labels

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

refs

Show the inbound reference sites for a single label, as a tree rooted at the label. Combines code-flow refs (items whose target is the label’s address) and data refs (table / pointer references). Exits with an error if the label is not declared in the version.

Usage

fantasm labels refs [OPTIONS] [TARGET] LABEL_NAME

Options

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: refs.

Options:

refs

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

LABEL_NAME

Required argument

lint

Validate that a driver script’s annotation addresses (comment / subroutine / label) all map to addresses present in the target’s disassembly output, its declared workspace regions, or its external_labels. DRIVER_FILEPATH defaults to the target’s own driver script.

Usage

fantasm lint [OPTIONS] [TARGET] [DRIVER_FILEPATH]

Options

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: broken_links, unmapped.

Options:

broken_links | unmapped

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

DRIVER_FILEPATH

Optional argument

project

Initialise and manage fantasm projects.

Usage

fantasm project [OPTIONS] COMMAND [ARGS]...

add

Add a target to the project. Without –binary, create a new version directory {versions}/{prefix}-{ID}/ with the configured binary subdirectory ([binary] dir, default rom/) and output/, ready for the binary bytes and disassembly artefacts. With –binary, append a [[targets]] entry to fantasm.toml naming the files where they already are.

Usage

fantasm project add [OPTIONS] ID

Options

--prefix <prefix>

Prefix to use for the new version directory. Defaults to the first prefix in [versions] prefixes.

--binary <PATH[@ADDR>

The program binary, optionally with its hexadecimal load address (e.g. disc/FS3@1900). Without @ADDR the load and exec addresses are read from the binary’s .inf sidecar.

--driver <driver_path>

Driver script path (default disasm_<id>.py).

--asm <asm_path>

Generated .asm path (default output/<id>.asm).

--json <json_path>

Generated .json path (default output/<id>.json).

--metadata <metadata_path>

Optional metadata JSON path (its docs list is linted).

Arguments

ID

Required argument

init

Initialise a fantasm project. With the default –layout versions, write fantasm.toml and create the versions directory. With –layout explicit, adopt an existing project as it stands: write fantasm.toml with a [[targets]] entry naming the binary (–binary), driver, .asm and .json where they already are, and create nothing else. Safe to run inside an existing repository: no existing files are touched apart from fantasm.toml.

Usage

fantasm project init [OPTIONS]

Options

--name <name>

Required Project name.

--layout <layout>

versions: one directory per version under the versions directory. explicit: a [[targets]] entry with the given paths.

Default:

'versions'

Options:

versions | explicit

--prefix <prefixes>

Version-directory name prefix. Repeat for multi-prefix projects (e.g. NFS’s anfs/nfs). Defaults to the project name when omitted.

--at <at_dirpath>

Project root directory. Created if absent.

Default:

PosixPath('.')

--cpu <cpu>

Default CPU for opcode decode: “6502” / “65c02”.

Default:

'6502'

--versions-dir <versions_dirname>

Subdirectory holding the version directories (versions layout).

Default:

'versions'

--target <target_id>

Target id for –layout explicit (default: the project name).

--binary <PATH[@ADDR>

The program binary, optionally with its hexadecimal load address (e.g. disc/FS3@1900). Without @ADDR the load and exec addresses are read from the binary’s .inf sidecar.

--driver <driver_path>

Driver script path (default disasm_<id>.py).

--asm <asm_path>

Generated .asm path (default output/<id>.asm).

--json <json_path>

Generated .json path (default output/<id>.json).

--metadata <metadata_path>

Optional metadata JSON path (its docs list is linted).

--force

Overwrite fantasm.toml if it already exists.

list

List the project’s targets: [[targets]] entries, versions named by [layout], and version directories.

Usage

fantasm project list [OPTIONS]

Options

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: targets.

Options:

targets

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

promote

Score labelled code items as candidates for promotion to entry()/subroutine() declarations.

Usage

fantasm promote [OPTIONS] [TARGET]

Options

--threshold <threshold>

Hide candidates below this score.

Default:

25

--show-all

Show every candidate regardless of score.

--not-declared

Hide labels already declared as entry/subroutine.

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: candidates.

Options:

candidates

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

[TARGET]

Required argument

shared

Find shared 6502 code fragments between a primary binary and one or more reference binaries. Specs use the form [label=]path@load-addr (e.g. nfs=path/to/nfs.rom@&8000).

Usage

fantasm shared [OPTIONS] PRIMARY REFERENCES...

Options

--min-len <min_len>

Minimum matching span length, in instructions.

Default:

8

--limit <limit>

Show at most N longest matches per reference.

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: matches.

Options:

matches

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

PRIMARY

Required argument

REFERENCES

Required argument(s)

sub

Subroutine workflow helpers.

Usage

fantasm sub [OPTIONS] COMMAND [ARGS]...

insert

Find where a new subroutine() declaration for ADDRESS belongs in the given driver script (address-sorted insertion).

Usage

fantasm sub insert [OPTIONS] DRIVER_FILEPATH ADDRESS

Options

--no-reports

Suppress all report output. The handler still runs (useful for action commands whose reports are incidental); only rendering is skipped. Mutually exclusive with –report and –all-reports.

--all-reports

Render every report the handler returns, regardless of the command’s default_reports. Useful for commands whose default is a subset (or silent) but where you want the full picture this time. Mutually exclusive with –report and –no-reports.

--report <report>

Report name(s) to display (can be specified multiple times). Shows all if omitted. Valid values: insert.

Options:

insert

--header, --no-header

Include column headers in output. Overrides each report’s default. Format-specific: TSV prefixes first cell with ‘#’, display omits headers/title/caption, JSON ignores this flag.

--detailed, --essential

Include detailed columns or only essential columns. Auto-detects based on output format if not specified.

--as <as_format>

Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.

Options:

display | json | tsv

Arguments

DRIVER_FILEPATH

Required argument

ADDRESS

Required argument

verify

Verify a disassembly round-trips: assemble its .asm and compare the bytes to the original binary. The assembler is beebasm unless fantasm.toml’s [verify] section configures another. TARGET may be omitted when the project has a single target or a [project] default_target. Pass –all to verify every target in the project.

Usage

fantasm verify [OPTIONS] [TARGET]

Options

--all

Verify every target in the project.

Arguments

[TARGET]

Optional argument