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,
        backend: BackendArg,
    
},
    Bench {
        file: PathBuf,
        warmup: usize,
        iterations: usize,
        max_tokens: usize,
        prompt: Option<String>,
        fast: bool,
        brick: Option<String>,
        percentiles: Vec<f64>,
    },
    Eval {

        file: PathBuf,
        dataset: String,
        text: Option<String>,
        max_tokens: usize,
        threshold: f32,
        task: Option<String>,
        data: Option<PathBuf>,
        model_size: Option<String>,
        num_classes: usize,
        generate_card: bool,
        device: String,
        samples: usize,
        temperature: 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,
        task: Option<String>,
        budget: usize,
        strategy: String,
        scheduler: String,
        scout: bool,
        data: Option<PathBuf>,
        num_classes: usize,
        model_size: Option<String>,
        from_scout: Option<PathBuf>,
        max_epochs: usize,
        time_limit: Option<String>,
    
},
    Monitor {
        dir: Option<PathBuf>,
        refresh_ms: u64,
        compact: bool,
        json: bool,
        format: String,
    },
    Runs {
        command: RunsCommands,
    },
    Experiment {
        command: ExperimentCommands,
    },
    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,
    
},
    Test {
        command: TestSubcommand,
    },
    CompareHf {
        file: PathBuf,
        hf: String,
        tensor: Option<String>,
        threshold: f64,
        json: bool,
    },
    Modelfile {
        command: ModelfileSubcommand,
    },
    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: TreeFormat,
        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>>,
    },
    Train {
        command: TrainCommands,
    },
    Pretrain {

        dataset: PathBuf,
        tokenizer: PathBuf,
        run_dir: PathBuf,
        mode: PretrainMode,
        lr: Option<f32>,
        num_steps: usize,
        warmup_steps: Option<usize>,
        batch_size: usize,
        seq_length: usize,
        steps_per_epoch: usize,
        seed: u64,
        target_val_loss: Option<f32>,
        vocab_size: u32,
        synthetic: bool,
        device: String,
        init: Option<PathBuf>,
        force_under_provisioned: bool,
        val_shard: Option<PathBuf>,
    
},
    Tokenize {
        command: TokenizeCommands,
    },
    Data {
        command: DataCommands,
    },
    Pipeline {
        command: PipelineCommands,
    },
    Diagnose {
        checkpoint_dir: PathBuf,
        data: Option<PathBuf>,
        model_size: Option<String>,
        num_classes: usize,
    },
    OllamaChatLint {
        response_file: PathBuf,
        stream: bool,
    },
    OllamaToolsLint {
        response_file: PathBuf,
        request_file: Option<PathBuf>,
        stream: bool,
    },
    DrySamplingLint {
        observation_file: PathBuf,
    },
    AwqLint {
        observation_file: PathBuf,
    },
    Fp8Lint {
        observation_file: PathBuf,
    },
    Nf4Lint {
        observation_file: PathBuf,
    },
    GptqLint {
        observation_file: PathBuf,
    },
    OomLint {
        report_file: PathBuf,
        stderr_file: Option<PathBuf>,
    },
    NcclDiagLint {
        diag_file: PathBuf,
        exit_code: Option<i32>,
        require_doc_link: bool,
    },
    ReactTraceLint {
        trace_file: PathBuf,
        max_iterations: Option<i64>,
        require_grammar: bool,
    },
    HangTraceLint {
        trace_dir: PathBuf,
        mode: String,
        world_size: usize,
        exit_code: Option<i32>,
        expected_exit_code: Option<i32>,
    },
    DdpMetricsLint {
        metrics_1gpu_file: PathBuf,
        metrics_ngpu_file: PathBuf,
        world_size: i64,
        scaling_floor: f64,
        loss_tolerance: f64,
    },
    Dataset {
        command: DatasetCommands,
    },
    Kernel {
        command: KernelCommands,
    },
    AudioInspectLint {
        json_file: PathBuf,
        expected_sample_rate: Option<u32>,
        expected_channels: Option<u32>,
    },
    AttnParityLint {
        parity_file: Option<PathBuf>,
        provenance_file: Option<PathBuf>,
        head_dim_error_file: Option<PathBuf>,
        tol_abs: f64,
        tol_cos: f64,
    },
    AttnVizLint {
        attn_file: Option<PathBuf>,
        html_file: Option<PathBuf>,
        expected_heatmaps: usize,
        tolerance: f64,
        epsilon: f64,
    },
    CheckFiniteLint {
        error_file: Option<PathBuf>,
        list_file: Option<PathBuf>,
        min_layers: usize,
    },
    EmbedVizLint {
        csv_file: PathBuf,
        expected_vocab_size: Option<usize>,
        csv_file_b: Option<PathBuf>,
    },
    ExplainTokenLint {
        jsonl_file: PathBuf,
        tolerance: f64,
        require_greedy: bool,
    },
    GpuMemtraceLint {
        trace_file: PathBuf,
    },
    KvTimelineLint {
        timeline_file: PathBuf,
        preempt_threshold: f64,
    },
    OtlpLint {
        otlp_file: PathBuf,
        require_apr_span: bool,
        require_genai_attrs: bool,
        expect_trace_id: Option<String>,
    },
    PrometheusLint {
        metrics_file: PathBuf,
        content_type: Option<String>,
        require_k07_metrics: bool,
    },
    ToolUseLint {
        observation_file: PathBuf,
    },
    GbnfLint {
        observation_file: PathBuf,
    },
    TypicalPLint {
        observation_file: PathBuf,
    },
    GradNorm {
        history_file: PathBuf,
        max_grad_norm: Option<f64>,
        spike_window: usize,
        spike_multiplier: f64,
    },
    RegistryQuotaLint {
        observation_file: PathBuf,
    },
    ImatrixLint {
        observation_file: PathBuf,
    },
    EmbeddingsLint {
        observation_file: PathBuf,
    },
    UnifiedSearchLint {
        observation_file: PathBuf,
    },
    RmGcLint {
        observation_file: PathBuf,
    },
    SharedCacheLint {
        observation_file: PathBuf,
    },
    Ppl {
        log_probs_file: PathBuf,
    },
    QuantPreservationLint {
        reference: PathBuf,
        requant: PathBuf,
    },
    Shard {
        file: PathBuf,
        max_shard_size: String,
        output: PathBuf,
        force: bool,
    },
    Unshard {
        input: PathBuf,
        output: PathBuf,
        force: bool,
    },
    Tools(ToolCommands),
    Rerank {

        model: PathBuf,
        input_ids: Option<String>,
        token_type_ids: Option<String>,
        query: Option<String>,
        passage: Option<String>,
        passages: Vec<String>,
        sort: bool,
        top_k: usize,
        vocab: Option<PathBuf>,
        hidden_dim: usize,
        num_layers: usize,
        num_heads: usize,
        intermediate_dim: usize,
        vocab_size: usize,
        max_position_embeddings: usize,
        type_vocab_size: usize,
        num_labels: usize,
        with_pooler: bool,
        raw_logit: bool,
        json: bool,
    
},
    Embed {

        model: PathBuf,
        text: Vec<String>,
        text_file: Option<PathBuf>,
        vocab: PathBuf,
        pool: String,
        normalize: bool,
        hidden_dim: usize,
        num_layers: usize,
        num_heads: usize,
        intermediate_dim: usize,
        vocab_size: usize,
        max_position_embeddings: usize,
        type_vocab_size: usize,
        json: bool,
    
},
}

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)

