This PR implements a new hf CLI tool to replace the existing huggingface-cli with a more modern and consistent syntax, similar to the GitHub CLI. The new CLI maintains 100% backward compatibility while providing a cleaner interface.

New CLI Structure

The new hf CLI organizes commands into logical groups:

# Authentication commands
hf auth login
hf auth logout
hf auth switch
hf auth list
hf auth whoami

# Repository commands
hf repo create
hf repo tag create/delete/list

# File management commands
hf files download
hf files upload
hf files delete

# Cache management commands
hf cache scan
hf cache delete

# Utility commands
hf version
hf env

# Convenient aliases
hf download  # alias for hf files download
hf upload    # alias for hf files upload

Implementation Details

• New CLI directory: Created src/huggingface_hub/cli/ with modular command structure
• Entry point: Added hf=huggingface_hub.cli.hf_cli:main to setup.py
• Backward compatibility: All existing huggingface-cli commands continue to work unchanged
• Deprecation warnings: Old commands show yellow warnings pointing to new syntax
• Code reuse: New CLI reuses existing command implementations for consistent behavior
• Legacy support: Included specialized commands like lfs-enable-largefiles and upload-large-folder

Examples

Before (old CLI)

huggingface-cli login --token=hf_***
huggingface-cli download gpt2 config.json
huggingface-cli scan-cache
huggingface-cli tag create my-model v1.0

After (new CLI)

hf auth login --token=hf_***
hf files download gpt2 config.json
hf cache scan
hf repo tag create my-model v1.0

Testing

• Added comprehensive test suite covering all command parsing scenarios
• All existing tests continue to pass
• Verified deprecation warnings work correctly
• Confirmed new CLI provides same functionality without warnings

Migration Path

Users can gradually migrate to the new CLI at their own pace:

• Old commands work exactly as before but show helpful deprecation warnings
• New commands provide the same functionality with cleaner syntax
• No breaking changes to existing workflows

Fixes #3224.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.