[Whq02]

What this changes

tensorfold models prints one line a checkpoint and takes no argument, so a program that wants the inventory parses the
lines or reads the Hugging Face cache itself. On main at 53311e7 (and in 1.2.2 and 1.2.3):

$ tensorfold models --json
usage: tensorfold models
       tensorfold info MODEL
       tensorfold pull REPO[@REVISION]
       tensorfold pull REPO[@REVISION] --exlr8 PROFILE --node R/N --dir DIR
       tensorfold plan MODEL [--memory-gb GIB] [--ram GB]...
       tensorfold merge MODEL ADAPTER OUT
       tensorfold merge DENSE ADAPTER OUT --quantize SHIPPED
$ echo $?
2

After this change models --json prints the same checkpoints as one document, in the shape capabilities --json uses
(here a cache holding the 2B and the 27B):

$ tensorfold models --json
{"schema":1,"models":[{"repo":"mlx-community/Qwen3.5-2B-MLX-4bit","family":"Qwen3.5-2B or Qwen3.8-27B","model_type":"qwen3_5"},{"repo":"TensorFold/Qwen3.8-27B-MLX-4bit","family":"Qwen3.5-2B or Qwen3.8-27B","model_type":"qwen3_5"}]}

Each entry is the line's repo, family and model_type, nothing the lines don't print. A cache that does not exist yet
answers {"schema":1,"models":[]} with exit 0, as the lines exit 0 with their hint. The lines are unchanged, and any
other word after models is still the usage with exit 2. The README's Models on disk section names the flag; where it
goes is your call.

Mercury CLI integrates TensorFold as a model source and hit this: it reads the cache directory itself to list what
tensorfold serve can serve.

• Issue: n/a: no issue filed; the failing command and its output are above.
• Stacked on: main (5daafaf), one commit (rebased from 53311e7 for the review asks; patch-id unchanged).
• atc overlap --json: run 2026-11-06T15:49:35Z on this head against origin/main at 5daafaf (ATC 0.9.0). changedFiles 5; the conflicts named are CHANGELOG.md only, with the other open PRs that add a line under Unreleased (server: a refused API key file logs the path and the mode it read #2365 among them); README.md, cli.zig, models.zig and main.zig overlap no open PR (each named head test-merged with git merge-tree).

Checks on this head

• Head commit: 282e5b0
• Lean checker, python3 tools/zig/lean_check.py, on the base and on this head: 252 on 5daafaf, 252 on this head, 0 new (tools/zig/lean_new.py: "lean: 252 problems, 252 on the base, 0 new"; the 252 are inherited, and the checker exits 1 on both for them).
• Tests run, with the command and pass, fail and skip counts:
  • zig/src/cli/tests.zig, the CLI test module, compiled against the host registry (the zig test line zig build test-cli-memory-host --verbose prints, without its three --test-filters and --listen=-): 52 pass, 0 fail, 0 skip on this head; 51 on the base. The new test, models --json prints the listed checkpoints as one document, and an absent cache as none, does not compile against the base's models.run (zig/src/cli/models.zig:61:22: error: expected 5 argument(s), found 6, and :77:49), so it is red there by construction; the lines test keeps passing. zig build test-cli-memory-host itself: 15/15 on the base and on this head; its filters do not reach the two models tests.
  • zig build test-golden --summary all: 5/5 steps, 322/335 and 55/55 equal to the server goldens, 0 unexpected differences (the 13 are its recorded known differences).
  • zig fmt --check build.zig zig and git diff --check: clean.
  • The Linux aarch64 tensorfold from zig build install -Dtarget=aarch64-linux-gnu ran the commands above against a real cache of four checkpoints: the lines and the document agree entry for entry, an absent cache prints {"schema":1,"models":[]} with exit 0, and models --json --x is the usage with exit 2. The install step itself exits 1 on this head and on main alike (28/31 steps, tensorfold installed): tf-qwen35-cuda does not compile on main, zig/tests/qwen35_cuda_main.zig:259 passing saveCache four arguments where it takes five since 443e867; not from this change.
• CI: runs on push; the quick checks (zig fmt, lean) pass locally.
• Not run, and why: zig build test and zig build test-cli on macOS, which compile the Metal shaders; the build host has no Metal toolchain, so the CLI module ran from the host registry build instead (the same cli/tests.zig root; hub.family reads the registry's families either way). zig build dev-tools for the same reason; models.run has one caller, cli.zig, and no tf-* tool calls it.

Receipt

n/a: a CLI listing, nothing reaches inference.

Checklist

• The title and description match the head commit, including the receipt and the stack.
• New tests fail before the change, pass after it, and skip cleanly without their dependency.
• Comments and docstrings are one line. No measurements or history in the source.
• No personal data, machine names, internal hosts or local paths in the diff or its commits. No AI attribution lines.

[ashhart]

Thanks @Whq02, this is a clean addition:

• The plain models output is unchanged.
• schema: 1 matches capabilities --json.
• The empty-cache document with exit 0 matches the lines.
• The README spot is fine.

Two small things:

1. A CHANGELOG line under Unreleased, e.g. "CLI: tensorfold models --json prints the cached checkpoints as one document (schema 1, each checkpoint's repo, family and model_type); the lines are unchanged (cli: tensorfold models --json, the listed checkpoints as one document #2364). Thanks to @Whq02."
2. Optional: the native binary's usage text (zig/src/server/main.zig:60 and :90) still says models. models [--json] there would match cli.zig. In the README sentence it may also help to say that family is a display title and model_type is the key to match on.

[Whq02]

Done as one commit on 5daafaf, 282e5b0: your CHANGELOG line under Unreleased, models [--json] in both usage strings of zig/src/server/main.zig, and the README sentence now says family is a display title and model_type the key to match on.

On that tip: zig fmt --check and git diff --check clean, lean 252 on base and head (0 new), test-golden 322/335 and 55/55 equal with 0 unexpected, the CLI module 52/52, the engine-less tensorfold-native --help shows the new usage, and a Linux build's models and models --json agree entry for entry on a cache of four checkpoints. atc overlap after the rebase: the only conflicts are in CHANGELOG.md with the other open PRs that add a line under Unreleased (#2365 among them) — whichever lands second takes a one-line re-place.

[ashhart]

Thanks @Whq02, all three are in: the CHANGELOG line, models [--json] in both native usage strings, and the README note on family and model_type. Ready to land. If #2365 lands first, the CHANGELOG line needs a one-line re-place under Unreleased, which we'll do at landing.