backend: BackendArg

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

percentiles: Vec<f64>

Comma-separated latency percentile points for JSON output (CRUX-E-07). Default: 50,95,99. Values must be in (0, 100].

Eval

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

Fields

file: PathBuf

Path to model file or checkpoint directory

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

task: Option<String>

Task type: omit for perplexity, “classify” for classification eval

data: Option<PathBuf>

Test data file (JSONL) for classification evaluation

model_size: Option<String>

Model size hint: “0.5B”, “tiny” (for classification eval)

num_classes: usize

Number of output classes (default: 5)

generate_card: bool

Generate HuggingFace model card (README.md) in checkpoint dir

device: String

Device for inference: “cpu” (default) or “cuda” (GPU-accelerated, ALB-089). Applies to –task humaneval/mbpp; perplexity evaluation is CPU-only.

samples: usize

Number of samples per problem for pass@k (ALB-088, default: 1)

temperature: f32

Sampling temperature (0.0 = greedy, 0.8 = standard for pass@k>1)

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

Achieved-GFLOPS floor below which the run is reported as naive

compare_hf: Option<String>

[NOT IMPLEMENTED — accepted and ignored] Compare against HuggingFace baseline

energy: bool

[NOT IMPLEMENTED — accepted and ignored] Measure energy consumption (requires RAPL)

