Enum ExtendedCommands 

pub enum ExtendedCommands {
    Chat {

        file: PathBuf,
        temperature: f32,
        top_p: f32,
        max_tokens: usize,
        system: Option<String>,
        inspect: bool,
        no_gpu: bool,
        gpu: bool,
        trace: bool,
        trace_steps: Option<Vec<String>>,
        trace_verbose: bool,
        trace_output: Option<PathBuf>,
        trace_level: String,
        profile: bool,
    
},
    Bench {
        file: PathBuf,
        warmup: usize,
        iterations: usize,
        max_tokens: usize,
        prompt: Option<String>,
        fast: bool,
        brick: Option<String>,
    },
    Eval {
        file: PathBuf,
        dataset: String,
        text: Option<String>,
        max_tokens: usize,
        threshold: f32,
    },
    Profile {

        file: PathBuf,
        granular: bool,
        format: String,
        focus: Option<String>,
        detect_naive: bool,
        threshold: f64,
        compare_hf: Option<String>,
        energy: bool,
        perf_grade: bool,
        callgraph: bool,
        fail_on_naive: bool,
        output: Option<PathBuf>,
        ci: bool,
        assert_throughput: Option<f64>,
        assert_p99: Option<f64>,
        assert_p50: Option<f64>,
        warmup: usize,
        measure: usize,
        tokens: usize,
        ollama: bool,
        no_gpu: bool,
        compare: Option<PathBuf>,
    
},
    Qa {

        file: PathBuf,
        assert_tps: Option<f64>,
        assert_speedup: Option<f64>,
        assert_gpu_speedup: Option<f64>,
        skip_golden: bool,
        skip_throughput: bool,
        skip_ollama: bool,
        skip_gpu_speedup: bool,
        skip_contract: bool,
        skip_format_parity: bool,
        skip_ptx_parity: bool,
        safetensors_path: Option<PathBuf>,
        iterations: usize,
        warmup: usize,
        max_tokens: usize,
        json: bool,
        verbose: bool,
        min_executed: Option<usize>,
        previous_report: Option<PathBuf>,
        regression_threshold: Option<f64>,
        skip_gpu_state: bool,
        skip_metadata: bool,
        skip_capability: bool,
        assert_classifier_head: bool,
    
},
    Parity {
        file: PathBuf,
        prompt: String,
        assert: bool,
    },
    PtxMap {
        file: PathBuf,
        kernel: Option<String>,
        reverse: Option<String>,
        json: bool,
        verbose: bool,
        prefill: bool,
    },
    Ptx {
        file: Option<PathBuf>,
        kernel: Option<String>,
        strict: bool,
        bugs: bool,
        json: bool,
        verbose: bool,
    },
    Tune {
        file: Option<PathBuf>,
        method: String,
        rank: Option<u32>,
        vram: f64,
        plan: bool,
        model: Option<String>,
        freeze_base: bool,
        train_data: Option<PathBuf>,
        json: bool,
    },
    Monitor {
        dir: PathBuf,
        refresh_ms: u64,
        compact: bool,
    },
    Cbtop {

        model: Option<String>,
        attach: Option<String>,
        model_path: Option<PathBuf>,
        headless: bool,
        json: bool,
        output: Option<PathBuf>,
        ci: bool,
        throughput: Option<f64>,
        brick_score: Option<u32>,
        warmup: usize,
        iterations: usize,
        speculative: bool,
        speculation_k: usize,
        draft_model: Option<PathBuf>,
        concurrent: usize,
        simulated: bool,
    
},
    Probar {
        file: PathBuf,
        output: PathBuf,
        format: String,
        golden: Option<PathBuf>,
        layer: Option<String>,
    },
    CompareHf {
        file: PathBuf,
        hf: String,
        tensor: Option<String>,
        threshold: f64,
        json: bool,
    },
    Hex {

        file: PathBuf,
        tensor: Option<String>,
        limit: usize,
        stats: bool,
        list: bool,
        json: bool,
        header: bool,
        blocks: bool,
        distribution: bool,
        contract: bool,
        entropy: bool,
        raw: bool,
        offset: String,
        width: usize,
        slice: Option<String>,
    
},
    Tree {
        file: PathBuf,
        filter: Option<String>,
        format: String,
        sizes: bool,
        depth: Option<usize>,
    },
    Flow {
        file: PathBuf,
        layer: Option<String>,
        component: String,
        verbose: bool,
        json: bool,
    },
    Qualify {
        file: PathBuf,
        tier: String,
        timeout: u64,
        json: bool,
        verbose: bool,
        skip: Option<Vec<String>>,
    },
    Tools(ToolCommands),
}

