Use Winml CLI

winml CLI

winml is a CLI that turns a source model — a Hugging Face ID or a local ONNX file — into a portable, performant artifact that runs on any Windows execution provider. This skill teaches you the shape of that workflow. The CLI is the source of truth for current commands and flags.

Installing the CLI

Default behavior: lead any walkthrough with a brief install section. Unless the user signals they already have winml working, include the install steps below (or a clear "prereq: install winml first" pointer to them) as the first thing in your response. First-timers shouldn't have to guess what they need.

Skip the install section only if the user clearly signals they're past install:

• They quote a winml <command> they ran, with output or an error from it.
• They say they "already" / "previously" exported, built, optimized, etc. with winml.
• They share an artifact path that came out of an earlier winml run.
• They're asking a debugging or comparison question that presumes a working install.

When in doubt, include it — a five-line prereq block is cheaper than a stuck user.

winml-cli pins Python 3.11 exactly (>=3.11,<3.12) — use uv to create an isolated venv so you don't pollute system Python or land on a 3.12+ environment that won't resolve.

1. Create a Python 3.11 environment

uv venv --python 3.11

Activate it:

# Windows (PowerShell)
.venv\Scripts\activate

# Windows (Git Bash / WSL)
source .venv/Scripts/activate

2. Install winml-cli from PyPI

uv pip install winml-cli

3. Verify

winml --help
winml sys --list-ep

--help should print the command list, and sys --list-ep should show the execution providers registered on this machine.

Discover the CLI before doing anything else

The command set and flags evolve. Don't memorize them and don't guess them — read them from the tool itself:

• winml --help — current top-level command list with one-line descriptions.
• winml <command> --help — current flags, arguments, and defaults for that command.
• winml sys --list-device --list-ep — what hardware and execution providers are actually present on this machine.

Run these before quoting any command to the user, not after. "I'll check --help if anything looks off" is too late — the user has already copy-pasted a broken command and come back annoyed. If you're about to write winml <something> in your reply, run winml <something> --help first.

The CLI is flag-based, not positional. Model IDs and paths go through -m / --model, not as bare positional arguments. winml inspect microsoft/resnet-50 will error — you need winml inspect -m microsoft/resnet-50. This shape is stable across the toolkit; the specific flag spelling per command isn't, which is why you still read --help.

Inventing plausible-sounding flags (a --preset, --profile, --mode=fast) is the most common way to waste the user's time — the command will reject them and the user has to come back. When in doubt, --help.

The mental model

winml organizes work as a pipeline. Each stage is its own primitive command, and the output of one stage feeds the next:

inspect → export → analyze → optimize → quantize → compile → perf