perf_grade: bool

Compute performance grade (vs Ollama baseline)

callgraph: bool

[NOT IMPLEMENTED — accepted and ignored] Show call graph

fail_on_naive: bool

Exit non-zero if naive implementation detected (implies –detect-naive)

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

Tokens generated per measurement pass — GPU and –ollama paths only; the CPU per-operation profiler measures one forward pass per pass

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 (register pressure, roofline)

#2399 finding 1: on a build without the analyzer this line is the only thing a user sees before running the command, so it has to say so.

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, memory planning, and HPO (GH-176, SPEC-TUNE-2026-001)

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)

task: Option<String>

Task type for HPO: classify (SPEC-TUNE-2026-001)

budget: usize

Number of HPO trials (default: 10)

strategy: String

HPO search strategy: tpe, grid, random

scheduler: String

HPO scheduler: asha, median, none

scout: bool

Scout mode: 1 epoch per trial for fast exploration

data: Option<PathBuf>

Training data file for HPO (JSONL format)

num_classes: usize

Number of output classes for classification

model_size: Option<String>

Model size hint for HPO (e.g., “0.5B”, “1.5B”)

from_scout: Option<PathBuf>

Warm-start from scout phase results directory

max_epochs: usize

Maximum epochs per trial (full mode, default: 20)

time_limit: Option<String>

Maximum wall-clock time (e.g., “8h”, “30m”)

Monitor

Attach live TUI to a running training session

Fields

dir: Option<PathBuf>

Experiment output directory (same as finetune -o)

refresh_ms: u64

Refresh interval in milliseconds

compact: bool

Compact display mode

json: bool

Output JSON lines instead of TUI (for LLM agents and CI)

format: String

Output format: tui (default), json, text

Runs

List, show, and compare training experiment runs

Fields

command: RunsCommands

Experiment

Interactive experiment browser (TUI with loss curves)

Fields

command: ExperimentCommands

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 non-zero if thresholds are not met or the report status is FAIL

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 (must be >= 1)

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)

Test

Test harness for web, LLM, media and replay — powered by probador.

Named for what it tests, not for the act of testing. probar is Spanish for “to try”; it named the VERB, so apr probar --help told a reader nothing about the subject. This follows the precedent already set by apr data (“Data quality pipeline … powered by alimentar”): a plain noun for the user-facing command, the Spanish name kept for the engine and credited in the description.

The harness covers four distinct things, and the subcommands group by what is UNDER TEST rather than by verb:

web the WASM/browser build and its runtime behaviour (serve, build, watch, comply, stress) llm inference correctness, throughput and cost against an endpoint (test, load, bench, sweep, score, experiment, data-audit) media rendered output against ground truth (av-sync, audio, video, animation) replay the runner itself — recording, state machines, reporting (record, playbook, coverage, report)

Only tensor is routed today (PMAT-481 visual regression); the rest land as they are delegated to the probador library. Renaming now costs one path — after those land it is a breaking change across the whole testing surface.

apr probar stays as a hidden alias so existing scripts keep working.

Fields

command: TestSubcommand

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

Modelfile

CRUX-K-11: parse Ollama-style Modelfile DSL into apr config.

Fields

command: ModelfileSubcommand

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: TreeFormat

Output format: ascii, dot, mermaid, json

#2394 finding 15: this was a String that the dispatcher parsed with .unwrap_or(TreeFormat::Ascii), so --format bogusvalue silently rendered ascii and exited 0 — a typo’d --format josn in a pipeline produced a tree instead of JSON, with no warning. Parsing at the CLI boundary makes the unparseable value unrepresentable downstream: clap rejects it before any command runs.

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)

Train

Training pipeline (plan/apply) — forjar-style pre-flight validation

Fields

command: TrainCommands

Pretrain

Pretraining loop driver (SHIP-TWO-001 MODEL-2).

Wires the pretraining loop shape defined by contracts/training-loop-pretrain-v1.yaml. Executes a synthetic decreasing-loss drive by default so GATE-TRAIN-005 / -007 / -008 divergence-and-NaN guards can be exercised without an actual 370M compute run. Real corpus wiring is a follow-up ticket.

Fields

dataset: PathBuf

Dataset path (tokenized shard index or raw corpus).