Extended CLI commands (analysis, profiling, QA, benchmarks, and advanced tools).

Flattened into Commands via #[command(flatten)] so all subcommands remain top-level from the user’s perspective (e.g., apr chat, apr profile).

Variants

Chat

Interactive chat with language model

Fields

file: PathBuf

Path to .apr model file

temperature: f32

Sampling temperature (0 = greedy, higher = more random)

top_p: f32

Nucleus sampling threshold

max_tokens: usize

Maximum tokens to generate per response

system: Option<String>

System prompt to set model behavior

inspect: bool

Show inspection info (top-k probs, tokens/sec)

no_gpu: bool

Disable GPU acceleration (use CPU)

gpu: bool

Force GPU acceleration (requires CUDA)

trace: bool

Enable inference tracing (APR-TRACE-001)

trace_steps: Option<Vec<String>>

Trace specific steps only (comma-separated)

trace_verbose: bool

Verbose tracing

trace_output: Option<PathBuf>

Save trace output to JSON file

trace_level: String

Trace detail level (none, basic, layer, payload)

profile: bool

Enable inline Roofline profiling (PMAT-SHOWCASE-METHODOLOGY-001)

Bench

Benchmark throughput (spec H12: >= 10 tok/s)

Fields

file: PathBuf

Path to model file

warmup: usize

Number of warmup iterations

iterations: usize

Number of measurement iterations

max_tokens: usize

Max tokens to generate per iteration

prompt: Option<String>

Test prompt

fast: bool

Use realizar for fast inference (vs aprender baseline)

brick: Option<String>

Benchmark specific brick

Eval

Evaluate model perplexity (spec H13: PPL <= 20)

Fields

file: PathBuf

Path to model file

dataset: String

Dataset: wikitext-2, lambada, or custom

text: Option<String>

Custom text (when dataset=custom)

max_tokens: usize

Maximum tokens to evaluate

threshold: f32

Perplexity threshold for pass/fail

Profile

Deep profiling with Roofline analysis

Fields

file: PathBuf

Path to model file

granular: bool

Layer-by-layer granular analysis

format: String

Output format (human, json, flamegraph)

focus: Option<String>

Focus on specific operation

detect_naive: bool

Detect naive implementations

threshold: f64

GFLOPS threshold for naive detection

compare_hf: Option<String>

Compare against HuggingFace baseline

energy: bool

Measure energy consumption (requires RAPL)

perf_grade: bool

Compute performance grade (vs Ollama baseline)

callgraph: bool

Show call graph

fail_on_naive: bool

Exit non-zero if naive implementation detected

output: Option<PathBuf>

Output file path for flamegraph SVG (GH-174, PMAT-182)

ci: bool

Enable CI mode with assertion checks (exits 1 on failure)

assert_throughput: Option<f64>

Minimum throughput in tok/s (CI assertion, exits 1 if below)

assert_p99: Option<f64>

Maximum p99 latency in ms (CI assertion, exits 1 if above)

assert_p50: Option<f64>

Maximum p50 latency in ms (CI assertion, exits 1 if above)

warmup: usize

Warmup passes before measurement (default: 3)

measure: usize

Measurement passes (default: 10)

tokens: usize

Number of tokens to generate per measurement pass (default: 32)

ollama: bool

Compare against Ollama baseline (runs ollama for comparison)

no_gpu: bool

Disable GPU (force CPU-only profiling)

compare: Option<PathBuf>

