Enum Commands 

pub enum Commands {
    Run {

        source: String,
        positional_prompt: Option<String>,
        input: Option<PathBuf>,
        prompt: Option<String>,
        max_tokens: usize,
        stream: bool,
        language: Option<String>,
        task: Option<String>,
        format: String,
        no_gpu: bool,
        gpu: bool,
        offline: bool,
        benchmark: bool,
        trace: bool,
        trace_steps: Option<Vec<String>>,
        trace_verbose: bool,
        trace_output: Option<PathBuf>,
        trace_level: String,
        trace_payload: bool,
        profile: bool,
        chat: bool,
        verbose: bool,
    
},
    Serve {
        command: ServeCommands,
    },
    Inspect {
        file: PathBuf,
        vocab: bool,
        filters: bool,
        weights: bool,
        json: bool,
    },
    Debug {
        file: PathBuf,
        drama: bool,
        hex: bool,
        strings: bool,
        limit: usize,
    },
    Validate {
        file: PathBuf,
        quality: bool,
        strict: bool,
        min_score: Option<u8>,
    },
    Diff {
        file1: PathBuf,
        file2: PathBuf,
        weights: bool,
        values: bool,
        filter: Option<String>,
        limit: usize,
        transpose_aware: bool,
        json: bool,
    },
    Tensors {
        file: PathBuf,
        stats: bool,
        filter: Option<String>,
        limit: usize,
        json: bool,
    },
    Trace {
        file: PathBuf,
        layer: Option<String>,
        reference: Option<PathBuf>,
        json: bool,
        verbose: bool,
        payload: bool,
        diff: bool,
        interactive: bool,
    },
    Lint {
        file: PathBuf,
    },
    Explain {
        code_or_file: Option<String>,
        file: Option<PathBuf>,
        tensor: Option<String>,
        kernel: bool,
        json: bool,
        verbose: bool,
        proof_status: bool,
    },
    Canary {
        command: CanaryCommands,
    },
    Export {
        file: Option<PathBuf>,
        format: String,
        output: Option<PathBuf>,
        quantize: Option<String>,
        list_formats: bool,
        batch: Option<String>,
        json: bool,
        plan: bool,
    },
    Import {
        source: String,
        output: Option<PathBuf>,
        arch: String,
        quantize: Option<String>,
        strict: bool,
        preserve_q4k: bool,
        tokenizer: Option<PathBuf>,
        enforce_provenance: bool,
        allow_no_config: bool,
    },
    Pull {
        model_ref: String,
        force: bool,
    },
    List,
    Rm {
        model_ref: String,
    },
    Convert {
        file: PathBuf,
        quantize: Option<String>,
        compress: Option<String>,
        output: PathBuf,
        force: bool,
    },
    Compile {
        file: Option<PathBuf>,
        output: Option<PathBuf>,
        target: Option<String>,
        quantize: Option<String>,
        release: bool,
        strip: bool,
        lto: bool,
        list_targets: bool,
    },
    Merge {
        files: Vec<PathBuf>,
        strategy: String,
        output: PathBuf,
        weights: Option<Vec<f32>>,
        base_model: Option<PathBuf>,
        drop_rate: f32,
        density: f32,
        seed: u64,
        plan: bool,
    },
    Quantize {
        file: PathBuf,
        scheme: String,
        output: Option<PathBuf>,
        format: Option<String>,
        batch: Option<String>,
        plan: bool,
        force: bool,
    },
    ModelOps(ModelOpsCommands),
    Tui {
        file: Option<PathBuf>,
    },
    Check {
        file: PathBuf,
        no_gpu: bool,
        json: bool,
    },
    Gpu {
        json: bool,
    },
    Extended(ExtendedCommands),
}

Variants

Run

Run model directly (auto-download, cache, execute)

Fields

source: String

Model source: local path, hf://org/repo, or URL

positional_prompt: Option<String>

Text prompt (positional): apr run model.gguf "What is 2+2?"

input: Option<PathBuf>

Input file (audio, text, etc.)

prompt: Option<String>

Text prompt for generation (for LLM models)

max_tokens: usize

Maximum tokens to generate (default: 32)

stream: bool

Enable streaming output

language: Option<String>

Language code (for ASR models)