tokenizer: PathBuf

Tokenizer directory (vocab.json + merges.txt).

run_dir: PathBuf

Run output directory — checkpoints + metadata go to {run_dir}/ckpt/.

mode: PretrainMode

Training regime — finetune (MODEL-1) or from-scratch (MODEL-2 cold start). Per contract training-loop-pretrain-v1 §hyperparameter_defaults, this atomically flips (regime, lr_max, warmup_steps, target_val_loss) unless explicit –lr / –warmup-steps / –target-val-loss override.

lr: Option<f32>

Peak learning rate after warmup. Omit to inherit mode default (finetune: 5e-5, from-scratch: 3e-4).

num_steps: usize

Warmup + cosine decay total steps.

warmup_steps: Option<usize>

Number of warmup steps. Omit to inherit mode default (finetune: 100, from-scratch: 1000).

batch_size: usize

Micro-batch size.

seq_length: usize

Sequence length per example.

steps_per_epoch: usize

Steps per epoch — controls per-epoch artifact cadence.

seed: u64

GATE-TRAIN-006 fixed RNG seed.

target_val_loss: Option<f32>

Target val_loss. Omit to inherit mode default (finetune: 2.2, from-scratch: 3.0).

vocab_size: u32

Vocabulary size (required for --mode from-scratch INV-TRAIN-005 regime-dependent cap: 2·ln(vocab_size)). MODEL-2 uses 50257.

synthetic: bool

Synthetic-drive only — do not attempt real compute, exercise loop gates only. INV-TRAIN-010: absent = real compute (drive_real), present = synthetic (drive_synthetic).

device: String

Training backend. Grammar (contract gpu-training-backend-v1 INV-GPUTRAIN-001): ^(cpu|cuda(:[0-9]|:1[0-5])?|auto)$. Default auto uses CUDA if available, else CPU (the only spelling that may fall back silently — all other values hard-fail on missing runtime per GATE-GPUTRAIN-002).

init: Option<PathBuf>

Initial weights from a pretrained APR file (contract apr-pretrain-from-init-v1). Per spec §49’s MODEL-2 pretrained-init pivot: when present, load weights from <PATH> instead of random-init. Composes with --mode finetune (canonical) or --mode from-scratch (allowed but non-canonical — emits a warning). Missing, corrupted, or arch-mismatched APR files exit non-zero before step 1 (no silent random-init fallback).

force_under_provisioned: bool

SPEC §83 P0-J: bypass the Chinchilla compute-optimal hard gate (chinchilla-gate-v1). Default is fail-fast when D/N < 10× (severely under-provisioned per Hoffmann et al. 2022). Pass this flag to acknowledge the under-provisioning and proceed anyway (e.g. for ablation studies, resumed runs, or smoke tests).

val_shard: Option<PathBuf>

SPEC §84 P2-F: shared held-out validation shard.

When provided, the val-loss eval reads HELD_OUT_BATCHES batches from this separate .bin-shards directory instead of stealing the first 16 batches of --dataset. This makes val_loss comparable across runs whose --dataset composition changes (P2-C’s audit-falsified result was confounded by val sets being drawn from different corpus distributions — qwen-v2 = codeparrot only, qwen-v3 = codeparrot + the-stack-dedup).

Path semantics: directory of .bin shards (same format as --dataset). Operator tokenizes the held-out corpus independently via apr tokenize encode-corpus --max-docs N to a separate output dir, then passes that dir here. The shard contract is contracts/dataset-thestack-python-v1.yaml.

When omitted, falls back to the historical “first 16 batches of –dataset” behaviour for backwards compatibility.

Tokenize

Tokenizer training pipeline (plan/apply) — BPE vocabulary learning

Fields

command: TokenizeCommands

Data

Data quality pipeline (audit, split, balance) — powered by alimentar

Fields

command: DataCommands

Pipeline

Pipeline orchestration (plan/apply/status) — wraps forjar DAG engine

Fields

command: PipelineCommands

Diagnose

Automated Five Whys diagnosis on a training checkpoint

Fields

checkpoint_dir: PathBuf

Path to checkpoint directory

data: Option<PathBuf>

Test data file (JSONL) for evaluation

model_size: Option<String>

Model size hint: “0.5B”, “tiny”

num_classes: usize

Number of output classes (default: 5)

OllamaChatLint

