# schappim/coreml-cli: inspect, run and benchmark Core ML models from the terminal

> A Swift command-line tool for Apple Core ML models on macOS, covering inspection, inference, batch runs, benchmarking, compilation and metadata editing. The last push to master was on 2026-01-21, and the README leaves several questions unanswered.

**schappim/coreml-cli** — A native command-line interface for working with Apple Core ML models on macOS

- Repository: https://github.com/schappim/coreml-cli
- Stars: 103 · Forks: 2
- Language: Swift
- License: MIT
- Published: 2026-08-17 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/schappim-coreml-cli

## The gap coreml-cli fills between Xcode and coremltools

Core ML is Apple's on-device machine learning framework. Models ship as .mlmodel files, which Apple's toolchain compiles into .mlmodelc directories that the runtime loads. Two official routes exist for working with those files: Xcode's model viewer, which is graphical and awkward to script, and coremltools, Apple's Python package. The README positions coreml-cli as a third option: "Inspect, run inference, benchmark, and manage Core ML models without Xcode or Python." That is the whole pitch, and it is a narrow one. The tool is for engineers who already have a .mlmodel or .mlpackage and want to answer questions about it from a shell: what are its inputs and outputs, how fast does it run on this machine, what does its metadata say, and can I fix that metadata without opening a Python environment. It is not a conversion tool, a training tool, or a serving framework. If your model is still a PyTorch checkpoint, coreml-cli has nothing for you, and the README does not pretend otherwise.

## How the commands map onto Core ML's model lifecycle

The command set follows the lifecycle of a model file rather than any internal architecture. coreml inspect reads a model's structure and metadata. coreml predict loads the model and runs a single inference, with a --device flag selecting cpu, gpu, ane (Apple Neural Engine) or all. coreml batch walks a directory, runs inference over every file it finds and writes results to an output directory, with --concurrency controlling how many run at once. coreml benchmark runs repeated inferences with a warmup phase and reports latency percentiles and throughput. coreml compile turns a .mlmodel into an optimized .mlmodelc. coreml meta get and coreml meta set read and write metadata fields. The metadata editing is the one place the README describes an implementation detail: "The model spec is rewritten in place at the protobuf level, no Python or coremltools required." That means the tool manipulates the serialized model specification directly rather than going through a framework API. The README also states that compiled .mlmodelc models are read-only, so metadata changes apply to the source .mlmodel or .mlpackage and then require a recompile. The rest of the pipeline is opaque: the README does not say how models are loaded, whether the compiled form is cached between runs, or what happens when a model's input does not match the supplied file.

## Installing coreml-cli and running your first prediction

The README recommends Homebrew. Two commands tap the repository and install the formula:

```bash
brew tap schappim/coreml-cli
brew install coreml-cli
```

If you prefer a binary, the README points at the GitHub Releases page for v1.0.0 and gives this download path, which unpacks an archive and moves the binary onto your PATH:

```bash
curl -L https://github.com/schappim/coreml-cli/releases/download/v1.0.0/coreml-1.0.0-macos.tar.gz -o coreml.tar.gz
tar -xzf coreml.tar.gz
sudo mv coreml /usr/local/bin/
```

Building from source requires macOS 13 or later and Swift 5.9 or later. The README's build sequence is a release build followed by a copy into /usr/local/bin:

```bash
git clone https://github.com/schappim/coreml-cli.git
cd coreml-cli
swift build -c release
sudo cp .build/release/coreml /usr/local/bin/
```

Whichever route you take, the README's verification step is a version check that should print "coreml 1.0.0":

```bash
coreml --version
```

For a first real use, inspect a model before running it. The README's example is MobileNetV2, and the output it documents shows the model name, file size, whether it is compiled, the input shape (image 224x224 BGRA32), the outputs (classLabel and classLabelProbs) and the metadata block:

```bash
coreml inspect MobileNetV2.mlmodel
```

Then run one image through it. The README's example reports an inference time and prints the top label with its probability:

```bash
coreml predict MobileNetV2.mlmodel --input photo.jpg
```

Adding --json to either command produces machine-readable output, which is the form you want inside a script.

## Batch runs and benchmarking, and where the numbers come from

The batch command is the one most likely to end up in a pipeline. The README's example processes a directory of images and writes a CSV:

```bash
coreml batch MobileNetV2.mlmodel --dir ./photos --out ./results --format csv
```

Its documented output reports how many input files were found, where results were written, total wall time and average inference time per file. Concurrency is set with --concurrency, and the README's example uses 8. Note what the README does not say: there is no documented resume behaviour, no statement about what happens when one file in the directory fails, and no list of which --format values are accepted beyond the csv shown. Benchmarking is more explicit. The README documents a warmup phase, a default of 100 iterations and 10 warmup runs, and output split into mean, min, max and standard deviation plus P50, P95 and P99 percentiles and a throughput figure. Iteration count and warmup are configurable:

```bash
coreml benchmark MobileNetV2.mlmodel --input sample.jpg -n 500 --warmup 50
```

The --json flag makes the benchmark output suitable for CI, and the README's own example pipes it through jq to pull out a meanLatencyMs field. Treat these numbers as measurements of one machine at one moment. The README gives no guidance on thermal state, background load or how the device flag interacts with the reported figures, and a single-image benchmark says nothing about how the model behaves on a varied input set.

## Metadata editing is the most distinctive feature and the least documented

