feat(higgs): migrate from huggingface-cli to hf

[vdorokhin]

Summary

This PR migrates all references from huggingface-cli to hf.
The upstream huggingface-cli was renamed to hf.

➜  brew install panbanda/brews/higgs
Inspect the formula dependency plan before installing with `brew install --ask`.
Enable ask mode by setting `HOMEBREW_ASK=1`.
Hide these hints with `HOMEBREW_NO_ENV_HINTS=1` (see `man brew`).
==> Fetching downloads for: higgs
Warning: Formula huggingface-cli was renamed to hf.
Warning: Formula huggingface-cli was renamed to hf.
✔︎ Formula higgs (1.3.0) ... Verified     44.0MB/ 44.0MB
==> Installing higgs from panbanda/brews
Warning: Formula huggingface-cli was renamed to hf.
Warning: Formula huggingface-cli was renamed to hf.
🍺  /opt/homebrew/Cellar/higgs/1.3.0: 5 files, 141.3MB, built in 1 second
==> Running `brew cleanup higgs`...
Disable this behaviour by setting `HOMEBREW_NO_INSTALL_CLEANUP=1`.
Hide these hints with `HOMEBREW_NO_ENV_HINTS=1` (see `man brew`).

The old CLI still installs but produces a deprecation warning, and the huggingface-cli binary no longer works at all — it exits with code 1 and prints:

➜  ~ huggingface-cli download mlx-community/Qwen3.6-35B-A3B-4bit
Warning: `huggingface-cli` is deprecated and no longer works. Use `hf` instead.

Hint: `hf` is already installed! Use it directly.

Hint: Examples:
  hf auth login
  hf download unsloth/gemma-4-31B-it-GGUF
  hf upload my-cool-model . .
  hf models ls --search "gemma"
  hf repos ls --format json
  hf jobs run python:3.12 python -c 'print("Hello!")'
  hf --help

➜  ~ echo $?
1

This means higgs serve --model <id> on a cold cache is broken for anyone relying on automatic download via huggingface-cli.

➜  higgs serve --model nvidia/dvlt
2026-06-04T08:37:02.799587Z  INFO higgs: Resolving model path model=nvidia/dvlt
Model 'nvidia/dvlt' not found in HuggingFace cache. Download now? [y/N] y
Warning: `huggingface-cli` is deprecated and no longer works. Use `hf` instead.
                                                                                                                                                                                                                                  
Hint: `hf` is already installed! Use it directly.
                                                                                                                                                                                                                                  
Hint: Examples:
  hf auth login                                                                                                                                                                                                                   
  hf download unsloth/gemma-4-31B-it-GGUF                                                                                                                                                                                         
  hf upload my-cool-model . .                                                                                                                                                                                                     
  hf models ls --search "gemma"                                                                                                                                                                                                   
  hf repos ls --format json                                                                                                                                                                                                       
  hf jobs run python:3.12 python -c 'print("Hello!")'                                                                                                                                                                             
  hf --help                                                                                                                                                                                                                       
                                                                                                                                                                                                                                  
Error: "huggingface-cli download failed for 'nvidia/dvlt'"

Verification

• cargo test -- --test-threads=1
• cargo clippy
• cargo fmt --check
• cargo build --release and download a model

➜  ./higgs serve --model nvidia/dvlt
2026-06-04T08:37:37.989539Z  INFO higgs: restored mlx.metallib next to executable from Cargo build output source=/target/release/build/mlx-sys-2132f80883b99581/out/build/lib/mlx.metallib destination=/target/release/mlx.metallib
2026-06-04T08:37:37.989698Z  INFO higgs: Resolving model path model=nvidia/dvlt
Model 'nvidia/dvlt' not found in HuggingFace cache. Download now? [y/N] y
Downloading (incomplete total...): 0.00B [00:00, ?B/s]
Warning: You are sending unauthenticated requests to the HF Hub. Please set a HF_TOKEN to enable higher rate limits and faster downloads.                                                                   | 0/5 [00:00<?, ?it/s]
Fetching 5 files: 100%|█| 5/5 [00:20<00:00,  4.16s/it]
Download complete: 100%|█| 468M/468M [00:20<00:00, 30.2MB/s]✓ Downloaded  

Note: nvidia/dvlt random small model just for local check of download process

---

Summary by CodeRabbit

• Chores

  • Replaced references to the old HuggingFace CLI with the new hf command across downloads, install hints, and generated Homebrew formula.

• Tests

  • Added an integration test to verify the serve command surfaces the new hf download <model> guidance on failure.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR replaces uses of huggingface-cli with hf: the download fallback in code now invokes hf download, user-facing help/errors and tests were updated to mention hf download, an integration test was added, and the Homebrew formula dependency was changed to depends_on "hf".

Changes

HuggingFace CLI Tool Migration

Layer / File(s)	Summary
CLI tool invocation update crates/higgs/src/main.rs	The HF model download fallback now calls a download_via_hf_cli helper that runs hf download <model_path> and maps spawn/failure cases to brew install hf and hf download failed for '<model_path>'.
User guidance and test validation crates/higgs/src/model_download.rs	Rustdoc and non-interactive error messages updated to hf download {model_id}; unit tests updated to assert the new hint and exact command substring.
Integration test for serve fallback crates/higgs/tests/integration/cli_serve.rs, crates/higgs/tests/integration/mod.rs	Adds an integration test that runs higgs serve --model test/non-cached-hf-model, expects failure, and asserts stderr contains run: hf download test/non-cached-hf-model.
Homebrew release configuration .github/workflows/release.yml	Generated Homebrew formula now declares depends_on "hf" instead of depends_on "huggingface-cli".

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

risk: medium

"A rabbit hops to update the trail,
small paws tap a new hf tale.
Commands now whisper short and spry,
hf download beneath the sky.
Brew pours the cup — hop, compile, and smile."

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: migrating the codebase from using the deprecated huggingface-cli to the renamed hf CLI tool, which is the core objective of this PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}