Lint an Ollama /api/chat response for schema + NDJSON invariants (CRUX-C-04)

Fields

response_file: PathBuf

Path to captured /api/chat response (JSON object, or NDJSON if –stream)

stream: bool

Treat input as NDJSON stream (one frame per line)

OllamaToolsLint

Lint an Ollama /api/chat function-calling response (CRUX-I-04)

Fields

response_file: PathBuf

Path to captured /api/chat response (JSON object, or NDJSON if –stream)

request_file: Option<PathBuf>

Captured request JSON, required unless –stream — supplies the tool-name allowlist (every called tool name must appear in request.tools[*].function.name)

stream: bool

Treat input as NDJSON stream (one frame per line)

DrySamplingLint

Lint a captured DRY-sampling observation (CRUX-C-23)

Fields

observation_file: PathBuf

Path to observation JSON

AwqLint

Lint a captured AWQ quality/compression/flags observation (CRUX-B-08)

Fields

observation_file: PathBuf

Path to captured AWQ observation JSON

Fp8Lint

Lint a captured FP8 (E4M3) round-trip + SM-capability observation (CRUX-B-11)

Fields

observation_file: PathBuf

Path to captured observation JSON (frobenius, capability blocks)

Nf4Lint

Lint a captured NF4 codebook/roundtrip/storage/parity observation (CRUX-B-10)

Fields

observation_file: PathBuf

Path to captured NF4 observation JSON

GptqLint

Lint a captured GPTQ compression/cosine/flags observation (CRUX-B-09)

Fields

observation_file: PathBuf

Path to captured GPTQ observation JSON

OomLint

Lint a captured CUDA OOM postmortem report (CRUX-F-13)

Fields

report_file: PathBuf

Path to captured OOM postmortem JSON (e.g. /tmp/apr-oom-.json)

stderr_file: Option<PathBuf>

Optional captured stderr log to verify the OOM_REPORT breadcrumb

NcclDiagLint

Lint a captured NCCL failure-diagnostics JSON from stderr (CRUX-F-15)

Fields

diag_file: PathBuf

Path to captured stderr JSON diagnostic

exit_code: Option<i32>

Optional observed exit code (gate: >= 128 = NCCL class)

require_doc_link: bool

Require the suggest field to cite an nvidia.com / NVIDIA/nccl URL

ReactTraceLint

Lint an externally captured ReAct loop trace JSON (CRUX-I-06 — no apr producer yet)

Fields

trace_file: PathBuf

Path to captured trace JSON

max_iterations: Option<i64>

Optional max_iterations budget the trace was produced under

require_grammar: bool

Require the scratchpad to parse cleanly as Thought/Action/Observation blocks

HangTraceLint

Lint a captured $APR_TRACE_DIR hang stack-dump directory (CRUX-F-14)

Fields

trace_dir: PathBuf

Path to the captured trace directory

mode: String

Inspection mode: timeout (expects per-rank dumps) or success (expects empty dir)

world_size: usize

Expected world_size when mode=timeout (number of rank{N}.py.txt files)

exit_code: Option<i32>

Actual exit code from the run under inspection (for exit-code gate)

expected_exit_code: Option<i32>

Expected exit code (typically 124 for timeout, 1 for other error, 0 for success)

DdpMetricsLint

Lint two externally captured DDP metrics JSONs, N=1 and N=k (CRUX-D-11 — no apr producer yet)

Fields

metrics_1gpu_file: PathBuf

Path to N=1 metrics JSON

metrics_ngpu_file: PathBuf

Path to N=world_size metrics JSON

world_size: i64

World size used for –metrics-ngpu-file run (>= 2)

scaling_floor: f64

Scaling-efficiency floor (default 0.85, PyTorch DDP convention)

loss_tolerance: f64

Loss-parity relative tolerance (default 0.01)

Dataset

Dataset inspection tools (CRUX-H-13)

Fields

command: DatasetCommands

Kernel

Kernel-level parity measurements (CRUX-L-02)

Fields

command: KernelCommands

AudioInspectLint

Lint an audio-inspect JSON body, e.g. from apr dataset audio-inspect clip.wav --format json -o audio.json (CRUX-H-13)

Fields

json_file: PathBuf

Path to the JSON body written by apr dataset audio-inspect --format json

expected_sample_rate: Option<u32>

Optional expected sample_rate (typically the --resample-to arg)

expected_channels: Option<u32>