task: Option<String>

Task (transcribe, translate)

format: String

Output format (text, json, srt, vtt)

no_gpu: bool

Disable GPU acceleration

gpu: bool

Force GPU acceleration

offline: bool

Offline mode: block all network access (Sovereign AI compliance)

benchmark: bool

Benchmark mode: output performance metrics (tok/s, latency)

trace: bool

Enable inference tracing (APR-TRACE-001)

trace_steps: Option<Vec<String>>

Trace specific steps only (comma-separated)

trace_verbose: bool

Verbose tracing (show tensor values)

trace_output: Option<PathBuf>

Save trace output to JSON file

trace_level: String

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

trace_payload: bool

Shorthand for –trace –trace-level payload (tensor value inspection)

profile: bool

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

chat: bool

Apply chat template for Instruct models (GAP-UX-001)

Wraps prompt in ChatML format for Qwen2, LLaMA, Mistral Instruct models. Format: <|im_start|>user\n{prompt}<|im_end|>\n<|im_start|>assistant\n

verbose: bool

Show verbose output (model loading, backend info)

Serve

Inference server (plan/run)

Fields

command: ServeCommands

Inspect

Inspect model metadata, vocab, and structure

Fields

file: PathBuf

Path to .apr model file

vocab: bool

Show vocabulary details

filters: bool

Show filter/security details

weights: bool

Show weight statistics

json: bool

Output as JSON

Debug

Simple debugging output (“drama” mode available)

Fields

file: PathBuf

Path to .apr model file

drama: bool

Theatrical “drama” mode output

hex: bool

Show hex dump

strings: bool

Extract ASCII strings

limit: usize

Limit output lines

Validate

Validate model integrity and quality

Fields

file: PathBuf

Path to .apr model file

quality: bool

Show 100-point quality assessment

strict: bool

Strict validation (fail on warnings)

min_score: Option<u8>

Minimum score to pass (0-100)

Diff

Compare two models

Fields

file1: PathBuf

First model file

file2: PathBuf

Second model file

weights: bool

Show weight-level differences

values: bool

Compare actual tensor values with statistical analysis

filter: Option<String>

Filter tensors by name pattern (for –values)

limit: usize

Maximum number of tensors to compare (for –values)

transpose_aware: bool

Account for transpose when comparing (GGUF col-major vs APR row-major)

json: bool

Output as JSON

Tensors

List tensor names and shapes

Fields

file: PathBuf

Path to .apr model file

stats: bool

Show tensor statistics (mean, std, min, max)

filter: Option<String>

Filter tensors by name pattern

limit: usize

Limit number of tensors shown (0 = unlimited)

json: bool

Output as JSON

Trace

Layer-by-layer trace analysis

Fields

file: PathBuf

Path to .apr model file

layer: Option<String>

Filter layers by name pattern

reference: Option<PathBuf>

Compare with reference model

json: bool

Output as JSON

verbose: bool

Verbose output with per-layer stats

payload: bool

Trace payload through model

diff: bool

Diff mode

interactive: bool

Interactive mode

Lint

Check for best practices and conventions

Fields

file: PathBuf

Path to .apr model file

Explain

Explain errors, architecture, tensors, and kernel dispatch

Fields

code_or_file: Option<String>

Error code, model file path, or family name (auto-detected)

file: Option<PathBuf>

Path to .apr model file (optional context for –tensor)

tensor: Option<String>

Explain a specific tensor

kernel: bool

Explain kernel dispatch pipeline for architecture

json: bool

Output as JSON

verbose: bool

Show kernel contract details and proof obligations

proof_status: bool

Show per-kernel proof status from contract tests

Canary

Manage canary tests for regression

Fields

command: CanaryCommands

Export

Export model to other formats

Fields

file: Option<PathBuf>

Path to .apr model file

format: String

Output format (safetensors, gguf, mlx, onnx, openvino, coreml)

output: Option<PathBuf>

Output file/directory path

quantize: Option<String>

Apply quantization during export (int8, int4, fp16)

list_formats: bool

List all supported export formats

batch: Option<String>

Batch export to multiple formats (comma-separated: gguf,mlx,safetensors)

json: bool

Output in JSON format

plan: bool

Plan mode (validate inputs, show export plan, no execution)

