OpenTail.Stingray.Cli 1.0.9

OpenTail.Stingray.Cli

stingray is the command-line front door to OpenTail.Stingray: install a recommended model for a task and run it without typing a path (setup, chat, speak, transcribe), or point it at any GGUF and tune the run yourself. It also generates images, computes embeddings, and carries the tools for checking and admitting new models (scout, pull, inspect, admit-arch). Runs on CPU (AVX2/AVX-512) or GPU (Vulkan / CUDA). No Python, no llama.cpp, no sidecar process.

Built by opentail.net

Install

dotnet tool install -g OpenTail.Stingray.Cli

Or update:

dotnet tool update -g OpenTail.Stingray.Cli

The command is stingray.

Quick Start: Path-Free Front Door

# 1. Download verified default model bundles
stingray setup chat          # Qwen2.5 0.5B Instruct (469 MB)
stingray setup speak         # Piper en_US-lessac-medium (60 MB)
stingray setup transcribe    # Whisper base (141 MB)
stingray models              # check installation status

# Optional: choose a qualified alternative or view local inventory
stingray models chat         # view chat choices (qwen2.5-0.5b, qwen2.5-1.5b, qwen2.5-7b)
stingray models use chat qwen2.5-1.5b  # set persistent favourite for chat
stingray models --local      # list installed models on disk (multi-shard GGUFs deduplicated)

# 2. Run immediately without typing paths
stingray chat                # interactive multi-turn terminal chat
stingray chat "Explain SIMD in one sentence."
stingray speak "Hello from Stingray." -o hello.wav
stingray transcribe hello.wav

Is my machine ready?

stingray models              # which of chat / speak / transcribe have a model installed, and the command that fixes each gap
stingray doctor              # the local runtime and which GPU backends are usable
stingray doctor -m model.gguf   # structural check of a GGUF without running inference

(stingray status is different: it reads live metrics from a running server.) The starter catalogue covers chat, speak and transcribe only. Everything else the engine can run, and how well each model was checked, is in docs/STATUS.md.

A model that is not in the catalogue

Check it before you download it, then fetch exactly the file you checked:

stingray scout -r owner/repo --quants --budget 32G           # architecture, blockers, which quantisations fit, a pull command pinned to the inspected commit
stingray pull  -r owner/repo --revision <commit> -q Q4_K_M    # downloads that revision, so you get what scout inspected
stingray -m models/<file>.gguf -p "Hello" -g -1              # run it (drop -g -1 for CPU)

scout reads only the file index, never the weights, and only reports: without --budget it does not judge whether the model fits your RAM. A local file works too (stingray scout -m model.gguf). If the architecture is not admitted yet, see adding an architecture for the evidence required before it is advertised as supported.

Advanced & Path-Oriented Usage

# Text generation with explicit model path (CPU)
stingray -m models/SmolLM2-1.7B-Instruct-Q4_K_M.gguf -p "Once upon a time" --temp 0.7

# All layers on GPU (Vulkan or CUDA, auto-selected)
stingray -m models/Qwen3-8B-Q4_K_M.gguf -p "Explain mmap" --backend vulkan -g -1

# Interactive chat (omit -p to enter chat mode)
stingray -m models/Qwen3-8B-Q4_K_M.gguf

# Inspect before running
stingray list-metadata -m model.gguf
stingray capabilities                     # which model packages are supported
stingray inspect -m models/some-hf-dir    # verdict on a SafeTensors package

# Image generation (Z-Image-Turbo). A GPU (Vulkan or CUDA) is strongly recommended; add `--device none` to force CPU, which is slow.
stingray image \
  -m models/z_image_turbo-Q5_K_M.gguf \
  --vae models/z-image-turbo/vae \
  --qwen-encoder models/Z-Image-AbliteratedV1.Q5_K_M.gguf \
  --qwen-tokenizer models/z-image-turbo/tokenizer/tokenizer.json \
  -p "a serene mountain lake at sunrise" -W 512 -H 512 --steps 4 -o out.png

Coming from llama.cpp

Flag names follow llama-cli where the meaning matches, including single-dash spellings like -ngl, -ctk, -md and -fa, so a command copied from llama.cpp documentation generally just runs.

Where a flag cannot be honoured, it is refused with a named reason rather than silently ignored — -ts, -sm, -mg, --mlock, --numa, --presence-penalty and -b/-ub all tell you what Stingray does instead. Flags that are simply inert here (-fa, --no-warmup) are accepted with a note so a pasted command line still runs. The one thing you will never get is a flag that looks accepted and quietly does nothing.

Common flags

Run stingray --help or view the CLI Option Inventory for every option of every command.

Requirements

• .NET 10 runtime — the tool installs framework-dependent
• x86-64 CPU with AVX2
• GPU inference is optional: any Vulkan-capable GPU (AMD / Intel / NVIDIA), or an NVIDIA GPU with CUDA 12.x — the CUDA path is pinned to the 12.x runtime SONAMEs (cudart64_12, cublas64_12)

Links

• Library package
• Server package
• Repository and documentation

Acknowledgements

Forked from SharpInference by Pekka Heikura (MIT), which remains actively developed upstream; its copyright is retained in THIRD_PARTY_NOTICES.md.

Interoperates with llama.cpp's GGUF format and quantization block layouts, and follows llama-cli flag names where the meaning matches — no llama.cpp code is used. LLamaSharp was studied as the reference for .NET inference API design; no LLamaSharp code is used, and unlike it this engine is managed C# end to end rather than P/Invoke bindings to native llama.cpp.

License

MIT. Copyright © 2026 OpenTail.