Optional expected channel count (1 = mono after –mono)

AttnParityLint

Lint attention parity + provenance JSON, e.g. from apr kernel parity --impl tiled --ref naive --json -o parity.json (CRUX-L-02)

Fields

parity_file: Option<PathBuf>

Parity JSON body (max_abs_diff, cosine_sim), as written by apr kernel parity --json

provenance_file: Option<PathBuf>

Provenance JSON body (attn_impl, kernel_source, fallback). apr kernel parity --json writes both gates’ fields into one body, so the same file may be passed here and to –parity-file

head_dim_error_file: Option<PathBuf>

head_dim refusal JSON, as written by apr kernel parity --impl flash2 --head-dim 96 --json (which exits non-zero)

tol_abs: f64

Max absolute diff tolerance (default 5e-3, FlashAttention-2 bound)

tol_cos: f64

Min cosine similarity floor (default 0.9999)

AttnVizLint

Lint an externally captured attention dump (CRUX-F-17 — no apr producer yet)

Fields

attn_file: Option<PathBuf>

Path to attention dump in JSON form (4-D [layers][heads][rows][cols] floats)

html_file: Option<PathBuf>

Path to HTML heatmap output

expected_heatmaps: usize

Minimum <svg|<canvas open-tag count expected in HTML (|layers|*|heads|)

tolerance: f64

Row-softmax normalization tolerance (default 1e-5)

epsilon: f64

Causal-mask zero epsilon (default 1e-9)

CheckFiniteLint

Lint an externally captured check-finite error and/or coverage JSON (CRUX-F-11 — no apr producer yet)

Fields

error_file: Option<PathBuf>

Externally captured check-finite stderr JSON from a poisoned model

list_file: Option<PathBuf>

Externally captured check-finite layer-coverage JSON

min_layers: usize

Minimum layer-coverage count when --list-file is supplied (default 100)

EmbedVizLint

Lint an embedding-projection CSV, e.g. from apr debug embed-viz --model model.apr --seed 42 -o emb.csv (CRUX-F-18)

Fields

csv_file: PathBuf

Path to the token_id,token_str,x,y CSV written by apr debug embed-viz

expected_vocab_size: Option<usize>

Expected row count == vocab_size (optional)

csv_file_b: Option<PathBuf>

Second CSV from a rerun at the same –seed, for the determinism gate (optional)

ExplainTokenLint

Lint an externally captured token-selection JSONL trace (CRUX-F-19 — no apr producer yet)

Fields

jsonl_file: PathBuf

Path to captured JSONL body (one sampled-token record per line)

tolerance: f64

Tolerance for Σ post_prob ≈ 1.0 (default 1e-5)

require_greedy: bool

Assert greedy decoding: sampled_id must equal argmax(pre_prob)

GpuMemtraceLint

Lint a captured GPU memory Chrome Trace Event Format JSON (CRUX-F-07)

Fields

trace_file: PathBuf

Path to an externally captured GPU-memory Chrome Trace JSON (no apr producer yet)

KvTimelineLint

Lint a captured KV-cache utilization timeline (CRUX-F-06)

Fields

timeline_file: PathBuf

Path to an externally captured KV-cache timeline JSON body (no apr producer yet)

preempt_threshold: f64

Preemption threshold (default 0.95, vLLM canonical)

OtlpLint

Lint a captured OTLP/JSON ExportTraceServiceRequest body (CRUX-K-08).

At least one gate flag is required: every check is opt-in, so a bare invocation would check nothing and exit 0 for any parseable JSON.

Fields

otlp_file: PathBuf

Path to captured OTLP/JSON export body

require_apr_span: bool

Require at least one apr.inference span to be present

require_genai_attrs: bool

Require gen_ai.* and apr.tokens.* attribute keys on some span

expect_trace_id: Option<String>

Verify W3C trace-context propagation: expect this 32-hex traceId

PrometheusLint

Lint a captured Prometheus /metrics response (CRUX-K-07)

Fields

metrics_file: PathBuf

Path to captured /metrics response body (text/plain; version=0.0.4)

content_type: Option<String>

Optional captured Content-Type header to verify against version=0.0.4

require_k07_metrics: bool

Require the K-07 metric set (apr_num_requests_running, …) to be present

ToolUseLint

Lint a captured OpenAI tool-use response (CRUX-C-11)

Fields

observation_file: PathBuf