Import

Import from external formats (hf://org/repo, local files, URLs)

Fields

source: String

Source: hf://org/repo, local file, or URL

output: Option<PathBuf>

Output .apr file path (default: derived from source name)

arch: String

Model architecture (whisper, llama, bert, qwen2, qwen3, gpt2, starcoder, gpt-neox, opt, phi, gemma, falcon, mamba, t5, auto)

quantize: Option<String>

Quantization (int8, int4, fp16)

strict: bool

Strict mode: reject unverified architectures and fail on validation errors

preserve_q4k: bool

Preserve Q4K quantization for fused kernel inference (GGUF only) Uses realizar’s Q4K converter instead of dequantizing to F32

tokenizer: Option<PathBuf>

PMAT-232: External tokenizer.json for weights-only GGUF files. Required if the GGUF has no embedded tokenizer vocabulary.

enforce_provenance: bool

F-GT-001: Enforce provenance chain. Rejects pre-baked GGUF imports (only SafeTensors sources allowed). Ensures single-provenance testing.

allow_no_config: bool

GH-223: Allow import without config.json (default: error). Without config.json, hyperparameters like rope_theta are inferred from tensor shapes and may be wrong, producing garbage output.

Pull

Download and cache model from HuggingFace (Ollama-like UX)

Fields

model_ref: String

Model reference (alias, hf:// URI, or org/repo)

force: bool

Force re-download even if cached

List

List cached models

Rm

Remove model from cache

Fields

model_ref: String

Model reference to remove

Convert

Convert/optimize model

Fields

file: PathBuf

Path to .apr model file

quantize: Option<String>

Quantize to format (int8, int4, fp16, q4k)

compress: Option<String>

Compress output (none, zstd, zstd-max, lz4)

output: PathBuf

Output file path

force: bool

Force overwrite existing files

Compile

Compile model into standalone executable (APR-SPEC §4.16)

Fields

file: Option<PathBuf>

Input .apr model file

output: Option<PathBuf>

Output binary path (default: derived from model name)

target: Option<String>

Target triple (e.g., x86_64-unknown-linux-musl)

quantize: Option<String>

Quantize weights before embedding (int8, int4, fp16)

release: bool

Release mode (optimized)

strip: bool

Strip debug symbols

lto: bool

Enable LTO (Link-Time Optimization)

list_targets: bool

List available compilation targets

Merge

Merge multiple models

Fields

files: Vec<PathBuf>

Model files to merge

strategy: String

Merge strategy (average, weighted, slerp, ties, dare)

output: PathBuf

Output file path

weights: Option<Vec<f32>>

Weights for weighted merge (comma-separated, e.g., “0.7,0.3”)

base_model: Option<PathBuf>

Base model for TIES/DARE (task vectors computed as delta from base)

drop_rate: f32

DARE drop probability (default: 0.9)

density: f32

TIES trim density threshold (default: 0.2)

seed: u64

RNG seed for DARE (default: 42)

plan: bool

Plan mode (validate inputs, show merge plan, no execution)

Quantize

Quantize model weights (GH-243)

Fields

file: PathBuf

Input model file

scheme: String

Quantization scheme: int8, int4, fp16, q4k

output: Option<PathBuf>

Output file path (required unless –plan)

format: Option<String>

Output format override (apr, gguf, safetensors)

batch: Option<String>

Batch quantization (comma-separated schemes)

plan: bool

Plan mode (estimate only, no execution)

force: bool

Force overwrite existing files

ModelOps(ModelOpsCommands)

Model optimization commands (fine-tune, prune, distill)

Tui

Interactive terminal UI

Fields

file: Option<PathBuf>

Path to .apr model file

Check

Model self-test: 10-stage pipeline integrity check (APR-TRACE-001)

Fields

file: PathBuf

Path to model file

no_gpu: bool

Disable GPU acceleration

json: bool

Output as JSON

Gpu

GPU status and VRAM reservation management (GPU-SHARE-001)

Fields

json: bool

Show reservations as JSON

Extended(ExtendedCommands)

Extended analysis, profiling, QA, and visualization commands

Trait Implementations

impl Debug for Commands

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

Formats the value using the given formatter.

impl FromArgMatches for Commands

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 Commands

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