Compare against another model format (F-PROFILE-011)

Qa

Falsifiable QA checklist for model releases

Fields

file: PathBuf

Path to model file

assert_tps: Option<f64>

Minimum throughput threshold in tok/s

assert_speedup: Option<f64>

Minimum speedup vs Ollama

assert_gpu_speedup: Option<f64>

Minimum GPU vs CPU speedup (F-PERF-042)

skip_golden: bool

Skip golden output test

skip_throughput: bool

Skip throughput benchmark

skip_ollama: bool

Skip Ollama parity comparison

skip_gpu_speedup: bool

Skip GPU vs CPU speedup test (F-PERF-042)

skip_contract: bool

Skip tensor contract validation (PMAT-235)

skip_format_parity: bool

Skip cross-format parity test (F-QUAL-032)

skip_ptx_parity: bool

Skip PTX parity validation (GH-219)

safetensors_path: Option<PathBuf>

SafeTensors model path for cross-format parity test (F-QUAL-032)

iterations: usize

Number of benchmark iterations

warmup: usize

Number of warmup iterations

max_tokens: usize

Maximum tokens to generate

json: bool

Output as JSON (for CI integration)

verbose: bool

Verbose output

min_executed: Option<usize>

Minimum number of gates that must execute (fail if fewer)

previous_report: Option<PathBuf>

Previous QA report for regression detection

regression_threshold: Option<f64>

Maximum allowed performance regression ratio (default: 0.10 = 10%)

skip_gpu_state: bool

Skip GPU state isolation test

skip_metadata: bool

Skip metadata plausibility validation (Bug 210, GH-222)

skip_capability: bool

Skip GPU capability match gate (GH-280)

assert_classifier_head: bool

Assert classifier head presence and shape (F-CLASS-004)

Parity

GPU/CPU parity check (PMAT-232: genchi genbutsu — see where GPU diverges)

Fields

file: PathBuf

Path to GGUF model file

prompt: String

Prompt text (default: “What is 2+2?”)

assert: bool

Assert parity (exit non-zero on divergence)

PtxMap

Model-to-PTX source mapping (Mieruka: make GPU kernel dispatch visible)

Fields

file: PathBuf

Path to GGUF model file

kernel: Option<String>

Filter to specific kernel (e.g., –kernel Q4KGemv)

reverse: Option<String>

Reverse lookup: kernel name -> which layers/steps use it

json: bool

Output as JSON

verbose: bool

Full PTX snippets and detailed analysis

prefill: bool

Show batched prefill kernel variants instead of decode

Ptx

PTX analysis and bug detection (trueno-explain: register pressure, roofline, 15+ bug detectors)

Fields

file: Option<PathBuf>

Path to a PTX source file

kernel: Option<String>

Analyze a named kernel from trueno-gpu

strict: bool

Strict mode (no performance whitelist)

bugs: bool

Show only bug analysis (skip register/memory/roofline)

json: bool

Output as JSON

verbose: bool

Verbose output (include PTX source listing)

Tune

ML tuning: LoRA/QLoRA configuration and memory planning (GH-176)

Fields

file: Option<PathBuf>

Path to model file (optional if using –model)

method: String

Tuning method: auto, full, lora, qlora

rank: Option<u32>

LoRA rank (default: auto-selected)

vram: f64

Available VRAM in GB

plan: bool

Only plan configuration, don’t train

model: Option<String>

Model size for planning (e.g., “7B”, “1.5B”)

freeze_base: bool

Freeze base model weights

train_data: Option<PathBuf>

Training data file (JSONL format)

json: bool

Output as JSON (for CI integration)

Monitor

Attach live TUI to a running training session

Fields

dir: PathBuf

Experiment output directory (same as finetune -o)

refresh_ms: u64

Refresh interval in milliseconds

compact: bool

Compact display mode

Cbtop

ComputeBrick pipeline monitor (cbtop)

Fields

model: Option<String>

Model name (e.g., qwen2.5-coder-1.5b)

attach: Option<String>

Attach to running realizar process

model_path: Option<PathBuf>