Path to captured OpenAI tool-use response JSON

GbnfLint

Lint a GBNF grammar-constrained observation (CRUX-C-10)

Fields

observation_file: PathBuf

Path to captured GBNF observation JSON

TypicalPLint

Lint a typical-p sampling observation (CRUX-C-22)

Fields

observation_file: PathBuf

Path to captured typical-p observation JSON, with any of the sections range/identity/mass/sort/renorm

GradNorm

Gradient-norm telemetry analysis (CRUX-F-09)

Fields

history_file: PathBuf

Path to JSON file of per-step grad-norm records

max_grad_norm: Option<f64>

Maximum allowed clipped grad-norm (for cap-violation check)

spike_window: usize

Rolling-median window size for spike detection (in steps)

spike_multiplier: f64

Multiplier threshold for spike detection

RegistryQuotaLint

Lint a captured registry byte-quota observation (CRUX-A-22)

Fields

observation_file: PathBuf

Path to captured quota/atomic/ceiling observation JSON

ImatrixLint

Lint a captured imatrix calibration observation (CRUX-B-07)

Fields

observation_file: PathBuf

Path to captured imatrix observation JSON

EmbeddingsLint

Lint a captured /v1/embeddings observation (CRUX-C-13)

Fields

observation_file: PathBuf

Path to captured /v1/embeddings observation JSON, with any of the sections shape/determinism/usage/flag

UnifiedSearchLint

Lint a captured Hub+local unified-search merge observation (CRUX-A-23)

Fields

observation_file: PathBuf

Path to captured unified-search observation JSON

RmGcLint

Lint a captured apr rm / externally captured gc blob-GC observation (CRUX-A-25)

Fields

observation_file: PathBuf

Path to captured rm/gc observation JSON

SharedCacheLint

Lint a captured APR_MODELS shared-cache observation (CRUX-A-21)

Fields

observation_file: PathBuf

Path to captured dedup/permission observation JSON

Ppl

Perplexity classifier (CRUX-E-02)

Fields

log_probs_file: PathBuf

JSON file containing an array of per-token natural-log probabilities (e.g. [-1.2, -0.5, -2.1, ...]). Required.

QuantPreservationLint

Validate dequant→requant metadata preservation (CRUX-B-19)

Fields

reference: PathBuf

Reference GGUF (pre-roundtrip)

requant: PathBuf

Requantized GGUF (post-roundtrip)

Shard

Split a safetensors file into shards + weight-map index (CRUX-B-05)

Fields

file: PathBuf

Single-file safetensors model to split

max_shard_size: String

Maximum size of each shard (e.g. 5GB, 500MB, 1.5GiB)

output: PathBuf

Output directory for shards + model.safetensors.index.json

force: bool

#2392: Overwrite an existing shard set in the output directory

Unshard

Reconstruct a single safetensors file from a sharded directory (CRUX-B-05)

Fields

input: PathBuf

Sharded directory containing model.safetensors.index.json

output: PathBuf

Output single-file safetensors path

force: bool

#2392: Overwrite an existing output file (refused without it)

Tools(ToolCommands)

Publishing, conversion, and analysis tools

Rerank

Score a query/passage pair (or rank multiple passages) with a BERT cross-encoder loaded from an APR v2 file (GH-326 Phase 3).

Wraps aprender_core::models::bert::CrossEncoder::load_from_reader

• score(). The APR must contain the canonical HF BERT tensor names (see models::bert::expected_bert_tensor_names).

Tokenisation is NOT applied here — caller passes pre-tokenised input_ids + token_type_ids as comma-delimited u32 lists. A dedicated tokeniser-aware mode is Phase 3b follow-up scope.

Fields

model: PathBuf

Path to the APR file containing the cross-encoder weights.

input_ids: Option<String>

Pre-tokenised input ids (comma-separated u32s). Mutually exclusive with --query+--passage+--vocab (Phase 3b). Example: --input-ids 101,2024,102,3456,102 for [CLS] q [SEP] p [SEP].

token_type_ids: Option<String>

Pre-tokenised token-type ids (comma-separated u32s). Same length as --input-ids. 0 for query side, 1 for passage.

query: Option<String>

Phase 3b — query text. Pair with --passage + --vocab to enable in-process WordPiece tokenisation. The tokeniser builds [CLS] query [SEP] passage [SEP] with token_type_ids = 0 for the query side and 1 for the passage side.

