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,
        temperature: f32,
        top_k: usize,
        top_p: Option<f32>,
        seed: u64,
        repeat_penalty: f32,
        repeat_last_n: usize,
        split_prompt: bool,
        batch_jsonl: Option<PathBuf>,
        verbose: bool,
        backend: Option<String>,
    
},
    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>,
    },
    ValidateManifest {
        file: PathBuf,
        artifact: Option<PathBuf>,
        live: bool,
    },
    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,
        save_tensor: Option<String>,
        save_tensor_dir: Option<PathBuf>,
        save_tensor_layers: String,
    },
    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,
        repo: Option<String>,
        force: bool,
        dry_run: bool,
        revision: Option<String>,
        offline: bool,
        include: Vec<String>,
        output: Option<PathBuf>,
    },
    Registry {
        command: RegistryCommands,
    },
    List,
    Rm {
        model_ref: String,
    },
    Convert {
        file: PathBuf,
        quantize: Option<String>,
        compress: Option<String>,
        output: PathBuf,
        force: bool,
    },
    Stamp {
        file: PathBuf,
        license: Option<String>,
        data_source: Option<String>,
        data_license: 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: Option<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),
    Mcp {},
    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 (force CPU-only inference)

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, chrome) “chrome” outputs chrome://tracing JSON integrating layer trace + brick profile. F-CLIPARITY-01 / PMAT-386 / paiml/aprender#574

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

temperature: f32

Sampling temperature (0.0 = greedy, default: 0.0)

top_k: usize

Top-k sampling (default: 1 = greedy)

top_p: Option<f32>

Top-p nucleus sampling (0.0 = disabled). When set with –top-k, applies top-k first then top-p. F-CLIPARITY-01 / PMAT-381 / paiml/aprender#569

seed: u64

RNG seed for deterministic sampling (default: 299792458, matching Candle) F-CLIPARITY-01 / PMAT-382 / paiml/aprender#570

repeat_penalty: f32

Repetition penalty (1.0 = no penalty, >1.0 penalizes repeats) F-CLIPARITY-01 / PMAT-383 / paiml/aprender#571

repeat_last_n: usize

Context window for repetition penalty (number of recent tokens to check) F-CLIPARITY-01 / PMAT-384 / paiml/aprender#571

split_prompt: bool

Process prompt tokens one-by-one instead of batched prefill. Useful for debugging prefill correctness (comparing per-token attention). F-CLIPARITY-01 / PMAT-385 / paiml/aprender#572

batch_jsonl: Option<PathBuf>

Batch mode: read prompts from JSONL, output results as JSONL. Model loads once, processes all prompts sequentially. Each input line: {“prompt”: “…”, “task_id”: “…”} Chat template is applied automatically.

verbose: bool

Show verbose output (model loading, backend info)

backend: Option<String>

PMAT-488: Compute backend override (cuda, cpu, wgpu)

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)

ValidateManifest

Validate a publish manifest (FALSIFY-PM-001..006).

Contract: contracts/publish-manifest-v1.yaml Spec: SPEC-SHIP-TWO-001 §12.3 AC-EX-004

Fields

file: PathBuf

Path to manifest YAML

artifact: Option<PathBuf>

Optional local .apr artifact to discharge FALSIFY-PM-002 (sha256 match)

live: bool

Discharge FALSIFY-PM-003 via network: HTTP HEAD + streaming sha256. Default is DEFERRED (offline-safe). Ignored when –offline is set. Closes F-PUBLISH-EXTRA-001::dogfood_ex05 (no Python in ex-05).

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

save_tensor: Option<String>

Save per-stage F32 tensors during trace for SHIP-007 layer-0 element-wise diff. Comma-separated stage names from apr-cli-trace-save-tensor-v1.yaml (e.g. embedding,qkv_matmul,attention). Pass all to save every stage. Output goes to --save-tensor-dir if provided, else <file_dir>/trace-tensors/<run_id>/.

save_tensor_dir: Option<PathBuf>

Output directory for --save-tensor (default: sibling trace-tensors/<run_id>/).

save_tensor_layers: String

Layer-id range for --save-tensor (default: 0..1, i.e. layer 0 only). Format: START..END (Rust range syntax, END exclusive).

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 OR HuggingFace dataset (Ollama-like UX)

Fields

model_ref: String

Model reference (alias, hf:// URI, or org/repo) OR “dataset” asset-type discriminator. When this value is the literal string “dataset”, the next positional repo is the HuggingFace dataset repo and dataset-pull semantics apply.

repo: Option<String>

Dataset repository (used only when model_ref == “dataset”). Per apr-cli-pull-dataset-v1.yaml.

force: bool

Force re-download even if cached

dry_run: bool

CRUX-A-01: resolve short name to canonical URL and exit without performing any network I/O.

revision: Option<String>

CRUX-A-03: pin to a specific branch, tag, or git SHA on the remote (HuggingFace Hub). Defaults to “main” when omitted.

offline: bool

CRUX-A-20: offline mode — forbid any outbound network I/O. Equivalent to APR_OFFLINE=1 or HF_HUB_OFFLINE=1 in the environment.

include: Vec<String>

(dataset mode) Glob pattern for shard selection. May be passed multiple times; matches are unioned. fnmatch-compatible (*, ?, [a-z]). No-match is fail-fast.

output: Option<PathBuf>

(dataset mode) Output directory. Default: ~/.cache/aprender/datasets/<repo>/.

Registry

Registry operations (CRUX-A-01): inspect alias map, etc.

Fields

command: RegistryCommands

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

Stamp

Stamp provenance fields (license, data_source, data_license) onto an existing .apr file

SHIP-009 full-discharge enabler — patches the three provenance fields on a pre-built APR v2 artifact (e.g., the shipped MODEL-1 teacher whose fields are all (missing) because it was built before GATE-APR-PROV-001..003 shipped). Tensor bytes and header flags are preserved verbatim.

Fields

file: PathBuf

Path to input .apr model file

license: Option<String>

SPDX license identifier (e.g., Apache-2.0)

data_source: Option<String>

Training-data source (e.g., huggingface.co/Qwen/Qwen2.5-Coder-7B-Instruct)

data_license: Option<String>

SPDX license for data_source (e.g., Apache-2.0)

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: Option<PathBuf>

Output file path (optional in –plan mode)

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)

Mcp

Start the MCP (Model Context Protocol) server over stdio

Exposes apr as MCP tools for Claude Code, Cursor, Cline, and other MCP clients. Configure via .mcp.json with {"command":"apr","args":["mcp"]}.

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