Path to GGUF model file for real profiling

headless: bool

Run in headless mode (no TUI, for CI/automation)

json: bool

Output JSON format (requires –headless)

output: Option<PathBuf>

Output file path (requires –headless)

ci: bool

CI mode: exit with code 1 if thresholds not met

throughput: Option<f64>

Minimum throughput threshold in tok/s (for –ci)

brick_score: Option<u32>

Minimum brick score threshold 0-100 (for –ci)

warmup: usize

Number of warmup iterations before measurement

iterations: usize

Number of measurement iterations

speculative: bool

PAR-100: Enable speculative decoding benchmark

speculation_k: usize

PAR-100: Number of tokens to draft speculatively (default: 4)

draft_model: Option<PathBuf>

PAR-099: Path to draft model for speculative decoding

concurrent: usize

PAR-102: Number of concurrent requests

simulated: bool

Use simulated data (for CI testing only)

Probar

Export for probar visual testing

Fields

file: PathBuf

Path to .apr model file

output: PathBuf

Output directory for test artifacts

format: String

Export format: json, png, or both

golden: Option<PathBuf>

Golden reference directory for comparison

layer: Option<String>

Filter layers by name pattern

CompareHf

Compare APR model against HuggingFace source

Fields

file: PathBuf

Path to .apr model file

hf: String

HuggingFace repo ID (e.g., openai/whisper-tiny)

tensor: Option<String>

Filter tensors by name pattern

threshold: f64

Comparison threshold (default: 1e-5)

json: bool

Output as JSON

Hex

Format-aware binary forensics (10X better than xxd)

Fields

file: PathBuf

Path to model file (APR, GGUF, or SafeTensors)

tensor: Option<String>

Filter tensors by name pattern

limit: usize

Limit bytes/values to display

stats: bool

Show tensor statistics

list: bool

List tensor names only

json: bool

Output as JSON

header: bool

Annotated file header (magic, version, tensor count, metadata)

blocks: bool

Q4K/Q6K/Q8_0 super-block structure with field annotations

distribution: bool

Value histogram + entropy + kurtosis analysis

contract: bool

Layout contract verification overlay per tensor

entropy: bool

Per-region byte entropy analysis

raw: bool

Raw bytes (like xxd but format-aware, with ASCII column)

offset: String

Start at byte offset (supports 0x prefix for hex)

width: usize

Bytes per row for raw output (default: 16)

slice: Option<String>

Slice range for partial tensor reads (e.g., 0:3 for first 3 elements)

Tree

Model architecture tree view

Fields

file: PathBuf

Path to .apr model file

filter: Option<String>

Filter by component pattern

format: String

Output format: ascii, dot, mermaid, json

sizes: bool

Show tensor sizes

depth: Option<usize>

Maximum tree depth

Flow

Data flow visualization

Fields

file: PathBuf

Path to .apr model file

layer: Option<String>

Filter by layer pattern

component: String

Component to visualize: full, encoder, decoder, etc.

verbose: bool

Verbose output with statistics

json: bool

Output as JSON

Qualify

Cross-subcommand smoke test (does every tool handle this model?)

Fields

file: PathBuf

Path to model file (APR, GGUF, or SafeTensors)

tier: String

Testing tier: smoke (Phase 1), standard (+contracts), full (+playbook)

timeout: u64

Timeout per gate in seconds

json: bool

Output as JSON

verbose: bool

Show subcommand output (disable stdout suppression)

skip: Option<Vec<String>>

Skip specific gates (comma-separated)

Tools(ToolCommands)

Publishing, conversion, and analysis tools

Trait Implementations

impl Debug for ExtendedCommands

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromArgMatches for ExtendedCommands

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut<'b>( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

impl Subcommand for ExtendedCommands

fn augment_subcommands<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate Self via FromArgMatches::from_arg_matches_mut

fn augment_subcommands_for_update<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate self via FromArgMatches::update_from_arg_matches_mut

fn has_subcommand(__clap_name: &str) -> bool

Test whether Self can parse a specific subcommand