You don't have to run every stage. Enter wherever the user's input lives (already have an ONNX file? skip export) and exit when you have what you need (just want a latency number? stop at perf). Several stages are EP- or hardware-sensitive — compile is documented as requiring an NPU device (per README's Scope & Limitations: "winml compile requires an NPU device"). winml compile --help does expose --device and --ep values for CPU/GPU, but treat NPU as the assumed target unless the user says otherwise.

Sitting on top of the primitives are two shortcut commands that wrap the whole pipeline:

• A config command auto-detects every setting the pipeline needs and writes a JSON file.
• A build command reads that config and runs the stages in order.

Together they replace the seven primitives with two.

The names above (inspect, export, analyze, optimize, quantize, compile, perf, plus the config/build pair) are stable concepts — they map to subcommands of winml. Confirm exact spelling and current flags via winml --help before you write any command.

Outputs are explicit; cache is opaque

Every winml command has a published output — what -o writes or what it prints to stdout — and that is the only thing you can hand to a user or downstream command. What a command does internally (cached intermediate builds, temp graphs, EP context blobs in a private folder) is not a supported output. Don't try to fish artifacts out of cache, don't assume one command's internal byproducts can feed another.

This is the easiest way to pick the right command for a goal: map the goal to a published output, not to a side effect.

• inspect, sys, analyze, catalog print to stdout (no -o artifact).
• export, optimize, quantize, compile, build write transformed model artifacts to -o.
• perf writes a metrics JSON to -o — not a model.
• config writes the config JSON to -o — the input to build.

When you find yourself thinking "command X probably builds something internally that I can grab" — stop. You've picked the wrong entry point. Use the command whose published output is the thing you actually want.

One concrete failure this guards against: perf builds an artifact internally to benchmark it, but only the metrics JSON is published; the build lives in cache and is opaque. If a user wants both a deployable model and a latency number, perf alone won't get them the model, and chaining perf → build → perf just pays the build cost twice — the first perf produced nothing they could keep. The right shape is to enter at the command whose -o is the artifact (build), then run perf against that artifact for the number.

The same logic applies wherever a goal doesn't match a command's published output: inspect's JSON isn't a build input (use config); analyze's linter output isn't a graph rewrite (use a different optim/quant config); and so on.

The golden rule: inspect first

Before any other command, run the inspect subcommand on the user's model. Per winml inspect --help, it reads the model configuration without downloading weights and shows the loader, exporter, WinML inference class, I/O specs, and the build resolution the pipeline will use. Pass -f json for machine-readable output.

Inspect tells you whether the toolkit knows how to handle the architecture. But always cross-check against the scope section below — a model that inspect accepts can still be out of scope. The scope rule overrides anything inspect prints; for example, an LLM may have a usable loader/exporter via TasksManager defaults but is still not a fit.

Skipping inspect and jumping to export or build is the most common cause of confusing failures three stages in, because the cost of finding out a model is unsupported climbs at every later stage.

Choosing a path

Once inspect passes, pick one of two paths based on what the user is trying to do. Default to config + build unless the user explicitly wants to fiddle with a single stage.

Primitive commands — one stage at a time. Right when the user is exploring, debugging a specific stage, or tweaking settings between runs. They get fine-grained control at the cost of running more commands.

Config + build — two commands for the whole thing. Right when the user wants a clean, reproducible, end-to-end build for production, CI, or sharing with a teammate. The generated config is the single source of truth — they edit it to override defaults, version-control it, and replay deterministically.

If the user is unsure, default to config + build unless they say "I want to try different settings" or "something failed and I need to debug a specific stage."

Mapping "I want to run X" to a command

"I want to run resnet" / "can I try this model" / "let me use this on my NPU" is the most common ambiguous prompt. Apply the published-output rule from the previous section: figure out what the user actually wants, then pick the command whose -o is that thing.

If the user's intent isn't clear from their prompt, ask one short question — "do you want a usable artifact, or just a latency number?" — before quoting commands.

Hardware and execution providers

The right execution provider depends on the user's hardware. See the README's Supported Hardware table for the current hardware-to-EP matrix and Ready/Planned status — that's the canonical source, and it changes between releases. Don't reproduce the matrix here; it goes stale.

Ground truth for what's actually working on this machine is always winml sys --list-ep. Run it; trust its output over anything else. If the user's hardware needs an EP that isn't in the listed output (whether the README marks it Ready or Planned), recommend CPU or DML as the working fallback rather than pretending the missing EP works.

For exact flag spellings and device-selection options, consult winml <command> --help and winml sys. Don't hardcode flag values from this skill — read them live.

If you don't know what hardware the user has, ask, or run winml sys and read the output.

Common patterns

"Just benchmark this model on my hardware." A single perf invocation against the source model is enough — winml perf builds artifacts on the fly (see --rebuild, --no-use-cache, --no-quantize in winml perf --help). You don't have to chain primitives manually. For live NPU utilization during the run, look for the --monitor flag in winml perf --help.

"What's the latency on NPU vs CPU?" Build once, then run perf twice — once against the EP-compiled artifact on the NPU, once against the optimized (pre-compile) artifact on CPU. Compiled artifacts are tied to the EP they were compiled for, so run the CPU comparison against the pre-compile optimized ONNX, not the compiled NPU artifact.

"Will this model work with my hardware?" Inspect, then analyze. The analyzer's linter classifies every operator as supported / partial / unsupported per EP — that's the cheapest way to find out a build will succeed before paying the full export cost.

"My optimize/quantize step just blew up." Most operator-pattern failures land at these stages even when export succeeded. Re-run analyze against the exported ONNX; the linter will usually name the offending op pattern. Don't hand-edit the ONNX graph — try a different optim or quantization configuration to dodge the unsupported pattern, or escalate to "this model isn't a fit for this EP."

Scope — what's in and what's out

In scope. Classic deep learning models — CNNs, encoders, vision transformers, NLP classifiers, NER, object detection, segmentation. Concretely: ResNet, ViT, Swin, ConvNeXT, BERT, RoBERTa, Table Transformer, SegFormer families. If the user passes one of these, the pipeline is designed to handle it.

Out of scope. Generative and decoder-only architectures: GPT, LLaMA, Phi, Mistral, Stable Diffusion, any seq2seq generator. If a user asks winml to handle one of these, stop and say so — the pipeline will fail mid-way and the error won't always make the cause obvious. LLM support (with LoRA) is on the public roadmap for late 2026; don't pretend it works today.

If you're genuinely unsure whether a model is in scope, the inspect command is the source of truth. Trust its verdict over your guess.

Things that catch people out

• Confirm the target EP is registered before compiling. Run winml sys --list-ep first; if your --ep <foo> isn't in the list, compile won't produce a usable artifact for that EP. Compile also runs validation by default (see --validate / --no-validate in winml compile --help).
• Compile defaults to external EP-context storage. Per winml compile --help, the default writes EP context to a .bin file co-located with the output .onnx; pass --embed to inline it instead. If you move a non-embedded artifact, move the .bin alongside.
• CLI flags override the config file, not the other way around. Every primitive that accepts -c, --config says so in its --help: "Provides defaults; explicit CLI options take precedence." For repeatable builds, edit the JSON; for one-off overrides, pass the flag at build time.
• Output paths are explicit on the pipeline-building commands. export, optimize, quantize, compile, perf, config, and build each take an -o / --output (or --output-dir). There's no implicit "current directory" convention — tell the user where files will land. inspect, sys, analyze, and catalog print to stdout and don't require an output path.
• EP-compiled models are tied to their target EP. Don't try to perf a QNN-compiled artifact against the CPU EP — the result is at best meaningless. For cross-EP comparison, use the pre-compile optimized ONNX.
• Don't fabricate flags. If a flag isn't in winml <command> --help, it doesn't exist. Find a real one or change approach.

When things go sideways

Read the error before suggesting a next step. winml error messages are usually specific (op name, EP, stage). When you don't know what to do:

1. winml <failing-command> --help to confirm you used real flags.
2. winml sys --list-ep to confirm the EP is actually registered on this machine.
3. winml inspect and winml analyze to confirm the model is supported and the operator pattern is buildable.

The CLI is self-documenting; lean on it before guessing.