Complete command reference¶
This reference is generated from the same command help shipped with CLI 0.2.2. Use the workflow guides for context, model requirements and full examples.
run¶
Generate text, optionally with an image from a compatible vision model.
spum run MODEL.gguf --gpu -p "Explain this observation." -n 256
spum run --model MODEL.gguf --prompt-file question.txt --json -o result.json
INPUT
--model FILE Model file (alternative to positional MODEL)
-p, --prompt TEXT User prompt
--prompt-file FILE Read user prompt from UTF-8 text file (max 64 MiB)
--system TEXT System instruction
--system-file FILE Read system instruction from a text file
--image FILE Image input for a compatible vision model
--mmproj FILE Matching image projector
--vision-cpu Encode the image on the CPU
--no-image-cache Disable persistent image caching for this command
--raw Bypass the model's normal chat template
--parse-special Parse special tokens where supported
GENERATION
-n, --n-predict, --max-tokens N Maximum new tokens (default 256)
--temp, --temperature N Temperature; 0 is greedy (default 0.7)
--top-k N Top-k sampling (default 40)
--top-p N Nucleus probability (default 0.9)
--min-p N Minimum relative probability (default 0)
--repeat-penalty N Repetition penalty (default 1.1)
--seed N Sampling seed (default 0)
-c, --ctx, --context-size N Context size; 0 uses model/runtime default
-t, --threads N CPU threads; 0 uses runtime default
--gpu Use the supported GPU backend
--cpu Use the CPU backend
--gpu-fp16 auto|on|off GPU precision policy (default auto)
--compact off|on|auto Compact mode (default off); may affect quality
--no-spec Disable prompt-lookup acceleration
--draft FILE Compatible assistant model
--no-draft Disable assistant-model drafting
--draft-max N Maximum assistant draft length
--history on|off Local output history (default off)
OUTPUT (run only)
--json JSON response and timing fields
-o, --output FILE Write response to a file (replaces existing file)
-q, --quiet Suppress run timing messages; errors remain visible
Default: response on stdout, run timings on stderr.
LINK (CPU path; same model file on each host)
--link HOST:PORT[,HOST:PORT] Connect worker(s)
--link-key CODE Pairing key
--link-key-file FILE Read pairing key from a file
--link-layers N[,N] Explicit model split boundaries
--link-fp16 Reduced-precision transfer; outputs may differ
SPUM_LINK_KEY Alternative environment variable for pairing key
chat¶
Interactive terminal chat. Generation, system, CPU/GPU and Link options match run.
spum chat MODEL.gguf --gpu --system "You are a concise research assistant."
/reset Clear the current conversation
/quit Exit (also /exit)
--json, --output and --quiet are run-only options.
serve¶
Start a local HTTP server with one loaded model.
spum serve MODEL.gguf --gpu --host 127.0.0.1 --port 11436
--host ADDRESS Bind address (default 127.0.0.1)
--port N TCP port (default 11436)
--system TEXT Default system instruction
--system-file FILE Read default system instruction from a file
GET /health
GET /v1/models
POST /v1/chat/completions Streaming and non-streaming
CPU/GPU, context, image-projector and Link options are also accepted.
bench¶
Measure prompt processing and decode independently.
spum bench MODEL.gguf --gpu --n-prompt 256 -n 128 --reps 5
--n-prompt N Synthetic prompt length (default 128)
-n N Decode length (default 256)
--reps N Measured repetitions (default 3), plus warm-up
-t N CPU threads
--profile Additional profiling output
--gpu / --cpu, --gpu-fp16, --compact and --no-pack also accepted.
ppl¶
Measure text perplexity on a corpus, independently of generation quality.
spum ppl MODEL.gguf --gpu -f corpus.txt -c 512 --chunks 8
-f, --file FILE UTF-8 evaluation corpus
--chunks N Maximum context chunks (default 8)
-c N Context size; corpus must contain enough complete chunks
info¶
tokenize¶
Print prompt token IDs using the model's tokenizer and chat formatting.
spum tokenize MODEL.gguf -p "Hello"
--raw Raw prompt formatting
--parse-special Parse special tokens
logits¶
Print top next-token candidates for an exact prompt.
spum logits MODEL.gguf --gpu -p "The answer is"
--image FILE --mmproj FILE can be used with compatible vision models.
music¶
AfterGlow: continue a MIDI phrase with a compatible Aria GGUF checkpoint.
spum music --checkpoint ARIA.gguf --input phrase.mid --output continuation
--checkpoint FILE Compatible Aria GGUF checkpoint (required)
--input FILE Input MIDI file
--output DIRECTORY Output directory; full.mid contains the resulting continuation
--tokens N Requested new tokens (default 192)
--temperature N Sampling temperature (default 0.95)
--seed N Sampling seed
--cpu CPU execution
--serve JSON-lines requests on stdin, one JSON reply per line
JSON request: {"input":"phrase.mid","output":"continuation","tokens":192,"temperature":0.95}
MIDI continuation does not produce an audio waveform or establish therapeutic efficacy.
link¶
Run one model across computers you own.
spum link pair
spum link worker MODEL.gguf --listen 127.0.0.1:11900 --key CODE
spum link status HOST:11900 --key CODE
spum run MODEL.gguf --link HOST:11900 --link-key-file pairing.key -p "Hello"
Worker options: --listen HOST:PORT, --key CODE, --key-file FILE, -t THREADS
Use matching model files. Worker stays running until stopped.
history¶
Manage optional local output history.
spum history clear
Enable with --history on when running a model. Default is off.
Clearing history removes saved history files, not downloaded models.
app¶
Start the legacy local browser interface.
spum app --port 11436 --models-dir DIRECTORY
The standalone Mac app is installed separately with the spum-app cask.
xray¶
Run a separately supplied compatible radiograph model pack (macOS).
spum xray MODELPACK --image IMAGE --output DIRECTORY
Requires the actual pack; a plain MedGemma GGUF is not a segmentation pack.
This command's existence does not establish clinical accuracy.
detect¶
Run detection with a separately supplied compatible model pack.
spum detect MODELPACK --image IMAGE --output findings.json
segment¶
Run a compatible compiled segmentation encoder and decoder with detections.
spum segment ENCODER.mlmodelc DECODER.mlmodelc --image IMAGE --detections findings.json --mask mask.pgm
capabilities¶
Show machine-readable model-type capability information.
spum capabilities
spum capabilities --json
Lists text, image understanding, MIDI, speech recognition, speech synthesis,
image generation and video generation with explicit executable status.
models¶
Show the model-type catalog and model-distribution status.
spum models types
Model weights are not bundled with the application and must match the runtime.
Unreleased or unimplemented model types are never represented as executable.