passage: Option<String>

Phase 3b — passage text. Required when --query is supplied in single-pair mode (use --passages for batch ranking).

passages: Vec<String>

Phase 5 — batch ranking mode (#326). Passage candidates to score against --query. May be supplied multiple times: apr rerank model.apr --query "..." --passages "p1" --passages "p2". Mutually exclusive with --passage. Output is one score[i] line per passage in input order, OR a JSON array of {passage, logit, score} objects sorted by descending score when --sort is set.

sort: bool

Phase 5 — sort batch output by descending score (highest relevance first). Only meaningful with --passages and --json. Default: preserve input order.

top_k: usize

Phase 5 — limit to top-K passages after sorting. Implies --sort. Default 0 (no limit).

vocab: Option<PathBuf>

Phase 3b — path to a WordPiece vocab.txt (one token per line, line index = token id). Required when --query is supplied. Must contain entries for [CLS], [SEP], and [UNK]. Phase 4 accepts HuggingFace tokenizer.json (extension-detected).

hidden_dim: usize

Override hidden_dim (default: 384 / MiniLM-L-6).

num_layers: usize

Override num_layers (default: 6 / MiniLM-L-6).

num_heads: usize

Override num_heads (default: 12 / MiniLM-L-6).

intermediate_dim: usize

Override intermediate_dim (default: 1536 / MiniLM-L-6).

vocab_size: usize

Override vocab_size (default: 30522 / bert-base-uncased).

max_position_embeddings: usize

Override max_position_embeddings (default: 512).

type_vocab_size: usize

Override type_vocab_size (default: 2).

num_labels: usize

Number of labels in the classifier head (default: 1 for regression-style relevance scoring).

with_pooler: bool

Load the optional BERT pooler dense layer (default: true). Cross-encoders that skip the pooler should pass --with-pooler false.

Takes an optional value: --with-pooler (bare) and an omitted flag both mean true; --with-pooler false / --with-pooler=false turn the pooler off. A bare bool here would compile to a SetTrue switch and make the documented false unreachable.

raw_logit: bool

Emit the raw logit instead of the sigmoid-mapped relevance score.

json: bool

Output as JSON.

Embed

Produce sentence embeddings from a BERT bi-encoder (GH-326 Phase 6).

First-stage dense retrieval companion to apr rerank. Loads an encoder-only BertModel (e.g. sentence-transformers/all-MiniLM-L6-v2), tokenises the input text with WordPiece, runs the full encoder forward, then pools the hidden states with one of: --pool cls — take the [CLS] hidden state --pool mean — mean over non-padding token positions (default; sentence-transformers convention) Optionally L2-normalises the result (--normalize, default true, matches sentence-transformers).

Fields

model: PathBuf

Path to the APR file containing the encoder weights (BertModel).

text: Vec<String>

Text to encode. Repeatable: apr embed model.apr --text "a" --text "b" --vocab tok.json.

text_file: Option<PathBuf>

Phase 7 (GH-326) — read texts from a file, one per line. Concatenated with --text inputs in order: --text first, then --text-file rows. Blank lines and lines starting with # are skipped. Useful for RAG-style first-stage retrieval where the second-stage rerank candidate set (50-100 documents) is the embed input.

vocab: PathBuf

Path to a WordPiece vocab.txt or HF tokenizer.json.

pool: String

Pooling strategy (cls or mean). Default: mean (matches sentence-transformers convention).

normalize: bool

L2-normalise the output embedding. Default: true (matches sentence-transformers convention). Pass --normalize false to keep raw magnitudes.

Takes an optional value: --normalize (bare) and an omitted flag both mean true; --normalize false / --normalize=false keep the raw magnitudes. A bare bool here would compile to a SetTrue switch and make the documented false unreachable.

Because the value is optional, do not place a bare --normalize immediately before the MODEL positional — write apr embed MODEL --normalize or --normalize=true MODEL.

hidden_dim: usize

Override hidden_dim (default: 384 / MiniLM).

num_layers: usize

Override num_layers (default: 6 / MiniLM-L-6).

num_heads: usize

Override num_heads.

intermediate_dim: usize

Override intermediate_dim.

vocab_size: usize

Override vocab_size.

max_position_embeddings: usize

Override max_position_embeddings.

type_vocab_size: usize

Override type_vocab_size.

json: bool

Output as JSON.

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