Most of what coreml-cli does, coremltools can also do. Editing metadata at the protobuf level without a Python environment is the part that stands out, and it is the part where the README raises the most questions. The four fields are author, description, license and version:

```bash
coreml meta set MobileNetV2.mlmodel author "Jane Doe"
coreml meta set MobileNetV2.mlmodel license ""
coreml meta set MobileNetV2.mlmodel author "Jane" --output MobileNetV2-attributed.mlmodel
```

The first sets a field, the second clears one by passing an empty string, and the third writes to a new file instead of overwriting the source. For .mlpackage inputs, the README states that --output clones the entire package directory and writes the modified spec inside the clone. That is a sensible default, but the README does not describe how the clone handles large packages, whether symlinks or extended attributes survive, or what happens if the output path already exists. It also does not document rollback. If a metadata write corrupts a model, the README offers no recovery path beyond keeping your own copy, which is exactly why the --output form is worth using by default rather than editing in place. And because compiled .mlmodelc models are read-only, any metadata change on a deployed model means editing the source and recompiling with coreml compile.

## What coreml-cli does not do, and what to use instead

The clearest limitation is conversion. One of the most common questions people search for around Core ML is how to convert a PyTorch model, and coreml-cli cannot help: the README describes no conversion command, and the tool works only with models that are already in Core ML format. For that job the alternative is coremltools, Apple's Python package. The difference in approach is substantial. coreml-cli is a compiled Swift binary that operates on model files as artifacts: it reads, runs, compiles and rewrites them. coremltools is a Python library that works on models as objects in a program, which is what you need to trace a PyTorch graph, set input shapes, run shape inference and emit a .mlmodel in the first place. The two are complementary rather than competing, and a realistic workflow uses coremltools to produce the model and coreml-cli to inspect, benchmark and annotate it afterwards. The second limitation is platform. The README's install paths are Homebrew on macOS, a macOS tarball and a source build requiring macOS 13 or later, so there is no Linux or Windows story. If your inference runs in a container on a Linux host, this tool is not part of that pipeline. A third limitation is input coverage: the README lists four supported input types (image extensions .jpg, .jpeg, .png and .heic; .wav audio; .txt text; .json tensors), and a model expecting anything else is outside what the documentation covers.

## Maintenance, licence and the cost of upgrading

The repository is not archived. The last push to master was on 2026-01-21, which is the same timestamp as the v1.0.0 release, so the published release and the current state of master coincide. There is a CHANGELOG.md in the repository root, but its contents are not documented in the README, so how changes are recorded between versions cannot be confirmed here. The licence is MIT. That is permissive: it allows use, modification and redistribution provided the copyright notice and permission notice are retained, and it comes with no warranty. It does not, by itself, settle the licensing of the models you process with the tool; a model's own licence field is metadata you can read with coreml meta get and edit with coreml meta set, and editing it changes the file, not the legal terms attached to the weights. On upgrade cost, the surface is small: seven commands, a handful of global flags, and a metadata writer that touches the model spec directly. The risk concentrates in that last part. A change to how the protobuf rewrite handles a given model format would be the kind of thing you would want to catch before it reaches a production model, which argues for running metadata edits against a copy and diffing the result.

## Conclusion

Adopt coreml-cli if you work with .mlmodel or .mlpackage files on macOS and want inspection, single-image inference, batch runs, benchmarking or metadata edits from a shell script, without opening Xcode or writing Python. Do not adopt it if you need to convert a PyTorch checkpoint to Core ML, train anything, or run inference on Linux and Windows, because the README covers none of those and the binary is macOS-only. Before relying on it in a pipeline, verify that your model's input type is one of the four the README lists (image, .wav audio, .txt text, .json tensors), that the metadata rewrite behaves as expected when you run coreml meta set with --output on a copy of the model, and that the --device ane result matches what you get from --device cpu on the same input. The last push to master was on 2026-01-21, so check the repository yourself before you build a long-lived dependency on it.

## FAQ

### What is Core ML and what does coreml-cli do with it?

Core ML is Apple's framework for running machine learning models on device, with models stored as .mlmodel files that compile into .mlmodelc. coreml-cli is a macOS command-line tool that inspects, runs, benchmarks, compiles and edits the metadata of those models without Xcode or Python.

### How do I convert a PyTorch model to Core ML with coreml-cli?

You cannot. coreml-cli works only with models that are already in Core ML format, and the README describes no conversion command. Converting from PyTorch is the job of coremltools, Apple's Python package; coreml-cli takes over once you have a .mlmodel or .mlpackage.

### How do I install coreml-cli?

The README recommends Homebrew: run brew tap schappim/coreml-cli followed by brew install coreml-cli. Alternatively you can download the v1.0.0 macOS tarball from GitHub Releases, or build from source with swift build -c release, which requires macOS 13 or later and Swift 5.9 or later.

### Which input file types does coreml-cli accept?

The README lists four: images with the extensions .jpg, .jpeg, .png and .heic for Vision models, .wav for sound classification, .txt for NLP models, and .json for custom tensor models.

### Can I change a model's metadata without coremltools?

Yes. coreml meta set rewrites the model spec at the protobuf level, and the README documents four editable fields: author, description, license and version. Compiled .mlmodelc models are read-only, so you edit the source .mlmodel or .mlpackage and recompile with coreml compile.

## Sources

- [Official README](https://github.com/schappim/coreml-cli#readme)
- [Project repository](https://github.com/schappim/coreml-cli)
- [Release notes](https://github.com/schappim/coreml-cli/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/schappim-coreml-cli