Upload folder using huggingface_hub

.gitattributes

@@ -92,3 +92,5 @@ venv/Lib/site-packages/h5py/hdf5_hl.dll filter=lfs diff=lfs merge=lfs -text
 venv/Lib/site-packages/h5py/tests/__pycache__/test_dataset.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text
 venv/Lib/site-packages/hf_xet/hf_xet.pyd filter=lfs diff=lfs merge=lfs -text
 venv/Lib/site-packages/huggingface_hub/__pycache__/hf_api.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text
+venv/Lib/site-packages/huggingface_hub/inference/__pycache__/_client.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text
+venv/Lib/site-packages/huggingface_hub/inference/_generated/__pycache__/_async_client.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text

venv/Lib/site-packages/huggingface_hub/cli/_city_game.py

@@ -0,0 +1,661 @@
+"""Interactive isometric city explorer — easter egg for `hf repos ls --explore`."""
+
+import dataclasses
+import math
+import os
+import random
+import re
+import select
+import shutil
+import sys
+import time
+
+from huggingface_hub.hf_api import RepoStorageInfo
+
+from ._file_listing import format_size
+
+
+Color = tuple[int, int, int]
+
+# (top_face, left_face, right_face) — lighter to darker for 3D effect
+_TYPE_COLORS: dict[str, tuple[Color, Color, Color]] = {
+    "model": ((175, 148, 240), (138, 112, 208), (105, 80, 180)),
+    "dataset": ((245, 128, 128), (222, 92, 92), (190, 60, 60)),
+    "space": ((245, 175, 85), (218, 140, 55), (185, 110, 30)),
+    "bucket": ((112, 185, 242), (70, 150, 220), (40, 118, 192)),
+}
+_EXTRA_COLORS: tuple[Color, Color, Color] = ((168, 176, 188), (128, 136, 148), (90, 98, 110))
+_GRID_COLOR: Color = (178, 182, 190)
+
+_DX = 4  # isometric half-width (pixels)
+_DY = 2  # isometric half-height (pixels)
+_MAX_H = 16  # tallest tile (pixels)
+_MIN_H = 1
+_COLS = 6
+_EXT = 1  # grid extension beyond tiles
+_MAX_TILES = 30
+
+# Cursor sprite — pixel art arrow pointer
+_OUTLINE: Color = (30, 30, 30)
+_FILL: Color = (255, 255, 255)
+
+_CURSOR_GRID = [
+    "  X  ",
+    " XWX ",
+    "XWWWX",
+    " XWX ",
+    "  X  ",
+]
+_CURSOR_PALETTE: dict[str, Color] = {
+    "X": _OUTLINE,
+    "W": _FILL,
+}
+_CURSOR_H = len(_CURSOR_GRID)
+
+_MOVE_FRAMES = 8
+_MOVE_DELAY = 0.03
+_CURSOR_PAD = _CURSOR_H + 16
+_GAP = 3
+_MIN_TERM_W = 100
+_MIN_TERM_H = 24
+_SUMMARY_W = 24
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+
+@dataclasses.dataclass
+class TileInfo:
+    grid_row: int
+    grid_col: int
+    height: int
+    top: Color
+    left: Color
+    right: Color
+    repo: RepoStorageInfo | None
+
+
+@dataclasses.dataclass
+class CityData:
+    tiles: list[TileInfo]
+    rows: int
+    cols: int
+    x_off: int
+    y_off: int
+    buf_w: int
+    buf_h: int
+    total_storage: int
+    extra_count: int
+    extra_storage: int
+    all_repos: list[RepoStorageInfo]
+
+
+# ---------------------------------------------------------------------------
+# City layout
+# ---------------------------------------------------------------------------
+
+
+def _prepare_city_data(repos: list[RepoStorageInfo]) -> CityData:
+    sorted_repos = sorted(repos, key=lambda r: r.storage, reverse=True)
+    display = sorted_repos[:_MAX_TILES]
+    extra_count = max(0, len(sorted_repos) - _MAX_TILES)
+    extra_storage = sum(r.storage for r in sorted_repos[_MAX_TILES:])
+    total_storage = sum(r.storage for r in repos)
+    max_storage = max(1, display[0].storage)
+
+    n = len(display) + (1 if extra_count > 0 else 0)
+    cols = min(n, _COLS)
+    rows = math.ceil(n / cols) if cols > 0 else 1
+
+    tiles: list[TileInfo] = []
+    for i, repo in enumerate(display):
+        r, c = divmod(i, cols)
+        h = max(_MIN_H, round(math.sqrt(repo.storage / max_storage) * _MAX_H))
+        top, left, right = _TYPE_COLORS.get(repo.type, _EXTRA_COLORS)
+        tiles.append(TileInfo(r, c, h, top, left, right, repo))
+    if extra_count > 0:
+        r, c = divmod(len(display), cols)
+        h = max(_MIN_H, round(math.sqrt(extra_storage / max_storage) * _MAX_H))
+        tiles.append(TileInfo(r, c, h, *_EXTRA_COLORS, None))
+
+    r_lo, r_hi = -_EXT, rows - 1 + _EXT
+    c_lo, c_hi = -_EXT, cols - 1 + _EXT
+
+    xs: list[int] = []
+    ys: list[int] = []
+    for rr in range(r_lo, r_hi + 1):
+        for cc in range(c_lo, c_hi + 1):
+            cx, cy = (cc - rr) * _DX, (cc + rr) * _DY
+            xs.extend([cx - _DX, cx + _DX])
+            ys.extend([cy, cy + 2 * _DY])
+    for tile in tiles:
+        ys.append((tile.grid_col + tile.grid_row) * _DY - tile.height)
+
+    x_off = -min(xs)
+    y_off = -min(ys)
+    buf_w = max(xs) - min(xs) + 1
+    buf_h = max(ys) - min(ys) + 1
+    if buf_h % 2:
+        buf_h += 1
+
+    return CityData(
+        tiles=tiles,
+        rows=rows,
+        cols=cols,
+        x_off=x_off,
+        y_off=y_off,
+        buf_w=buf_w,
+        buf_h=buf_h,
+        total_storage=total_storage,
+        extra_count=extra_count,
+        extra_storage=extra_storage,
+        all_repos=repos,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Drawing primitives
+# ---------------------------------------------------------------------------
+
+
+def _draw_diamond_outline(buf: list[list[Color | None]], cx: int, cy: int) -> None:
+    t = (cx, cy)
+    r = (cx + _DX, cy + _DY)
+    b = (cx, cy + 2 * _DY)
+    ll = (cx - _DX, cy + _DY)
+    _draw_line(buf, *t, *r, _GRID_COLOR)
+    _draw_line(buf, *r, *b, _GRID_COLOR)
+    _draw_line(buf, *b, *ll, _GRID_COLOR)
+    _draw_line(buf, *ll, *t, _GRID_COLOR)
+
+
+def _draw_block(
+    buf: list[list[Color | None]],
+    cx: int,
+    cy: int,
+    h: int,
+    top: Color,
+    left: Color,
+    right: Color,
+) -> None:
+    _fill_poly(
+        buf,
+        [(cx - _DX, cy + _DY - h), (cx, cy + 2 * _DY - h), (cx, cy + 2 * _DY), (cx - _DX, cy + _DY)],
+        left,
+    )
+    _fill_poly(
+        buf,
+        [(cx, cy + 2 * _DY - h), (cx + _DX, cy + _DY - h), (cx + _DX, cy + _DY), (cx, cy + 2 * _DY)],
+        right,
+    )
+    _fill_poly(
+        buf,
+        [(cx, cy - h), (cx + _DX, cy + _DY - h), (cx, cy + 2 * _DY - h), (cx - _DX, cy + _DY - h)],
+        top,
+    )
+
+
+def _fill_poly(buf: list[list[Color | None]], verts: list[tuple[int, int]], color: Color) -> None:
+    bh = len(buf)
+    bw = len(buf[0]) if buf else 0
+    all_y = [v[1] for v in verts]
+    y0 = max(0, min(all_y))
+    y1 = min(bh - 1, max(all_y))
+    n = len(verts)
+    for y in range(y0, y1 + 1):
+        xl: float = float("inf")
+        xr: float = float("-inf")
+        for i in range(n):
+            ax, ay = verts[i]
+            bx, by = verts[(i + 1) % n]
+            if ay == by:
+                if y == ay:
+                    xl = min(xl, float(min(ax, bx)))
+                    xr = max(xr, float(max(ax, bx)))
+                continue
+            if not (min(ay, by) <= y <= max(ay, by)):
+                continue
+            t = (y - ay) / (by - ay)
+            ix = ax + t * (bx - ax)
+            xl = min(xl, ix)
+            xr = max(xr, ix)
+        if xl <= xr:
+            for x in range(max(0, round(xl)), min(bw, round(xr) + 1)):
+                buf[y][x] = color
+
+
+def _draw_line(buf: list[list[Color | None]], x0: int, y0: int, x1: int, y1: int, color: Color) -> None:
+    bh = len(buf)
+    bw = len(buf[0]) if buf else 0
+    dx = abs(x1 - x0)
+    dy = abs(y1 - y0)
+    steps = max(dx, dy)
+    if steps == 0:
+        if 0 <= y0 < bh and 0 <= x0 < bw:
+            buf[y0][x0] = color
+        return
+    xi = (x1 - x0) / steps
+    yi = (y1 - y0) / steps
+    fx, fy = float(x0), float(y0)
+    for _ in range(steps + 1):
+        px, py = round(fx), round(fy)
+        if 0 <= py < bh and 0 <= px < bw:
+            buf[py][px] = color
+        fx += xi
+        fy += yi
+
+
+# ---------------------------------------------------------------------------
+# Pixel buffer → terminal
+# ---------------------------------------------------------------------------
+
+_ANSI_RE = re.compile(r"\033\[[0-9;]*m")
+
+
+def _strip_ansi(s: str) -> str:
+    return _ANSI_RE.sub("", s)
+
+
+def _visible_len(s: str) -> int:
+    return len(_strip_ansi(s))
+
+
+def _pixels_to_lines(buf: list[list[Color | None]]) -> list[str]:
+    height = len(buf)
+    width = len(buf[0]) if buf else 0
+    lines: list[str] = []
+    for row in range(0, height, 2):
+        last = -1
+        for col in range(width - 1, -1, -1):
+            top = buf[row][col]
+            bot = buf[row + 1][col] if row + 1 < height else None
+            if top or bot:
+                last = col
+                break
+        if last < 0:
+            lines.append("")
+            continue
+
+        parts: list[str] = []
+        cfg: Color | None = None
+        cbg: Color | None = None
+
+        for col in range(last + 1):
+            top = buf[row][col]
+            bot = buf[row + 1][col] if row + 1 < height else None
+
+            if not top and not bot:
+                if cfg is not None or cbg is not None:
+                    parts.append("\033[0m")
+                    cfg = cbg = None
+                parts.append(" ")
+                continue
+
+            if top and bot and top == bot:
+                nfg, nbg, ch = top, None, "█"
+            elif top and bot:
+                nfg, nbg, ch = bot, top, "▄"
+            elif top:
+                nfg, nbg, ch = top, None, "▀"
+            else:
+                nfg, nbg, ch = bot, None, "▄"  # type: ignore[assignment]
+
+            esc = ""
+            if nfg != cfg:
+                esc += f"\033[38;2;{nfg[0]};{nfg[1]};{nfg[2]}m"
+                cfg = nfg
+            if nbg != cbg:
+                esc += "\033[49m" if nbg is None else f"\033[48;2;{nbg[0]};{nbg[1]};{nbg[2]}m"
+                cbg = nbg
+            parts.append(esc + ch)
+
+        if cfg is not None or cbg is not None:
+            parts.append("\033[0m")
+        lines.append("".join(parts))
+    return lines
+
+
+# ---------------------------------------------------------------------------
+# Rendering
+# ---------------------------------------------------------------------------
+
+
+def _render_base_buffer(city: CityData) -> list[list[Color | None]]:
+    buf: list[list[Color | None]] = [[None] * city.buf_w for _ in range(city.buf_h)]
+
+    for tile in city.tiles:
+        cx = city.x_off + (tile.grid_col - tile.grid_row) * _DX
+        cy = city.y_off + (tile.grid_col + tile.grid_row) * _DY
+        _draw_diamond_outline(buf, cx, cy)
+
+    sorted_tiles = sorted(city.tiles, key=lambda t: (t.grid_row + t.grid_col, t.grid_col))
+    for tile in sorted_tiles:
+        cx = city.x_off + (tile.grid_col - tile.grid_row) * _DX
+        cy = city.y_off + (tile.grid_col + tile.grid_row) * _DY
+        _draw_block(buf, cx, cy, tile.height, tile.top, tile.left, tile.right)
+
+    return buf
+
+
+# ---------------------------------------------------------------------------
+# Summary panel
+# ---------------------------------------------------------------------------
+
+
+def _colored_square(color: Color) -> str:
+    return f"\033[38;2;{color[0]};{color[1]};{color[2]}m■\033[0m"
+
+
+def _build_summary(
+    repos: list[RepoStorageInfo],
+    total_storage: int,
+    extra_count: int,
+) -> list[str]:
+    lines: list[str] = [""]
+    lines.append("  Storage Overview")
+    lines.append("  " + "─" * 16)
+    lines.append(f"  {format_size(total_storage, human_readable=True)} total")
+    lines.append("")
+
+    order = ["model", "dataset", "space", "bucket"]
+    labels = {"model": "Models", "dataset": "Datasets", "space": "Spaces", "bucket": "Buckets"}
+    for rtype in order:
+        group = [r for r in repos if r.type == rtype]
+        if not group:
+            continue
+        storage = sum(r.storage for r in group)
+        sq = _colored_square(_TYPE_COLORS[rtype][0])
+        lines.append(f"  {sq} {labels[rtype]}")
+        lines.append(f"    {len(group)} repos · {format_size(storage, human_readable=True)}")
+        lines.append("")
+
+    if extra_count > 0:
+        sq = _colored_square(_EXTRA_COLORS[0])
+        lines.append(f"  {sq} +{extra_count} more repos")
+
+    return lines
+
+
+# ---------------------------------------------------------------------------
+# Cursor
+# ---------------------------------------------------------------------------
+
+
+def _build_cursor() -> list[tuple[int, int, Color]]:
+    pixels: list[tuple[int, int, Color]] = []
+    for ri, row in enumerate(_CURSOR_GRID):
+        for ci, ch in enumerate(row):
+            if ch in _CURSOR_PALETTE:
+                pixels.append((ci - len(row) // 2, ri - _CURSOR_H + 1, _CURSOR_PALETTE[ch]))
+    return pixels
+
+
+_CURSOR_PIXELS = _build_cursor()
+
+
+# ---------------------------------------------------------------------------
+# Interactive game
+# ---------------------------------------------------------------------------
+
+
+def run_city_game(repos: list[RepoStorageInfo]) -> None:
+    """Launch the interactive city explorer."""
+    if not repos:
+        print("No repositories found.")
+        return
+
+    try:
+        import termios
+        import tty
+    except ImportError:
+        print("Interactive mode requires a Unix-like terminal (Linux/macOS).")
+        return
+
+    if not sys.stdin.isatty() or not sys.stdout.isatty():
+        print("Interactive mode requires a terminal.")
+        return
+
+    term = shutil.get_terminal_size()
+    if term.columns < _MIN_TERM_W or term.lines < _MIN_TERM_H:
+        print(f"Your terminal is {term.columns}×{term.lines} characters.")
+        print(f"Please resize to at least {_MIN_TERM_W}×{_MIN_TERM_H} to explore the city!")
+        return
+
+    city = _prepare_city_data(repos)
+
+    tiles_with_repos = [t for t in city.tiles if t.repo is not None]
+    start_tile = random.choice(tiles_with_repos) if tiles_with_repos else city.tiles[0]
+
+    fd = sys.stdin.fileno()
+    old_settings = termios.tcgetattr(fd)
+    try:
+        tty.setraw(fd)
+        sys.stdout.write("\033[?1049h\033[?25l\033[2J")
+        sys.stdout.flush()
+        _game_loop(city, start_tile.grid_row, start_tile.grid_col)
+    finally:
+        sys.stdout.write("\033[?25h\033[?1049l")
+        sys.stdout.flush()
+        termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+
+
+def _game_loop(city: CityData, cur_row: int, cur_col: int) -> None:
+    tile_map: dict[tuple[int, int], TileInfo] = {(t.grid_row, t.grid_col): t for t in city.tiles}
+    city = dataclasses.replace(city, buf_h=city.buf_h + _CURSOR_PAD, y_off=city.y_off + _CURSOR_PAD)
+    base_buf = _render_base_buffer(city)
+
+    summary = _build_summary(city.all_repos, city.total_storage, city.extra_count)
+
+    # Intro: cursor drops onto starting tile
+    tx, ty = _tile_top_center(city, cur_row, cur_col, tile_map)
+    for i in range(1, _MOVE_FRAMES + 1):
+        t = i / _MOVE_FRAMES
+        t = t * t * (3 - 2 * t)
+        drop_y = ty - 16 * (1 - t)
+        frame = _copy_buf(base_buf)
+        _highlight_tile(frame, city, tile_map[(cur_row, cur_col)])
+        _draw_cursor(frame, tx, round(drop_y))
+        _present(city, frame, tile_map.get((cur_row, cur_col)), summary)
+        time.sleep(_MOVE_DELAY)
+
+    while True:
+        cx, cy = _tile_top_center(city, cur_row, cur_col, tile_map)
+        frame = _copy_buf(base_buf)
+        _highlight_tile(frame, city, tile_map[(cur_row, cur_col)])
+        _draw_cursor(frame, cx, cy)
+        _present(city, frame, tile_map.get((cur_row, cur_col)), summary)
+
+        key = _read_key()
+        if key in ("q", "Q", "esc", "\x03"):
+            return
+
+        dr, dc = _key_to_direction(key)
+        if dr == 0 and dc == 0:
+            continue
+
+        nr, nc = cur_row + dr, cur_col + dc
+        if (nr, nc) not in tile_map:
+            continue
+
+        ex, ey = _tile_top_center(city, nr, nc, tile_map)
+        for i in range(1, _MOVE_FRAMES + 1):
+            t = i / _MOVE_FRAMES
+            t = t * t * (3 - 2 * t)
+            bx = cx + (ex - cx) * t
+            by = cy + (ey - cy) * t
+            frame = _copy_buf(base_buf)
+            _highlight_tile(frame, city, tile_map[(nr, nc)])
+            _draw_cursor(frame, round(bx), round(by))
+            _present(city, frame, tile_map.get((nr, nc)), summary)
+            time.sleep(_MOVE_DELAY)
+
+        cur_row, cur_col = nr, nc
+
+
+def _tile_top_center(city: CityData, row: int, col: int, tile_map: dict[tuple[int, int], TileInfo]) -> tuple[int, int]:
+    tile = tile_map.get((row, col))
+    h = tile.height if tile else 1
+    cx = city.x_off + (col - row) * _DX
+    cy = city.y_off + (col + row) * _DY
+    return cx, cy + _DY - h
+
+
+def _key_to_direction(key: str) -> tuple[int, int]:
+    match key:
+        case "w" | "W" | "\x1b[A":
+            return -1, 0
+        case "s" | "S" | "\x1b[B":
+            return 1, 0
+        case "a" | "A" | "\x1b[D":
+            return 0, -1
+        case "d" | "D" | "\x1b[C":
+            return 0, 1
+        case _:
+            return 0, 0
+
+
+def _draw_cursor(buf: list[list[Color | None]], cx: int, cy: int) -> None:
+    bh = len(buf)
+    bw = len(buf[0]) if buf else 0
+    for dx, dy, color in _CURSOR_PIXELS:
+        px, py = cx + dx, cy + dy
+        if 0 <= py < bh and 0 <= px < bw:
+            buf[py][px] = color
+
+
+def _highlight_tile(buf: list[list[Color | None]], city: CityData, tile: TileInfo) -> None:
+    cx = city.x_off + (tile.grid_col - tile.grid_row) * _DX
+    cy = city.y_off + (tile.grid_col + tile.grid_row) * _DY
+    h = tile.height
+    _fill_poly(
+        buf,
+        [(cx, cy - h), (cx + _DX, cy + _DY - h), (cx, cy + 2 * _DY - h), (cx - _DX, cy + _DY - h)],
+        _brighten(tile.top, 35),
+    )
+
+
+def _brighten(color: Color, amount: int) -> Color:
+    return (min(255, color[0] + amount), min(255, color[1] + amount), min(255, color[2] + amount))
+
+
+def _present(
+    city: CityData,
+    buf: list[list[Color | None]],
+    tile: TileInfo | None,
+    summary: list[str],
+) -> None:
+    city_lines = _pixels_to_lines(buf)
+    while city_lines and not _strip_ansi(city_lines[0]).strip():
+        city_lines.pop(0)
+    while city_lines and not _strip_ansi(city_lines[-1]).strip():
+        city_lines.pop()
+
+    city_w = max((_visible_len(line) for line in city_lines), default=0)
+    term = shutil.get_terminal_size()
+    panel_max_w = max(20, term.columns - city_w - _SUMMARY_W - 2 * _GAP)
+
+    info = _build_info_panel(tile, city, panel_max_w)
+
+    n = max(len(summary), len(city_lines), len(info))
+    summary_lo = max(0, (n - len(summary)) // 2)
+    info_lo = max(0, (n - len(info)) // 2)
+
+    lines: list[str] = []
+    for i in range(n):
+        si = i - summary_lo
+        lt = summary[si] if 0 <= si < len(summary) else ""
+        lpad = max(0, _SUMMARY_W - _visible_len(lt))
+
+        ct = city_lines[i] if i < len(city_lines) else ""
+        cpad = max(0, city_w - _visible_len(ct))
+
+        ri = i - info_lo
+        rt = info[ri] if 0 <= ri < len(info) else ""
+
+        lines.append(lt + " " * lpad + " " * _GAP + ct + " " * cpad + " " * _GAP + rt)
+
+    lines.append("")
+    lines.append("  \033[90mWASD/Arrows: move · Q/ESC: quit\033[0m")
+
+    while len(lines) < term.lines - 1:
+        lines.append("")
+
+    output = "\033[H"
+    for line in lines[: term.lines - 1]:
+        output += line + "\033[K\r\n"
+    sys.stdout.write(output)
+    sys.stdout.flush()
+
+
+def _build_info_panel(tile: TileInfo | None, city: CityData, max_w: int) -> list[str]:
+    reset = "\033[0m"
+    gray = "\033[90m"
+    bold = "\033[1m"
+    indent = "  "
+    content_w = max_w - len(indent)
+
+    lines: list[str] = [""]
+    lines.append(f"{indent}{bold}City Explorer{reset}")
+    lines.append(indent + "─" * min(22, content_w))
+    lines.append("")
+
+    if tile is None:
+        lines.append(f"{indent}{gray}Move to a tile")
+        lines.append(f"{indent}to see details.{reset}")
+        return lines
+
+    if tile.repo is None:
+        lines.append(f"{indent}{gray}+{city.extra_count} more repos{reset}")
+        lines.append(f"{indent}{gray}{format_size(city.extra_storage, human_readable=True)} combined{reset}")
+        return lines
+
+    repo = tile.repo
+    name = repo.id
+    if len(name) > content_w:
+        name = name[: content_w - 3] + "..."
+    lines.append(f"{indent}{bold}{name}{reset}")
+    lines.append("")
+
+    type_ansi = {
+        "model": "\033[38;2;175;148;240m",
+        "dataset": "\033[38;2;245;128;128m",
+        "space": "\033[38;2;245;175;85m",
+        "bucket": "\033[38;2;112;185;242m",
+    }
+    tc = type_ansi.get(repo.type, "")
+
+    lines.append(f"{indent}Type       {tc}{repo.type}{reset}")
+    lines.append(f"{indent}Visibility {repo.visibility}")
+    lines.append(f"{indent}Storage    {format_size(repo.storage, human_readable=True)}")
+    lines.append(f"{indent}Usage      {repo.storage_percent:.1f}%")
+    lines.append("")
+
+    bar_w = min(18, content_w)
+    filled = max(0, min(bar_w, round(repo.storage_percent / 100 * bar_w)))
+    lines.append(f"{indent}{tc}{'█' * filled}{gray}{'░' * (bar_w - filled)}{reset}")
+
+    return lines
+
+
+def _copy_buf(buf: list[list[Color | None]]) -> list[list[Color | None]]:
+    return [row[:] for row in buf]
+
+
+def _read_key() -> str:
+    fd = sys.stdin.fileno()
+    ch = os.read(fd, 1)
+    if ch == b"\x1b":
+        if _has_input(fd, 0.05):
+            ch2 = os.read(fd, 1)
+            if ch2 == b"[" and _has_input(fd, 0.05):
+                ch3 = os.read(fd, 1)
+                return f"\x1b[{ch3.decode()}"
+        return "esc"
+    return ch.decode("utf-8", errors="replace")
+
+
+def _has_input(fd: int, timeout: float) -> bool:
+    r, _, _ = select.select([fd], [], [], timeout)
+    return bool(r)

venv/Lib/site-packages/huggingface_hub/cli/_cli_utils.py

@@ -0,0 +1,1068 @@
+# Copyright 2022 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains CLI utilities (styling, helpers)."""
+
+import difflib
+import importlib.metadata
+import os
+import re
+import subprocess
+import sys
+import time
+from collections.abc import Callable, Sequence
+from enum import Enum
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated, Any, Literal, TypeVar, cast
+
+import click
+import typer
+from typer.core import TyperCommand, TyperGroup
+
+from huggingface_hub import Volume, __version__, constants
+from huggingface_hub.errors import CLIError
+from huggingface_hub.utils import (
+    get_session,
+    hf_raise_for_status,
+    installation_method,
+    logging,
+    parse_hf_mount,
+)
+from huggingface_hub.utils._dotenv import load_dotenv
+
+from ._help_formatter import StyledContext
+from ._output import OutputFormat, out
+
+
+logger = logging.get_logger()
+
+# Arbitrary default limit for models/datasets/spaces list commands.
+REPO_LIST_DEFAULT_LIMIT = 30
+
+if TYPE_CHECKING:
+    from huggingface_hub.hf_api import HfApi
+
+
+def get_hf_api(token: str | None = None) -> "HfApi":
+    # Import here to avoid circular import
+    from huggingface_hub.hf_api import HfApi
+
+    return HfApi(token=token, library_name="huggingface-cli", library_version=__version__)
+
+
+#### TYPER UTILS
+
+CLI_REFERENCE_URL = "https://huggingface.co/docs/huggingface_hub/en/guides/cli"
+
+
+def generate_epilog(examples: list[str], docs_anchor: str | None = None) -> str:
+    """Generate an epilog with examples and a Learn More section.
+
+    Args:
+        examples: List of example commands (without the `$ ` prefix).
+        docs_anchor: Optional anchor for the docs URL (e.g., "#hf-download").
+
+    Returns:
+        Formatted epilog string.
+    """
+    docs_url = f"{CLI_REFERENCE_URL}{docs_anchor}" if docs_anchor else CLI_REFERENCE_URL
+    examples_str = "\n".join(f"  $ {ex}" for ex in examples)
+    return f"""\
+Examples
+{examples_str}
+
+Learn more
+  Use `hf <command> --help` for more information about a command.
+  Read the documentation at {docs_url}
+"""
+
+
+TOPIC_T = Literal["main", "help"] | str
+FallbackHandlerT = Callable[[list[str], set[str]], int | None]
+ExpandPropertyT = TypeVar("ExpandPropertyT", bound=str)
+
+
+def _format_epilog_no_indent(epilog: str | None, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+    """Write the epilog without indentation."""
+    if epilog:
+        formatter.write_paragraph()
+        for line in epilog.split("\n"):
+            formatter.write_text(line)
+
+
+_ALIAS_SPLIT = re.compile(r"\s*\|\s*")
+
+
+class HFCliTyperGroup(TyperGroup):
+    """
+    Typer Group that:
+    - lists commands alphabetically within sections.
+    - separates commands by topic (main, help, etc.).
+    - formats epilog without extra indentation.
+    - supports aliases via pipe-separated names (e.g. ``name="list | ls"``).
+    - consumes the global formatting flags (``--format``, ``--json``, ``-q`` / ``--quiet``, ``--no-truncate``)
+      anywhere in the args of a leaf command and applies them to ``out``, so leaf
+      commands don't need to declare these options themselves.
+    - rewrites ``spaces/user/repo`` to ``user/repo --type space`` for commands that accept ``--type``.
+    - enriches "No such option" / "No such command" errors with available options or commands.
+    """
+
+    context_class = StyledContext
+
+    def invoke(self, ctx: click.Context) -> None:
+        """Enrich unknown-option errors with available options or subcommands.
+
+        Catches `NoSuchOption` raised during subcommand `make_context()`
+        (option parsing).  For leaf commands (e.g. `hf repos create --test`)
+        we list the command's options; for groups (e.g. `hf cache --test`)
+        we list subcommands since groups have no user-facing options.
+        """
+        try:
+            return super().invoke(ctx)
+        except click.NoSuchOption as e:
+            if e.ctx is not None and e.ctx.command is not None:
+                cmd = e.ctx.command
+                if isinstance(cmd, click.Group):
+                    # Group has no user-facing options -> show subcommands instead
+                    items = [
+                        (name, sub.get_short_help_str(limit=80))
+                        for name in cmd.list_commands(e.ctx)
+                        if (sub := cmd.get_command(e.ctx, name)) is not None and not sub.hidden
+                    ]
+                    _enrich_usage_error(e, "commands", items)
+                else:
+                    # Leaf command -> show its options using Click's rich formatting
+                    items = [
+                        record
+                        for p in cmd.get_params(e.ctx)
+                        if isinstance(p, click.Option) and not p.hidden and (record := p.get_help_record(e.ctx))
+                    ]
+                    _enrich_usage_error(e, "options", items)
+            raise
+
+    def resolve_command(self, ctx: click.Context, args: list[str]) -> tuple:
+        cmd_name = args[0] if args and not args[0].startswith("-") else None
+        cmd = self.get_command(ctx, cmd_name) if cmd_name else None
+
+        if cmd is not None:
+            self._rewrite_repo_type_prefix(cmd, args)
+
+        try:
+            name, resolved_cmd, sub_args = super().resolve_command(ctx, args)
+        except click.UsageError as e:
+            # Unknown subcommand -> add fuzzy suggestions and list available commands.
+            if cmd is None and cmd_name is not None:
+                # Expand aliases ("list | ls" → ["list", "ls"]) for accurate fuzzy matching.
+                visible_names = [
+                    alias
+                    for key, registered in self.commands.items()
+                    if not registered.hidden
+                    for alias in _ALIAS_SPLIT.split(key)
+                ]
+                matches = difflib.get_close_matches(cmd_name, visible_names)
+                if matches:
+                    suggestions = ", ".join(f"'{m}'" for m in matches)
+                    e.message = f"{e.message.rstrip('.')}. Did you mean {suggestions}?"
+                items = [
+                    (name, sub.get_short_help_str(limit=80))
+                    for name in self.list_commands(ctx)
+                    if (sub := self.get_command(ctx, name)) is not None and not sub.hidden
+                ]
+                _enrich_usage_error(e, "commands", items)
+            raise
+
+        # If we just resolved a leaf command, eagerly consume any global formatting
+        # flags (--format / --json / -q / --quiet / --no-truncate) from its args before click parses
+        # them.  Group resolution is recursive — leaves (and only leaves) need this.
+        if resolved_cmd is not None and not isinstance(resolved_cmd, click.Group):
+            _consume_format_flags_for_leaf(resolved_cmd, sub_args)
+
+        return name, resolved_cmd, sub_args
+
+    @staticmethod
+    def _rewrite_repo_type_prefix(cmd: click.Command, args: list[str]) -> None:
+        """Rewrite prefixed repo IDs (e.g. ``spaces/user/repo``) to ``user/repo --type space``.
+
+        Only applies to commands that have a ``--type`` / ``--repo-type`` option and
+        at least one repo-ID positional argument (any ``click.Argument`` whose name
+        ends with ``_id``, e.g. ``repo_id``, ``from_id``, ``to_id``).  When the
+        token that maps to such an argument matches ``{prefix}/org/repo`` (where
+        *prefix* is one of ``spaces``, ``datasets``, or ``models``), the prefix is
+        stripped and an implicit ``--type {type}`` is appended.  An error is raised
+        if ``--type`` is also provided explicitly or if multiple prefixed arguments
+        disagree on the repo type.
+
+        Only repo-ID positional slots are inspected so that other positional
+        arguments (filenames, local paths, patterns …) are never misinterpreted as
+        prefixed repo IDs.
+        """
+        has_type_option = any(isinstance(param, click.Option) and "--type" in param.opts for param in cmd.params)
+        if not has_type_option:
+            return
+
+        # Locate all repo-ID positional arguments and their indices among Arguments.
+        repo_id_positions: set[int] = set()
+        arg_idx = 0
+        for param in cmd.params:
+            if isinstance(param, click.Argument):
+                if param.name in ("repo_id", "from_id", "to_id"):
+                    repo_id_positions.add(arg_idx)
+                arg_idx += 1
+
+        if not repo_id_positions:
+            return
+
+        # Build a set of option names that consume a following value token.
+        value_options: set[str] = set()
+        for param in cmd.params:
+            if isinstance(param, click.Option) and not param.is_flag:
+                for opt in (*param.opts, *param.secondary_opts):
+                    value_options.add(opt)
+
+        # Walk through args (skipping args[0] = command name) to map positional
+        # slots to their indices in `args`.
+        positional_count = 0
+        repo_id_arg_indices: list[int] = []
+        i = 1
+        while i < len(args):
+            arg = args[i]
+            if arg == "--":
+                break  # everything after -- is positional literal; stop rewriting
+            if arg.startswith("-"):
+                if "=" in arg or arg not in value_options:
+                    i += 1  # flag or --opt=val — single token
+                else:
+                    i += 2  # value-taking option — skip the value too
+            else:
+                if positional_count in repo_id_positions:
+                    repo_id_arg_indices.append(i)
+                positional_count += 1
+                i += 1
+
+        if not repo_id_arg_indices:
+            return
+
+        # Check each repo-ID arg for a type prefix and collect rewrites.
+        inferred_type: str | None = None
+        first_prefix: str | None = None
+        rewrites: list[tuple[int, str]] = []  # (args index, new value without prefix)
+
+        for arg_index in repo_id_arg_indices:
+            parts = args[arg_index].split("/", 2)
+            if len(parts) != 3 or parts[0] not in constants.REPO_TYPES_MAPPING:
+                continue
+            prefix = parts[0]
+            mapped_type = constants.REPO_TYPES_MAPPING[prefix]
+            if inferred_type is not None and mapped_type != inferred_type:
+                raise click.UsageError(f"Conflicting repo type prefixes: '{first_prefix}/' and '{prefix}/'.")
+            inferred_type = mapped_type
+            first_prefix = prefix
+            rewrites.append((arg_index, f"{parts[1]}/{parts[2]}"))
+
+        if not rewrites:
+            return
+
+        # Error if --type / --repo-type was also provided explicitly.
+        if any(
+            arg == "--type" or arg.startswith("--type=") or arg == "--repo-type" or arg.startswith("--repo-type=")
+            for arg in args
+        ):
+            raise click.UsageError(
+                f"Ambiguous repo type: got prefix '{first_prefix}/' in repo ID and explicit --type. Use one or the other."
+            )
+
+        # Apply all rewrites and append --type once.
+        for arg_index, new_value in rewrites:
+            args[arg_index] = new_value
+        args.extend(["--type", inferred_type])  # type: ignore
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        # Try exact match first
+        cmd = super().get_command(ctx, cmd_name)
+        if cmd is not None:
+            return cmd
+        # Fall back to alias lookup: check if cmd_name matches any alias
+        # taken from https://github.com/fastapi/typer/issues/132#issuecomment-2417492805
+        for registered_name, registered_cmd in self.commands.items():
+            aliases = _ALIAS_SPLIT.split(registered_name)
+            if cmd_name in aliases:
+                return registered_cmd
+        return None
+
+    def _alias_map(self) -> dict[str, list[str]]:
+        """Build a mapping from primary command name to its aliases (if any)."""
+        result: dict[str, list[str]] = {}
+        for registered_name in self.commands:
+            parts = _ALIAS_SPLIT.split(registered_name)
+            primary = parts[0]
+            result[primary] = parts[1:]
+        return result
+
+    def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        topics: dict[str, list] = {}
+        alias_map = self._alias_map()
+
+        for name in self.list_commands(ctx):
+            cmd = self.get_command(ctx, name)
+            if cmd is None or cmd.hidden:
+                continue
+            help_text = cmd.get_short_help_str(limit=formatter.width)
+            aliases = alias_map.get(name, [])
+            if aliases:
+                help_text = f"{help_text} [alias: {', '.join(aliases)}]"
+            topic = getattr(cmd, "topic", "main")
+            topics.setdefault(topic, []).append((name, help_text))
+
+        with formatter.section("Main commands"):
+            formatter.write_dl(topics["main"])
+        for topic in sorted(topics.keys()):
+            if topic == "main":
+                continue
+            with formatter.section(f"{topic.capitalize()} commands"):
+                formatter.write_dl(topics[topic])
+
+    def format_epilog(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        # Collect only the first example from each command (to keep group help concise)
+        # Full examples are shown in individual subcommand help (e.g. `hf buckets sync --help`)
+        all_examples: list[str] = []
+        for name in self.list_commands(ctx):
+            cmd = self.get_command(ctx, name)
+            if cmd is None or cmd.hidden:
+                continue
+            cmd_examples = getattr(cmd, "examples", [])
+            if cmd_examples:
+                all_examples.append(cmd_examples[0])
+
+        if all_examples:
+            epilog = generate_epilog(all_examples)
+            _format_epilog_no_indent(epilog, ctx, formatter)
+        elif self.epilog:
+            _format_epilog_no_indent(self.epilog, ctx, formatter)
+
+    def list_commands(self, ctx: click.Context) -> list[str]:  # type: ignore[name-defined]
+        # For aliased commands ("list | ls"), use the primary name (first entry).
+        primary_names: list[str] = []
+        for name in self.commands:
+            primary = _ALIAS_SPLIT.split(name)[0]
+            primary_names.append(primary)
+        return sorted(primary_names)
+
+
+_FORMATTING_OPTIONS_HELP_RECORDS: list[tuple[str, str]] = [
+    (
+        "--format [auto|human|agent|json|quiet]",
+        "Output format. Defaults to 'auto' which picks 'agent' or 'human' based on the terminal.",
+    ),
+    ("--json", "JSON output. Equivalent to '--format json'."),
+    ("-q, --quiet", "Quiet output (one ID per line). Equivalent to '--format quiet'."),
+    ("--no-truncate", "Do not truncate scalar values in human tables (list/dict columns stay shortened)."),
+]
+
+
+def _format_formatting_options_section(formatter: click.HelpFormatter) -> None:
+    with formatter.section("Formatting options"):
+        formatter.write_dl(_FORMATTING_OPTIONS_HELP_RECORDS)
+
+
+def _has_local_formatting_option(cmd: click.Command) -> bool:
+    """Return True if the command defines its own --format, --json or --quiet / -q.
+
+    Used to skip the global formatting flag pre-processor and the duplicated "Formatting options" help section for
+    legacy commands like 'hf jobs ps' that have their own format/quiet options.
+    """
+    for param in cmd.params:
+        if not isinstance(param, click.Option):
+            continue
+        opts = (*param.opts, *param.secondary_opts)
+        if "--format" in opts or "--json" in opts or "--quiet" in opts or "-q" in opts:
+            return True
+    return False
+
+
+def _consume_format_flags_for_leaf(cmd: click.Command, args: list[str]) -> None:
+    """Apply global formatting flags from 'args' to a leaf command.
+
+    Two modes, depending on the command:
+
+    * **Pass-through commands** (ignore_unknown_options=True, e.g. 'hf extensions exec'):
+      args are forwarded verbatim to an external binary; we don't touch them.
+
+    * **Legacy commands with a local --format option** (e.g. 'hf jobs ps' whose '--format' accepts Go templates):
+      the global flags are rewritten in-place to the legacy form ('--json' → '--format json', '--quiet'/'-q' → '--format quiet'
+      when the cmd has no own '--quiet') so click can parse them locally. This preserves backwards compatibility with the previous shorthand behavior.
+
+    * **Modern commands** (no local format/quiet/json options): the flags '--format <value>' / '--json' / '--quiet' / '-q' are stripped from 'args' and applied to the singleton 'out'.
+
+    '--no-truncate' is stripped for all non-pass-through commands; when present, human table cells are not truncated.
+
+    Raises click.UsageError if multiple conflicting flags are supplied (e.g. '--json' together with '--format table').
+    """
+    if cmd.context_settings.get("ignore_unknown_options"):
+        return
+
+    no_truncate = _consume_no_truncate_flags(args)
+    out.set_no_truncate(no_truncate)
+
+    has_local_format = False
+    has_local_quiet = False
+    has_local_json = False
+    for param in cmd.params:
+        if not isinstance(param, click.Option):
+            continue
+        opts = (*param.opts, *param.secondary_opts)
+        if "--format" in opts:
+            has_local_format = True
+        if "--quiet" in opts or "-q" in opts:
+            has_local_quiet = True
+        if "--json" in opts:
+            has_local_json = True
+
+    if has_local_format:
+        _rewrite_legacy_shorthands(args, rewrite_json=not has_local_json, rewrite_quiet=not has_local_quiet)
+        return
+
+    # Strip --format/--json/-q/--quiet from 'args' and apply to 'out'
+    chosen_mode: OutputFormat = OutputFormat.auto
+    chosen_flag: str | None = None
+
+    def _check_conflict(new_flag: str) -> None:
+        # Reject any second formatting flag before parsing values, so the user gets
+        # a "mutually exclusive" error rather than e.g. an "invalid value" error
+        # from the second flag's argument.
+        if chosen_flag is not None:
+            raise click.UsageError(f"'{chosen_flag}' and '{new_flag}' are mutually exclusive.")
+
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg == "--":
+            break  # everything after '--' is a positional literal
+        if arg == "--format":
+            _check_conflict("--format")
+            if i + 1 >= len(args):
+                raise click.UsageError("Option '--format' requires a value.")
+            chosen_mode = _parse_format_value(args[i + 1])
+            chosen_flag = "--format"
+            del args[i : i + 2]  # --format value => 2 args removed
+            continue
+        if arg.startswith("--format="):
+            _check_conflict("--format")
+            chosen_mode = _parse_format_value(arg[len("--format=") :])
+            chosen_flag = "--format"
+            del args[i : i + 1]
+            continue
+        if arg == "--json":
+            _check_conflict("--json")
+            chosen_mode = OutputFormat.json
+            chosen_flag = "--json"
+            del args[i : i + 1]
+            continue
+        if arg in ("-q", "--quiet"):
+            _check_conflict(arg)
+            chosen_mode = OutputFormat.quiet
+            chosen_flag = arg
+            del args[i : i + 1]
+            continue
+        i += 1
+
+    out.set_mode(chosen_mode)
+
+
+def _consume_no_truncate_flags(args: list[str]) -> bool:
+    """Strip all global --no-truncate flags from args and return whether any was provided."""
+    no_truncate = False
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg == "--":
+            break  # everything after '--' is a positional literal
+        if arg == "--no-truncate":
+            no_truncate = True
+            del args[i : i + 1]
+            continue
+        if arg.startswith("--no-truncate="):
+            raise click.UsageError("Option '--no-truncate' does not take a value.")
+        i += 1
+    return no_truncate
+
+
+def _rewrite_legacy_shorthands(args: list[str], *, rewrite_json: bool, rewrite_quiet: bool) -> None:
+    """Rewrite --json / -q / --quiet to --format ... for legacy commands.
+
+    Used for commands like 'hf jobs ps' that still own their '--format' option.
+    The rewrite lets users keep using the global shorthand while click parses
+    '--format <value>' locally.
+    """
+    has_format_in_args = any(arg == "--format" or arg.startswith("--format=") for arg in args)
+
+    if rewrite_json and "--json" in args:
+        if has_format_in_args:
+            raise click.UsageError("'--json' and '--format' are mutually exclusive.")
+        idx = args.index("--json")
+        args[idx : idx + 1] = ["--format", "json"]
+        has_format_in_args = True
+
+    if rewrite_quiet:
+        flag = "-q" if "-q" in args else ("--quiet" if "--quiet" in args else None)
+        if flag is not None:
+            if has_format_in_args:
+                raise click.UsageError(f"'{flag}' and '--format' are mutually exclusive.")
+            idx = args.index(flag)
+            args[idx : idx + 1] = ["--format", "quiet"]
+
+
+def _parse_format_value(value: str) -> "OutputFormat":
+    try:
+        return OutputFormat(value)
+    except ValueError:
+        valid = ", ".join(m.value for m in OutputFormat)
+        raise click.UsageError(f"Invalid value for '--format': '{value}'. Valid values: {valid}.") from None
+
+
+def _enrich_usage_error(error: click.UsageError, label: str, items: list[tuple[str, str]]) -> None:
+    """Append a list of available options or commands to a usage error message."""
+    if not items or error.ctx is None or f"Available {label} for" in error.message:
+        return
+    cmd_path = error.ctx.command_path
+    lines = [f"\n\nAvailable {label} for '{cmd_path}':"]
+    for name, help_text in items:
+        lines.append(f"  {name:30s} {help_text}")
+    lines.append(f"\nRun '{cmd_path} --help' for full details.")
+    if isinstance(error, click.NoSuchOption) and error.possibilities:
+        lines.append(f"\nDid you mean: {', '.join(sorted(error.possibilities))}?")
+        error.possibilities = []
+    error.message += "\n".join(lines)
+
+
+def fallback_typer_group_factory(
+    fallback_handler: FallbackHandlerT,
+    extra_commands_provider: Callable[[], list[tuple[str, str]]] | None = None,
+) -> type[HFCliTyperGroup]:
+    """Return a Typer group class that runs a fallback handler before command resolution."""
+
+    class FallbackTyperGroup(HFCliTyperGroup):
+        def resolve_command(self, ctx: click.Context, args: list[str]) -> tuple:
+            fallback_exit_code = fallback_handler(args, set(self.commands.keys()))
+            if fallback_exit_code is not None:
+                raise SystemExit(fallback_exit_code)
+            return super().resolve_command(ctx, args)
+
+        def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+            super().format_commands(ctx, formatter)
+            if extra_commands_provider is not None:
+                entries = extra_commands_provider()
+                if entries:
+                    with formatter.section("Extension commands"):
+                        formatter.write_dl(entries)
+
+    return FallbackTyperGroup
+
+
+def HFCliCommand(topic: TOPIC_T, examples: list[str] | None = None) -> type[TyperCommand]:
+    def format_epilog(self: click.Command, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        _format_epilog_no_indent(self.epilog, ctx, formatter)
+
+    def format_options(self: TyperCommand, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        TyperCommand.format_options(self, ctx, formatter)
+        # Skip the section for commands that define their own --format / --quiet / --json,
+        # or for pass-through commands that forward args to an external binary.
+        if _has_local_formatting_option(self):
+            return
+        if self.context_settings.get("ignore_unknown_options"):
+            return
+        _format_formatting_options_section(formatter)
+
+    def parse_args(self: click.Command, ctx: click.Context, args: list[str]) -> list[str]:
+        # Show help when a command with required arguments is invoked without any args
+        # (mirrors group behavior: `hf jobs` prints help, so `hf download` should too).
+        if not args and not ctx.resilient_parsing:
+            if any(isinstance(p, click.Argument) and p.required for p in self.params):
+                click.echo(ctx.get_help(), color=ctx.color)
+                ctx.exit()
+        return TyperCommand.parse_args(self, ctx, args)
+
+    return type(
+        f"TyperCommand{topic.capitalize()}",
+        (TyperCommand,),
+        {
+            "context_class": StyledContext,
+            "topic": topic,
+            "examples": examples or [],
+            "format_epilog": format_epilog,
+            "format_options": format_options,
+            "parse_args": parse_args,
+        },
+    )
+
+
+class HFCliApp(typer.Typer):
+    """Custom Typer app for Hugging Face CLI."""
+
+    def command(  # type: ignore
+        self,
+        name: str | None = None,
+        *,
+        topic: TOPIC_T = "main",
+        examples: list[str] | None = None,
+        context_settings: dict[str, Any] | None = None,
+        help: str | None = None,
+        epilog: str | None = None,
+        short_help: str | None = None,
+        options_metavar: str = "[OPTIONS]",
+        add_help_option: bool = True,
+        no_args_is_help: bool = False,
+        hidden: bool = False,
+        deprecated: bool = False,
+        rich_help_panel: str | None = None,
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        # Generate epilog from examples if not explicitly provided
+        if epilog is None and examples:
+            epilog = generate_epilog(examples)
+
+        def _inner(func: Callable[..., Any]) -> Callable[..., Any]:
+            return super(HFCliApp, self).command(
+                name,
+                cls=HFCliCommand(topic, examples),
+                context_settings=context_settings,
+                help=help,
+                epilog=epilog,
+                short_help=short_help,
+                options_metavar=options_metavar,
+                add_help_option=add_help_option,
+                no_args_is_help=no_args_is_help,
+                hidden=hidden,
+                deprecated=deprecated,
+                rich_help_panel=rich_help_panel,
+            )(func)
+
+        return _inner
+
+
+def typer_factory(help: str, epilog: str | None = None, cls: type[TyperGroup] | None = None) -> "HFCliApp":
+    """Create a Typer app with consistent settings.
+
+    Args:
+        help: Help text for the app.
+        epilog: Optional epilog text (use `generate_epilog` to create one).
+        cls: Optional Click group class to use (defaults to `HFCliTyperGroup`).
+
+    Returns:
+        A configured Typer app.
+    """
+    if cls is None:
+        cls = HFCliTyperGroup
+    return HFCliApp(
+        help=help,
+        epilog=epilog,
+        add_completion=True,
+        no_args_is_help=True,
+        cls=cls,
+        # Disable rich completely for consistent experience
+        rich_markup_mode=None,
+        rich_help_panel=None,
+        pretty_exceptions_enable=False,
+        # Disable TyperGroup's suggest_commands, it matches against raw aliased
+        # keys ("list | ls") leaking pipe syntax into user-facing messages.
+        # HFCliTyperGroup.resolve_command() handles suggestions with expanded names.
+        suggest_commands=False,
+        # Increase max content width for better readability
+        context_settings={
+            "max_content_width": 120,
+            "help_option_names": ["-h", "--help"],
+        },
+    )
+
+
+class SoftChoice(click.Choice):
+    """A click Choice that suggests choices for autocompletion/docs but accepts any string.
+
+    Unlike `click.Choice`, unknown values are passed through as-is instead of raising an error.
+    This makes CLI options future-compatible when new server-side values are added.
+
+    Accepts either a sequence of strings or an Enum class:
+    ```python
+    SoftChoice(SpaceHardware)        # from an enum
+    SoftChoice(["a", "b", "c"])      # from a list
+    ```
+    """
+
+    def __init__(self, choices: Sequence[str] | type[Enum]) -> None:
+        values = (
+            [m.value for m in choices] if isinstance(choices, type) and issubclass(choices, Enum) else list(choices)
+        )
+        super().__init__(values, case_sensitive=True)
+
+    def convert(self, value: Any, param: click.Parameter | None, ctx: click.Context | None) -> str:
+        try:
+            return super().convert(value, param, ctx)
+        except click.exceptions.BadParameter:
+            return str(value)
+
+
+class RepoType(str, Enum):
+    model = "model"
+    dataset = "dataset"
+    space = "space"
+
+
+RepoIdArg = Annotated[
+    str,
+    typer.Argument(
+        help="The ID of the repo (e.g. `username/repo-name` or `spaces/username/repo-name`).",
+    ),
+]
+
+
+RepoTypeOpt = Annotated[
+    RepoType,
+    typer.Option(
+        "--type",
+        "--repo-type",
+        help="The type of repository (model, dataset, or space).",
+    ),
+]
+
+# Same as `RepoTypeOpt` but optional (defaults to `None` rather than `model`). Used by commands that
+# accept an `hf://` URI as repo id: a `None` default lets us tell apart "user did not pass --repo-type"
+# from "user explicitly passed --repo-type model", which is required to detect conflicts with the URI.
+RepoTypeOptionalOpt = Annotated[
+    RepoType | None,
+    typer.Option(
+        "--type",
+        "--repo-type",
+        help="The type of repository (model, dataset, or space).",
+        show_default="model",
+    ),
+]
+
+TokenOpt = Annotated[
+    str | None,
+    typer.Option(
+        help="A User Access Token generated from https://huggingface.co/settings/tokens.",
+    ),
+]
+
+PrivateOpt = Annotated[
+    bool | None,
+    typer.Option(
+        help="Whether to create a private repo if repo doesn't exist on the Hub. Ignored if the repo already exists.",
+    ),
+]
+
+RevisionOpt = Annotated[
+    str | None,
+    typer.Option(
+        help="Git revision id which can be a branch name, a tag, or a commit hash.",
+    ),
+]
+
+
+LimitOpt = Annotated[
+    int,
+    typer.Option(help="Limit the number of results."),
+]
+
+AuthorOpt = Annotated[
+    str | None,
+    typer.Option(help="Filter by author or organization."),
+]
+
+FilterOpt = Annotated[
+    list[str] | None,
+    typer.Option(help="Filter by tags (e.g. 'text-classification'). Can be used multiple times."),
+]
+
+SearchOpt = Annotated[
+    str | None,
+    typer.Option(help="Search query."),
+]
+
+
+# --- Env / Secrets shared options and parsing helpers (used by jobs, repos, etc.) ---
+
+EnvOpt = Annotated[
+    list[str] | None,
+    typer.Option(
+        "-e",
+        "--env",
+        help="Set environment variables. E.g. --env ENV=value",
+    ),
+]
+
+SecretsOpt = Annotated[
+    list[str] | None,
+    typer.Option(
+        "-s",
+        "--secrets",
+        help=(
+            "Set secret environment variables. E.g. --secrets SECRET=value"
+            " or `--secrets HF_TOKEN` to pass your Hugging Face token."
+        ),
+    ),
+]
+
+EnvFileOpt = Annotated[
+    str | None,
+    typer.Option(
+        "--env-file",
+        help="Read in a file of environment variables.",
+    ),
+]
+
+SecretsFileOpt = Annotated[
+    str | None,
+    typer.Option(
+        help="Read in a file of secret environment variables.",
+    ),
+]
+
+
+def _get_extended_environ() -> dict[str, str]:
+    """Return a copy of ``os.environ`` with the user's HF token injected (if available)."""
+    from huggingface_hub import get_token
+
+    extended_environ = os.environ.copy()
+    if (token := get_token()) is not None:
+        extended_environ["HF_TOKEN"] = token
+    return extended_environ
+
+
+def parse_env_map(
+    env: list[str] | None = None,
+    env_file: str | None = None,
+) -> dict[str, str | None]:
+    """Parse ``-e``/``--env``/``-s``/``--secrets`` and ``--env-file``/``--secrets-file`` CLI args into a dict.
+
+    Uses an extended environment that includes the user's HF token so that
+    bare ``--secrets HF_TOKEN`` resolves correctly.
+    """
+    extended_environ = _get_extended_environ()
+    env_map: dict[str, str | None] = {}
+    if env_file:
+        env_map.update(load_dotenv(Path(env_file).read_text(), environ=extended_environ))
+    for env_value in env or []:
+        env_map.update(load_dotenv(env_value, environ=extended_environ))
+    return env_map
+
+
+def env_map_to_key_value_list(env_map: dict[str, str | None]) -> list[dict[str, str]] | None:
+    """Convert an env/secrets dict to the ``[{"key": ..., "value": ...}]`` format used by the Hub API."""
+    if not env_map:
+        return None
+    return [{"key": k, "value": v or ""} for k, v in env_map.items()]
+
+
+VolumesOpt = Annotated[
+    list[str] | None,
+    typer.Option(
+        "-v",
+        "--volume",
+        help="Mount one or more volumes. Format: hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]. "
+        "TYPE is one of: models, datasets, spaces, buckets. "
+        "TYPE defaults to models if omitted. "
+        "models, datasets and spaces are always mounted read-only. buckets are read+write by default. "
+        "E.g. -v hf://org/m:/data or -v hf://datasets/org/ds:/data or -v hf://buckets/org/b:/mnt:ro",
+    ),
+]
+
+
+def parse_volumes(volumes: list[str] | None) -> "list[Volume] | None":
+    """Parse volume specs from CLI arguments.
+
+    Format: hf://[TYPE/]SOURCE[/PATH]:/MOUNT_PATH[:ro|:rw]
+    Where TYPE is one of: models, datasets, spaces, buckets (defaults to models if omitted).
+    SOURCE is the repo/bucket identifier (e.g. 'username/my-model').
+    PATH is an optional subfolder inside the repo/bucket.
+    MOUNT_PATH starts with '/'.
+    Optional ':ro' or ':rw' suffix for read-only or read-write.
+
+    Examples:
+        hf://my-org/my-model:/data                (model, implicit type)
+        hf://models/my-org/my-model:/data         (model, explicit type)
+        hf://datasets/my-org/my-dataset:/data:ro
+        hf://buckets/my-org/my-bucket:/mnt
+        hf://spaces/my-org/my-space:/app
+        hf://datasets/org/ds/train:/data          (with path inside repo)
+        hf://buckets/org/b/sub/dir:/mnt           (with path inside bucket)
+    """
+    if not volumes:
+        return None
+
+    result: list[Volume] = []
+    for raw_spec in volumes:
+        mount = parse_hf_mount(raw_spec)
+        result.append(
+            Volume(
+                type=mount.source.type,
+                source=mount.source.id,
+                mount_path=mount.mount_path,
+                read_only=mount.read_only,
+                path=mount.source.path_in_repo or None,
+                revision=mount.source.revision or None,
+            )
+        )
+    return result
+
+
+def make_expand_properties_parser(valid_properties: Sequence[ExpandPropertyT]):
+    """Create a callback to parse and validate comma-separated expand properties."""
+
+    def _parse_expand_properties(value: str | None) -> list[ExpandPropertyT] | None:
+        if value is None:
+            return None
+        properties = [p.strip() for p in value.split(",")]
+        for prop in properties:
+            if prop not in valid_properties:
+                raise typer.BadParameter(
+                    f"Invalid expand property: '{prop}'. Valid values are: {', '.join(valid_properties)}"
+                )
+        return [cast(ExpandPropertyT, prop) for prop in properties]
+
+    return _parse_expand_properties
+
+
+### PyPI VERSION CHECKER
+
+
+def check_cli_update(library: Literal["huggingface_hub", "transformers"]) -> None:
+    """
+    Check whether a newer version of a library is available on PyPI.
+
+    If a newer version is found, print a hint pointing at `hf update`.
+
+    If current version is a pre-release (e.g. `1.0.0.rc1`), or a dev version (e.g. `1.0.0.dev1`), no check is performed.
+    If `HF_HUB_DISABLE_UPDATE_CHECK` is set, the check is skipped entirely.
+
+    This function is called at the entry point of the CLI. It only performs the check once every 24 hours, and any error
+    during the check is caught and logged, to avoid breaking the CLI.
+
+    Args:
+        library: The library to check for updates. Currently supports "huggingface_hub" and "transformers".
+    """
+    try:
+        _check_cli_update(library)
+    except Exception:
+        # We don't want the CLI to fail on version checks, no matter the reason.
+        logger.debug("Error while checking for CLI update.", exc_info=True)
+
+
+def _check_cli_update(library: Literal["huggingface_hub", "transformers"]) -> None:
+    if constants.HF_HUB_DISABLE_UPDATE_CHECK:
+        return
+
+    current_version = importlib.metadata.version(library)
+
+    # Skip if current version is a pre-release or dev version
+    if any(tag in current_version for tag in ["rc", "dev"]):
+        return
+
+    # Skip if already checked in the last 24 hours
+    if os.path.exists(constants.CHECK_FOR_UPDATE_DONE_PATH):
+        mtime = os.path.getmtime(constants.CHECK_FOR_UPDATE_DONE_PATH)
+        if (time.time() - mtime) < 24 * 3600:
+            return
+
+    # Touch the file to mark that we did the check now
+    Path(constants.CHECK_FOR_UPDATE_DONE_PATH).parent.mkdir(parents=True, exist_ok=True)
+    Path(constants.CHECK_FOR_UPDATE_DONE_PATH).touch()
+
+    # Check latest version from the appropriate registry
+    if library == "huggingface_hub" and installation_method() == "brew":
+        latest_version = _fetch_latest_brew_version()
+    else:
+        latest_version = _fetch_latest_pypi_version(library)
+    if latest_version is None or current_version == latest_version:
+        return
+
+    if library == "huggingface_hub":
+        update_command = _get_huggingface_hub_update_command()
+    else:
+        update_command = _get_transformers_update_command()
+
+    message = f"A new version of {library} ({latest_version}) is available! You are using version {current_version}."
+    if update_command is not None:
+        match library:
+            case "huggingface_hub":
+                message += "\nTo update, run: hf update"
+            case _:
+                message += f"\nTo update, run: {' '.join(update_command)}"
+    out.hint(message)
+
+
+def _fetch_latest_pypi_version(library: str) -> str | None:
+    """Fetch the latest version of a library from PyPI. Returns None if the request fails."""
+    try:
+        response = get_session().get(f"https://pypi.org/pypi/{library}/json", timeout=2)
+        hf_raise_for_status(response)
+        return response.json()["info"]["version"]
+    except Exception:
+        logger.debug("Error while fetching latest version from PyPI.", exc_info=True)
+        return None
+
+
+def _fetch_latest_brew_version() -> str | None:
+    """Fetch the latest version of the `hf` formula from the Homebrew registry. Returns None if the request fails."""
+    try:
+        response = get_session().get("https://formulae.brew.sh/api/formula/hf.json", timeout=2)
+        hf_raise_for_status(response)
+        return response.json()["versions"]["stable"]
+    except Exception:
+        logger.debug("Error while fetching latest version from Homebrew.", exc_info=True)
+        return None
+
+
+def run_update() -> int:
+    """Run the install-method-appropriate update command for the `hf` CLI.
+
+    Raises CLIError if the installation method can't be determined.
+    Returns the subprocess exit code on success/failure of the update itself.
+    """
+    cmd = _get_huggingface_hub_update_command()
+    if cmd is None:
+        raise CLIError(
+            "Cannot determine how to update huggingface_hub (unknown installation method). Please update manually."
+        )
+    return subprocess.call(cmd)
+
+
+def _get_huggingface_hub_update_command() -> list[str] | None:
+    """Return the command to update huggingface_hub as an argv list, or None if the installation method is unknown."""
+    match installation_method():
+        case "brew":
+            return ["brew", "upgrade", "hf"]
+        case "hf_installer" if os.name == "nt":
+            return ["powershell", "-NoProfile", "-Command", "iwr -useb https://hf.co/cli/install.ps1 | iex"]
+        case "hf_installer":
+            return ["bash", "-c", "curl -LsSf https://hf.co/cli/install.sh | bash -"]
+        case "pip":
+            return [sys.executable, "-m", "pip", "install", "-U", "huggingface_hub"]
+        case _:
+            return None
+
+
+def _get_transformers_update_command() -> list[str] | None:
+    """Return the command to update transformers as an argv list, or None if the installation method is unknown."""
+    match installation_method():
+        case "hf_installer" if os.name == "nt":
+            return [
+                "powershell",
+                "-NoProfile",
+                "-Command",
+                "iwr -useb https://hf.co/cli/install.ps1 | iex -WithTransformers",
+            ]
+        case "hf_installer":
+            return ["bash", "-c", "curl -LsSf https://hf.co/cli/install.sh | bash -s -- --with-transformers"]
+        case "pip":
+            return [sys.executable, "-m", "pip", "install", "-U", "transformers"]
+        case _:
+            return None

venv/Lib/site-packages/huggingface_hub/cli/_cp.py

@@ -0,0 +1,252 @@
+# Copyright 2026-present, the HuggingFace Inc. team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Shared ``cp`` command to copy files between local paths, repositories and buckets.
+
+This single command backs three identical CLI entry points: ``hf cp`` (top-level),
+``hf repos cp`` and ``hf buckets cp``. It supports any source/destination combination
+of local file, repo/bucket ``hf://`` URI, and ``-`` (stdin/stdout), with two exceptions:
+- bucket-to-repo copies are not supported (server limitation), and
+- local-to-local copies (use a regular ``cp`` for that).
+"""
+
+import os
+import sys
+from dataclasses import replace
+from typing import Annotated, Literal
+
+import typer
+
+from huggingface_hub import HfApi
+from huggingface_hub.errors import CLIError
+from huggingface_hub.utils import HfUri, SoftTemporaryDirectory, disable_progress_bars, is_hf_uri, parse_hf_uri
+
+from ._cli_utils import TokenOpt, get_hf_api
+from ._output import out
+
+
+CP_EXAMPLES = [
+    # Download (repo or bucket -> local / stdout)
+    "hf cp hf://username/my-model/config.json",
+    "hf cp hf://username/my-model/config.json ./config.json",
+    "hf cp hf://datasets/username/my-dataset/data.csv ./data/",
+    "hf cp hf://buckets/username/my-bucket/config.json -",
+    # Upload (local / stdin -> repo or bucket)
+    "hf cp ./model.safetensors hf://username/my-model/model.safetensors",
+    "hf cp ./config.json hf://buckets/username/my-bucket/logs/",
+    "hf cp - hf://buckets/username/my-bucket/config.json",
+    # Remote to remote (repo/bucket -> repo/bucket, server-side when possible)
+    "hf cp hf://username/source-model/ hf://username/dest-model/",
+    "hf cp hf://datasets/username/my-dataset/processed/ hf://buckets/username/my-bucket/processed/",
+    "hf cp hf://buckets/username/my-bucket/logs/ hf://buckets/username/archive-bucket/  # copies contents only",
+]
+
+
+# Which alias registered the command, used to restrict the remote endpoint type (see `_enforce_context`).
+CpContext = Literal["repos", "buckets"]
+
+
+def make_cp(context: CpContext | None = None):
+    """Build the ``cp`` command function for a given alias.
+
+    The three entry points (`hf cp`, `hf repos cp`, `hf buckets cp`) share the exact same logic;
+    'context' only adds a guardrail on the remote endpoint type (see `_enforce_context`).
+    """
+
+    def cp(
+        src: Annotated[
+            str,
+            typer.Argument(help="Source: local file, hf:// URI (repo or bucket), or - for stdin."),
+        ],
+        dst: Annotated[
+            str | None,
+            typer.Argument(help="Destination: local path, hf:// URI (repo or bucket), or - for stdout."),
+        ] = None,
+        token: TokenOpt = None,
+    ) -> None:
+        """Copy files between local paths, repositories, and buckets.
+
+        Handles uploads (local/stdin -> repo/bucket), downloads (repo/bucket -> local/stdout) and
+        remote-to-remote copies (repo/bucket -> repo/bucket). Bucket-to-repo and local-to-local
+        copies are not supported. For directories, use `hf upload`/`hf download` (repos) or
+        `hf buckets sync` (buckets). Remote-to-remote copies only work within the same storage
+        region (https://huggingface.co/docs/hub/storage-regions).
+        """
+        _enforce_context(context, src, dst)
+        _run_cp(src, dst, token)
+
+    return cp
+
+
+def _enforce_context(context: CpContext | None, src: str, dst: str | None) -> None:
+    """Guardrail for the `hf repos cp` / `hf buckets cp` aliases.
+
+    These aliases are exact duplicates of `hf cp`, so a bare `hf repos cp` could otherwise touch a
+    bucket (and vice versa). We validate the type of the remote side: the destination for uploads and
+    remote-to-remote copies, or the source when downloading to a local path / stdout. The top-level
+    `hf cp` (i.e. 'context' is None) accepts any combination.
+    """
+    if context is None:
+        return
+    # The remote endpoint is the destination when it is an hf:// URI, otherwise the source (download).
+    remote = dst if (dst is not None and is_hf_uri(dst)) else src
+    if not is_hf_uri(remote):
+        return
+    if context == "repos" and parse_hf_uri(remote).is_bucket:
+        raise CLIError("`hf repos cp` only works with repositories. Use `hf cp` or `hf buckets cp` for buckets.")
+    if context == "buckets" and not parse_hf_uri(remote).is_bucket:
+        raise CLIError("`hf buckets cp` only works with buckets. Use `hf cp` or `hf repos cp` for repositories.")
+
+
+def _run_cp(src: str, dst: str | None, token: str | None) -> None:
+    api = get_hf_api(token=token)
+
+    src_is_stdin = src == "-"
+    dst_is_stdout = dst == "-"
+    src_is_hf = is_hf_uri(src)
+    dst_is_hf = dst is not None and is_hf_uri(dst)
+
+    # --- Remote to remote: delegate to copy_files (repo/bucket -> repo/bucket) ---
+    if src_is_hf and dst_is_hf:
+        assert dst is not None  # guaranteed by dst_is_hf
+        api.copy_files(src, dst)
+        out.result("Copied", src=src, dst=dst)
+        return
+
+    # --- At least one side must be a remote hf:// URI (rules out local->local, stdin->local, etc.) ---
+    if not src_is_hf and not dst_is_hf:
+        if dst is None:
+            raise typer.BadParameter("Missing destination. Provide a repo or bucket hf:// URI as DST.")
+        raise typer.BadParameter(
+            "One of SRC or DST must be a repo (hf://username/...) or bucket (hf://buckets/...) URI."
+        )
+
+    # --- Download: repo/bucket -> local file or stdout ---
+    if src_is_hf:
+        if dst_is_stdout:
+            _download_file_to_stdout(api, src)
+            return
+        _download_file_to_local(api, src, dst)
+        return
+
+    # --- Upload: local file or stdin -> repo/bucket ---
+    assert dst is not None  # guaranteed: reaching here means dst_is_hf is True
+    _upload_file_to_remote(api, src, dst, src_is_stdin=src_is_stdin)
+
+
+def _download_file_to_stdout(api: HfApi, src: str) -> None:
+    uri = parse_hf_uri(src)
+    filename = _source_filename(uri, src)
+    # Suppress progress bars to avoid polluting the piped output.
+    with disable_progress_bars():
+        with SoftTemporaryDirectory() as tmp_dir:
+            tmp_path = os.path.join(tmp_dir, filename)
+            _download_single(api, uri, tmp_path)
+            with open(tmp_path, "rb") as f:
+                while chunk := f.read(32_000_000):  # 32MB chunks
+                    sys.stdout.buffer.write(chunk)
+
+
+def _download_file_to_local(api: HfApi, src: str, dst: str | None) -> None:
+    uri = parse_hf_uri(src)
+    filename = _source_filename(uri, src)
+
+    if dst is None:
+        local_path = filename
+    elif os.path.isdir(dst) or dst.endswith(os.sep) or dst.endswith("/"):
+        local_path = os.path.join(dst, filename)
+    else:
+        local_path = dst
+
+    parent_dir = os.path.dirname(local_path)
+    if parent_dir:
+        os.makedirs(parent_dir, exist_ok=True)
+
+    _download_single(api, uri, local_path)
+    out.result("Downloaded", src=src, dst=local_path)
+
+
+def _download_single(api: HfApi, uri: HfUri, local_path: str) -> None:
+    """Download a single file (repo or bucket) to ``local_path``.
+
+    Used by `_download_file_to_local` and `_download_file_to_stdout`.
+    """
+    if uri.is_bucket:
+        api.download_bucket_files(uri.id, [(uri.path_in_repo, local_path)], raise_on_missing_files=True)
+    else:
+        # Download into a temporary folder next to the destination (rather than the shared cache)
+        # so the final move stays on the same filesystem and is instant. The temp folder is
+        # cleaned up automatically once the move is complete.
+        parent_dir = os.path.dirname(local_path) or "."
+        with SoftTemporaryDirectory(prefix=".tmp", dir=parent_dir) as tmp_dir:
+            downloaded_path = api.hf_hub_download(
+                repo_id=uri.id,
+                repo_type=uri.type,
+                filename=uri.path_in_repo,
+                revision=uri.revision,
+                local_dir=tmp_dir,
+            )
+            os.replace(downloaded_path, local_path)
+
+
+def _source_filename(uri: HfUri, src: str) -> str:
+    if uri.path_in_repo == "" or src.endswith("/"):
+        raise typer.BadParameter(
+            "Source path must include a file name, not just a repo/bucket or directory path."
+            " Use `hf download` or `hf buckets sync` to copy directories."
+        )
+    return uri.path_in_repo.rsplit("/", 1)[-1]
+
+
+def _upload_file_to_remote(api: HfApi, src: str, dst: str, *, src_is_stdin: bool) -> None:
+    uri = parse_hf_uri(dst)
+
+    if src_is_stdin:
+        if uri.path_in_repo == "" or dst.endswith("/"):
+            raise typer.BadParameter("Stdin upload requires a full destination path including filename.")
+        data = sys.stdin.buffer.read()
+        _upload_single(api, uri, data, uri.path_in_repo)
+        out.result("Uploaded", src="stdin", dst=uri.to_uri())
+        return
+
+    if os.path.isdir(src):
+        raise typer.BadParameter(
+            "Source must be a file, not a directory. Use `hf upload` or `hf buckets sync` for directories."
+        )
+    if not os.path.isfile(src):
+        raise typer.BadParameter(f"Source file not found: {src}")
+
+    prefix = uri.path_in_repo
+    if prefix == "":
+        remote_path = os.path.basename(src)
+    elif dst.endswith("/"):
+        remote_path = prefix + "/" + os.path.basename(src)
+    else:
+        remote_path = prefix
+
+    _upload_single(api, uri, src, remote_path)
+    out.result("Uploaded", src=src, dst=replace(uri, path_in_repo=remote_path).to_uri())
+
+
+def _upload_single(api: HfApi, uri: HfUri, source: str | bytes, remote_path: str) -> None:
+    """Upload a single file or bytes (to a repo or bucket)."""
+    if uri.is_bucket:
+        api.batch_bucket_files(uri.id, add=[(source, remote_path)])
+    else:
+        api.upload_file(
+            path_or_fileobj=source,
+            path_in_repo=remote_path,
+            repo_id=uri.id,
+            repo_type=uri.type,
+            revision=uri.revision,
+        )

venv/Lib/site-packages/huggingface_hub/cli/_errors.py

@@ -0,0 +1,130 @@
+# Copyright 2026 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""CLI error handling utilities."""
+
+import traceback
+from collections.abc import Callable
+
+from huggingface_hub.errors import (
+    BucketNotFoundError,
+    CLIError,
+    CLIExtensionInstallError,
+    EntryNotFoundError,
+    GatedRepoError,
+    HfHubHTTPError,
+    HfUriError,
+    LocalEntryNotFoundError,
+    LocalTokenNotFoundError,
+    OfflineModeIsEnabled,
+    OIDCError,
+    RemoteEntryNotFoundError,
+    RepositoryNotFoundError,
+    RevisionNotFoundError,
+)
+
+
+def _format_repo_not_found(error: RepositoryNotFoundError) -> str:
+    label = error.repo_type.capitalize() if error.repo_type else "Repository"
+    if error.repo_id:
+        msg = f"{label} '{error.repo_id}' not found."
+    else:
+        msg = f"{label} not found."
+    msg += " If the repo is private, make sure you are authenticated and your token has the required permissions."
+    return msg
+
+
+def _format_gated_repo(error: GatedRepoError) -> str:
+    label = error.repo_type if error.repo_type else "repository"
+    if error.repo_id:
+        return f"Access denied. {label.capitalize()} '{error.repo_id}' requires approval."
+    return f"Access denied. This {label} requires approval."
+
+
+def _format_bucket_not_found(error: BucketNotFoundError) -> str:
+    if error.bucket_id:
+        return f"Bucket '{error.bucket_id}' not found. If the bucket is private, make sure you are authenticated and your token has the required permissions."
+    return "Bucket not found. Check the bucket id (namespace/name). If the bucket is private, make sure you are authenticated and your token has the required permissions."
+
+
+def _format_entry_not_found(error: RemoteEntryNotFoundError) -> str:
+    label = error.repo_type if error.repo_type else "repository"
+    url = str(error.response.url) if error.response else None
+    if error.repo_id:
+        msg = f"File not found in {label} '{error.repo_id}'."
+    else:
+        msg = f"File not found in {label}."
+    if url:
+        msg += f"\nURL: {url}"
+    return msg
+
+
+def _format_local_entry_not_found(error: LocalEntryNotFoundError) -> str:
+    cause = error.__cause__
+    if cause is not None:
+        return f"Local entry not found. {cause}"
+    return f"Local entry not found. {error}"
+
+
+def _format_revision_not_found(error: RevisionNotFoundError) -> str:
+    label = error.repo_type if error.repo_type else "repository"
+    if error.repo_id:
+        return f"Revision not found in {label} '{error.repo_id}'."
+    return f"Revision not found in {label}. Check the revision parameter."
+
+
+def _format_cli_error(error: CLIError) -> str:
+    """No traceback, just the error message."""
+    return str(error)
+
+
+def _format_cli_extension_install_error(error: CLIExtensionInstallError) -> str:
+    """Format a CLI extension installation error.
+
+    The error is likely to be a tricky subprocess error to investigate. In this specific case we want to format the
+    traceback of the root cause while keeping the "nicely formatted" error message of the CLIExtensionInstallError
+    as a 1-line message.
+    """
+    cause_tb = (
+        "".join(traceback.format_exception(type(error.__cause__), error.__cause__, error.__cause__.__traceback__))
+        if error.__cause__ is not None
+        else ""
+    )
+    return f"{cause_tb}\n{error}"
+
+
+CLI_ERROR_MAPPINGS: dict[type[Exception], Callable[..., str]] = {
+    OfflineModeIsEnabled: lambda error: str(error),
+    # GatedRepoError must come before RepositoryNotFoundError (it's a subclass).
+    GatedRepoError: _format_gated_repo,
+    BucketNotFoundError: _format_bucket_not_found,
+    RepositoryNotFoundError: _format_repo_not_found,
+    RevisionNotFoundError: _format_revision_not_found,
+    LocalTokenNotFoundError: lambda _: "Not logged in. Run 'hf auth login' first.",
+    OIDCError: lambda error: f"OIDC Exchange failed. {error}",
+    RemoteEntryNotFoundError: _format_entry_not_found,
+    LocalEntryNotFoundError: _format_local_entry_not_found,
+    EntryNotFoundError: lambda error: str(error),
+    HfHubHTTPError: lambda error: str(error),
+    HfUriError: lambda error: f"Invalid HF URI: {error.uri}. {error.msg}",
+    ValueError: lambda error: f"Invalid value. {error}",
+    CLIExtensionInstallError: _format_cli_extension_install_error,
+    CLIError: _format_cli_error,
+}
+
+
+def format_known_exception(error: Exception) -> str | None:
+    for exc_type, formatter in CLI_ERROR_MAPPINGS.items():
+        if isinstance(error, exc_type):
+            return formatter(error)
+    return None

venv/Lib/site-packages/huggingface_hub/cli/_file_listing.py

@@ -0,0 +1,225 @@
+# Copyright 2026-present, the HuggingFace Inc. team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Shared helpers for listing files in buckets and repos (tree view, flat view, formatting)."""
+
+import json
+from datetime import datetime
+from typing import Sequence
+
+import typer
+
+from huggingface_hub._buckets import BucketFile, BucketFolder
+from huggingface_hub.hf_api import RepoFile, RepoFolder
+
+from ._cli_utils import get_hf_api
+from ._output import OutputFormat, _dataclass_to_dict, out
+
+
+BucketItem = BucketFile | BucketFolder
+RepoItem = RepoFile | RepoFolder
+ListingItem = BucketItem | RepoItem
+
+
+def get_item_date(item: ListingItem) -> datetime | None:
+    """Extract date from an item, supporting both repo items (last_commit.date) and bucket items (mtime/uploaded_at)."""
+    match item:
+        case BucketFile(mtime=mtime) if mtime is not None:
+            return mtime
+        case BucketFile(uploaded_at=uploaded_at) | BucketFolder(uploaded_at=uploaded_at) if uploaded_at is not None:
+            return uploaded_at
+        case RepoFile(last_commit=last_commit) | RepoFolder(last_commit=last_commit) if last_commit is not None:
+            return last_commit.date
+        case _:
+            return None
+
+
+def format_size(size: int | float, human_readable: bool = False) -> str:
+    """Format a size in bytes."""
+    if not human_readable:
+        return str(size)
+
+    for unit in ["B", "KB", "MB", "GB", "TB"]:
+        if size < 1000:
+            if unit == "B":
+                return f"{size} {unit}"
+            return f"{size:.1f} {unit}"
+        size /= 1000
+    return f"{size:.1f} PB"
+
+
+def format_date(dt: datetime | None, human_readable: bool = False) -> str:
+    """Format a datetime to a readable date string."""
+    if dt is None:
+        return ""
+    if human_readable:
+        return dt.strftime("%b %d %H:%M")
+    return dt.strftime("%Y-%m-%d %H:%M:%S")
+
+
+def build_tree(
+    items: Sequence[BucketItem] | Sequence[RepoItem],
+    human_readable: bool = False,
+    quiet: bool = False,
+) -> list[str]:
+    """Build a tree representation of files and directories.
+
+    Produces ASCII tree with size and date columns before the tree connector.
+    When quiet=True, only the tree structure is shown (no size/date).
+    """
+    tree: dict = {}
+
+    for item in items:
+        parts = item.path.split("/")
+        current = tree
+        for part in parts[:-1]:
+            if part not in current:
+                current[part] = {"__children__": {}}
+            current = current[part]["__children__"]
+
+        final_part = parts[-1]
+        if isinstance(item, BucketFolder | RepoFolder):
+            if final_part not in current:
+                current[final_part] = {"__children__": {}}
+        else:
+            current[final_part] = {"__item__": item}
+
+    prefix_width = 0
+    max_size_width = 0
+    max_date_width = 0
+    if not quiet:
+        for item in items:
+            if isinstance(item, BucketFile | RepoFile):
+                size_str = format_size(item.size, human_readable)
+                max_size_width = max(max_size_width, len(size_str))
+                date_str = format_date(get_item_date(item), human_readable)
+                max_date_width = max(max_date_width, len(date_str))
+        if max_size_width > 0:
+            prefix_width = max_size_width + 2 + max_date_width
+
+    lines: list[str] = []
+    _render_tree(
+        tree,
+        lines,
+        "",
+        prefix_width=prefix_width,
+        max_size_width=max_size_width,
+        human_readable=human_readable,
+    )
+    return lines
+
+
+def _render_tree(
+    node: dict,
+    lines: list[str],
+    indent: str,
+    prefix_width: int = 0,
+    max_size_width: int = 0,
+    human_readable: bool = False,
+) -> None:
+    """Recursively render a tree structure with size+date prefix."""
+    sorted_items = sorted(node.items())
+    for i, (name, value) in enumerate(sorted_items):
+        is_last = i == len(sorted_items) - 1
+        connector = "└── " if is_last else "├── "
+
+        is_dir = "__children__" in value
+        children = value.get("__children__", {})
+
+        if prefix_width > 0:
+            if is_dir:
+                prefix = " " * prefix_width
+            else:
+                item = value.get("__item__")
+                if item is not None:
+                    size_str = format_size(item.size, human_readable)
+                    date_str = format_date(get_item_date(item), human_readable)
+                    prefix = f"{size_str:>{max_size_width}}  {date_str}"
+                else:
+                    prefix = " " * prefix_width
+            lines.append(f"{prefix}  {indent}{connector}{name}{'/' if is_dir else ''}")
+        else:
+            lines.append(f"{indent}{connector}{name}{'/' if is_dir else ''}")
+
+        if children:
+            child_indent = indent + ("    " if is_last else "│   ")
+            _render_tree(
+                children,
+                lines,
+                child_indent,
+                prefix_width=prefix_width,
+                max_size_width=max_size_width,
+                human_readable=human_readable,
+            )
+
+
+def list_repo_files_cmd(
+    repo_id: str,
+    repo_type: str,
+    human_readable: bool,
+    as_tree: bool,
+    recursive: bool,
+    revision: str | None,
+    token: str | None,
+) -> None:
+    """List files in a repo on the Hub. Used by models/datasets/spaces ls commands."""
+    if as_tree and out.mode == OutputFormat.json:
+        raise typer.BadParameter("Cannot use --tree with --format json.")
+
+    api = get_hf_api(token=token)
+    items = list(api.list_repo_tree(repo_id, recursive=recursive, revision=revision, repo_type=repo_type, expand=True))
+    print_file_listing(items, human_readable=human_readable, as_tree=as_tree, recursive=recursive)
+
+
+def print_file_listing(
+    items: Sequence[BucketItem] | Sequence[RepoItem],
+    *,
+    human_readable: bool = False,
+    as_tree: bool = False,
+    recursive: bool = False,
+) -> None:
+    """Print a file listing in the appropriate format based on the current output mode.
+
+    Supports tree, json, quiet, and flat human-readable views. Works with both
+    BucketFile/BucketFolder and RepoFile/RepoFolder items.
+    """
+    if not items:
+        out.text("(empty)")
+        return
+
+    has_directories = any(isinstance(item, BucketFolder | RepoFolder) for item in items)
+
+    if as_tree:
+        quiet = out.mode == OutputFormat.quiet
+        for line in build_tree(items, human_readable=human_readable, quiet=quiet):
+            print(line)
+    elif out.mode == OutputFormat.json:
+        print(json.dumps([_dataclass_to_dict(item) for item in items], indent=2))
+    elif out.mode == OutputFormat.quiet:
+        for item in items:
+            if isinstance(item, BucketFolder | RepoFolder):
+                print(f"{item.path}/")
+            else:
+                print(item.path)
+    else:
+        for item in items:
+            if isinstance(item, BucketFolder | RepoFolder):
+                date_str = format_date(get_item_date(item), human_readable)
+                print(f"{'':>12}  {date_str:>19}  {item.path}/")
+            else:
+                size_str = format_size(item.size, human_readable)
+                date_str = format_date(get_item_date(item), human_readable)
+                print(f"{size_str:>12}  {date_str:>19}  {item.path}")
+
+    if not recursive and has_directories:
+        out.hint("Use -R to list files recursively.")

venv/Lib/site-packages/huggingface_hub/cli/_help_formatter.py

@@ -0,0 +1,34 @@
+# Copyright 2026 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Pretty ANSI help formatter for the `hf` CLI."""
+
+from collections.abc import Sequence
+
+import click
+
+from huggingface_hub.utils import ANSI
+
+
+class StyledHelpFormatter(click.HelpFormatter):
+    def write_heading(self, heading: str) -> None:
+        styled = ANSI.underline(heading + ":")
+        self.write(f"{'':>{self.current_indent}}{styled}\n")
+
+    def write_dl(self, rows: Sequence[tuple[str, str]], col_max: int = 30, col_spacing: int = 2) -> None:
+        rows = [(ANSI.bold(first), second) for first, second in rows]
+        super().write_dl(rows, col_max=col_max, col_spacing=col_spacing)
+
+
+class StyledContext(click.Context):
+    formatter_class = StyledHelpFormatter

venv/Lib/site-packages/huggingface_hub/cli/_output.py

@@ -0,0 +1,345 @@
+# Copyright 2026 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Output framework for the `hf` CLI."""
+
+import dataclasses
+import datetime
+import json
+import re
+import shutil
+import sys
+from collections.abc import Sequence
+from enum import Enum
+from typing import Any, cast
+
+import typer
+
+from huggingface_hub.errors import ConfirmationError
+from huggingface_hub.utils import ANSI, StatusLine, disable_progress_bars, is_agent, tabulate
+
+
+class OutputFormat(str, Enum):
+    """Output format for CLI commands with auto detection of agent/human mode."""
+
+    agent = "agent"
+    auto = "auto"
+    human = "human"
+    json = "json"
+    quiet = "quiet"
+
+
+class Output:
+    """Output sink for the `hf` CLI.
+
+    Mode is resolved once at init time based on `is_agent()` auto-detection
+    and can be overridden per-command via `set_mode()`.
+    """
+
+    mode: OutputFormat
+    no_truncate: bool
+
+    def __init__(self) -> None:
+        self.no_truncate = False
+        self.set_mode()
+
+    def set_mode(self, mode: OutputFormat = OutputFormat.auto) -> None:
+        """Override the output mode (called once at startup and again per '--format' flag)."""
+        if mode == OutputFormat.auto:
+            mode = OutputFormat.agent if is_agent() else OutputFormat.human
+        self.mode = mode
+        if mode != OutputFormat.human:
+            disable_progress_bars()
+
+    def set_no_truncate(self, no_truncate: bool) -> None:
+        """Toggle off cell truncation for human table output."""
+        self.no_truncate = no_truncate
+
+    def is_quiet(self) -> bool:
+        return self.mode == OutputFormat.quiet
+
+    def text(self, msg: str | None = None, *, human: str | None = None, agent: str | None = None) -> None:
+        """Print a free-form text message to stdout."""
+        if msg is not None:
+            if human is not None or agent is not None:
+                raise ValueError("Cannot mix 'msg' with 'human'/'agent'.")
+            human = msg
+            agent = _strip_ansi(msg)
+
+        match self.mode:
+            case OutputFormat.human:
+                if human is not None:
+                    print(human)
+            case OutputFormat.agent:
+                if agent is not None:
+                    print(agent)
+            # json/quiet: no-op
+
+    def table(
+        self,
+        items: Sequence[dict[str, Any]],
+        *,
+        headers: list[str] | None = None,
+        id_key: str | None = None,
+        alignments: dict[str, str] | None = None,
+    ) -> None:
+        """Print tabular data to stdout.
+
+        Args:
+            items: List of dicts. Headers are auto-detected from keys if not provided.
+            headers: Explicit column names. If None, derived from dict keys (all-None columns filtered).
+            id_key: Key to print in quiet mode. If None, uses the first header.
+            alignments: Optional mapping of header name to "left" or "right". Defaults to "left".
+        """
+        if not items:
+            match self.mode:
+                case OutputFormat.agent | OutputFormat.human:
+                    print("No results found.")
+                case OutputFormat.json:
+                    print("[]")
+            return
+
+        if headers is None:
+            all_columns = list(items[0].keys())
+            headers = [col for col in all_columns if any(item.get(col) is not None for item in items)]
+        rows = [[item.get(h) for h in headers] for item in items]
+
+        match self.mode:
+            case OutputFormat.human:  # padded table, adaptive truncation, SCREAMING_SNAKE headers
+                screaming_headers = [_to_header(h) for h in headers]
+                formatted_rows: list[list[str]] = [[_format_table_value_human(v) for v in row] for row in rows]
+
+                is_truncated = _truncate_columns(screaming_headers, formatted_rows, no_truncate=self.no_truncate)
+
+                inferred = {**_infer_alignments(headers, rows), **(alignments or {})}
+                screaming_alignments = {_to_header(k): v for k, v in inferred.items()}
+                print(
+                    tabulate(
+                        cast("list[list[str | int]]", formatted_rows),
+                        headers=screaming_headers,
+                        alignments=screaming_alignments,
+                    )
+                )
+                if is_truncated:
+                    self.hint("Use `--no-truncate` or `--format json` to display full values.")
+            case OutputFormat.agent:  # TSV, no truncation, full timestamps
+                print("\t".join(headers))
+                for row in rows:
+                    print("\t".join(_format_table_cell_agent(v) for v in row))
+            case OutputFormat.json:  # compact JSON array
+                print(json.dumps(list(items), default=str))
+            case OutputFormat.quiet:  # id_key column (or first column), one per line
+                quiet_key = id_key or headers[0]
+                for item in items:
+                    print(item.get(quiet_key, ""))
+
+    def dict(self, data: Any, *, id_key: str | None = None) -> None:
+        """Print structured data as JSON in all modes (indented for human, compact otherwise).
+
+        Accepts a dict or a dataclass.
+        """
+        if dataclasses.is_dataclass(data) and not isinstance(data, type):
+            data = _dataclass_to_dict(data)
+        if self.mode == OutputFormat.quiet and id_key is not None:
+            print(data.get(id_key, ""))
+            return
+        indent = 2 if self.mode == OutputFormat.human else None
+        print(json.dumps(data, indent=indent, default=str))
+
+    def result(self, message: str, **data: Any) -> None:
+        """Print a success summary to stdout."""
+        match self.mode:
+            case OutputFormat.human:  # ✓ message + key: value lines
+                parts = [ANSI.green(f"✓ {message}")]
+                for k, v in data.items():
+                    if v is not None:
+                        parts.append(f"  {k}: {v}")
+                print("\n".join(parts))
+            case OutputFormat.agent:  # key=val pairs, space-separated
+                parts = [f"{k}={v}" for k, v in data.items() if v is not None]
+                print(" ".join(parts) if parts else message)
+            case OutputFormat.json:  # json.dumps(data), message ignored
+                print(json.dumps(data, default=str) if data else "")
+            case OutputFormat.quiet:  # first value only
+                values = list(data.values())
+                if values:
+                    print(values[0])
+
+    def confirm(self, message: str, *, default: bool = False, yes: bool = False, confirm_param: str = "--yes") -> None:
+        """
+        Ask for confirmation. Raises `ConfirmationError` in non-human modes.
+        """
+        if yes:
+            return
+        if self.mode != OutputFormat.human:
+            raise ConfirmationError(f"{message} Use {confirm_param} to skip confirmation.")
+        typer.confirm(message, default=default, abort=True)
+
+    def status(self, message: str | None = None) -> StatusLine:
+        """Return a status line that emits only in human mode (no-op otherwise)."""
+        status = StatusLine(enabled=self.mode == OutputFormat.human)
+        if message is not None:
+            status.update(message)
+        return status
+
+    def warning(self, message: str) -> None:
+        """Print a non-fatal warning to stderr (all modes)."""
+        if self.mode == OutputFormat.human:
+            print(ANSI.yellow(f"Warning: {message}"), file=sys.stderr)
+        else:
+            print(f"Warning: {message}", file=sys.stderr)
+
+    def error(self, message: str) -> None:
+        """Print an error to stderr (all modes)."""
+        if self.mode == OutputFormat.human:
+            print(ANSI.red(f"Error: {message}"), file=sys.stderr)
+        else:
+            print(f"Error: {message}", file=sys.stderr)
+
+    def hint(self, message: str) -> None:
+        """Print a helpful hint to stderr (human: gray, json/agent: plain text).
+
+        Suppressed in quiet mode. Kept in json mode (like agent) since agents
+        commonly run with ``--format json`` and the next-command hints are useful
+        there; hints go to stderr so they never pollute the parsed stdout.
+        """
+        if self.mode == OutputFormat.quiet:
+            return
+        if self.mode == OutputFormat.human:
+            print(ANSI.gray(f"Hint: {message}"), file=sys.stderr)
+        else:
+            print(f"Hint: {message}", file=sys.stderr)
+
+
+# HELPERS
+
+
+def _serialize_value(v: object) -> object:
+    """Recursively serialize a value to be JSON-compatible."""
+    if isinstance(v, datetime.datetime):
+        return v.isoformat()
+    elif isinstance(v, dict):
+        return {key: _serialize_value(val) for key, val in v.items() if val is not None}
+    elif isinstance(v, list):
+        return [_serialize_value(item) for item in v]
+    return v
+
+
+def _dataclass_to_dict(info: Any) -> dict[str, Any]:
+    """Convert a dataclass to a json-serializable dict."""
+    return {k: _serialize_value(v) for k, v in dataclasses.asdict(info).items() if v is not None}
+
+
+_ANSI_RE = re.compile(r"\033\[[0-9;]*m")
+
+
+def _strip_ansi(text: str) -> str:
+    return _ANSI_RE.sub("", text)
+
+
+def _single_line(text: str) -> str:
+    return " ".join(text.split())
+
+
+def _to_header(name: str) -> str:
+    """Convert a camelCase or PascalCase string to SCREAMING_SNAKE_CASE."""
+    s = re.sub(r"([a-z])([A-Z])", r"\1_\2", name)
+    return s.upper()
+
+
+def _infer_alignments(headers: list[str], rows: list[list[Any]]) -> dict[str, str]:
+    """Return ``{"col": "right"}`` for columns where every non-None value is numeric."""
+    result: dict[str, str] = {}
+    for c, h in enumerate(headers):
+        if all(row[c] is None or (isinstance(row[c], (int, float)) and not isinstance(row[c], bool)) for row in rows):
+            result[h] = "right"
+    return result
+
+
+def _format_table_value_human(value: Any) -> str:
+    """Convert a value to string for terminal display."""
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "✔" if value else ""
+    if isinstance(value, datetime.datetime):
+        return value.strftime("%Y-%m-%d")
+    if isinstance(value, str) and re.match(r"^\d{4}-\d{2}-\d{2}T", value):
+        return value[:10]
+    if isinstance(value, str):
+        return _single_line(value)
+    if isinstance(value, list):
+        return ", ".join(_format_table_value_human(v) for v in value)
+    elif isinstance(value, dict):
+        if "name" in value:  # Likely to be a user or org => print name
+            return _single_line(str(value["name"]))
+        return _single_line(json.dumps(value))
+    return _single_line(str(value))
+
+
+def _truncate_columns(
+    headers: list[str],
+    rows: list[list[str]],
+    *,
+    no_truncate: bool,
+) -> bool:
+    """Truncate cells in-place to fit the current terminal width.
+
+    Returns `True` if any cell was truncated, so the caller can emit a hint.
+    `shutil.get_terminal_size` is cross-platform: it honors `$COLUMNS`, then
+    queries the OS-native API, then falls back to `(80, 24)`.
+    """
+    if no_truncate or not rows:
+        return False
+
+    n = len(headers)
+    # Per-column natural width: longest of header label and cell values.
+    natural = [max(len(headers[c]), *(len(rows[r][c]) for r in range(len(rows)))) for c in range(n)]
+
+    # `max(0, n - 1)` accounts for the single-space separator between columns.
+    budget = shutil.get_terminal_size().columns - max(0, n - 1)
+    if sum(natural) <= budget:
+        return False
+
+    # Shrink the widest column 1 char at a time. Floors keep the header label
+    # visible; the `4` is the smallest cap that still shows "x..." (one content
+    # char plus the "..." marker).
+    caps = natural.copy()
+    min_widths = [max(len(h), 4) for h in headers]
+    while sum(caps) > budget:
+        widest = max(
+            (i for i, w in enumerate(caps) if w > min_widths[i]),
+            key=lambda i: caps[i],
+            default=-1,
+        )
+        if widest < 0:
+            break  # everything at floor — table wraps slightly
+        caps[widest] -= 1
+
+    truncated = False
+    for row in rows:
+        for c, cell in enumerate(row):
+            if len(cell) > caps[c]:
+                truncated = True
+                row[c] = cell[: caps[c] - 3] + "..."
+    return truncated
+
+
+def _format_table_cell_agent(value: Any) -> str:
+    """Format a cell value for agent TSV output (ISO timestamps, tabs escaped)."""
+    if isinstance(value, datetime.datetime):
+        return value.isoformat()
+    return _single_line(str(value))
+
+
+out = Output()

venv/Lib/site-packages/huggingface_hub/cli/_skills.py

@@ -0,0 +1,260 @@
+"""Internal helpers for Hugging Face marketplace skill installation and upgrades."""
+
+import json
+import shutil
+import tempfile
+from dataclasses import dataclass, replace
+from pathlib import Path, PurePosixPath
+from typing import Any, Literal
+
+from huggingface_hub._buckets import BucketFile
+from huggingface_hub.errors import CLIError
+
+from ..utils import disable_progress_bars
+from ._cli_utils import get_hf_api
+
+
+DEFAULT_SKILLS_BUCKET_ID = "huggingface/skills"
+MARKETPLACE_PATH = "marketplace.json"
+# Empty marker file dropped into managed skill installs so `hf skills update` knows
+# to touch them and leave user-placed skill dirs alone. Filename is historical (used
+# to be a JSON manifest with a revision); we keep it for backward compat with installs
+# made by previous versions.
+MANAGED_MARKER_FILENAME = ".hf-skill-manifest.json"
+
+SkillUpdateStatus = Literal["up_to_date", "unmanaged", "source_unreachable"]
+
+
+@dataclass(frozen=True)
+class MarketplaceSkill:
+    name: str
+    repo_path: str
+    description: str | None = None
+
+
+@dataclass(frozen=True)
+class SkillUpdateInfo:
+    name: str
+    skill_dir: Path
+    status: SkillUpdateStatus
+    detail: str | None = None
+
+
+def add_skill(skill_name: str, destination_root: Path, force: bool = False) -> Path:
+    """Resolve a marketplace skill by name and install it."""
+    api = get_hf_api()
+    with disable_progress_bars():
+        marketplace_skills = _load_marketplace_skills(api)
+        skill = _select_marketplace_skill(marketplace_skills, skill_name)
+        if skill is None:
+            raise CLIError(
+                f"Skill '{skill_name}' not found in {DEFAULT_SKILLS_BUCKET_ID}. "
+                "Try `hf skills add` to install `hf-cli` or use a known skill name."
+            )
+        return _install_marketplace_skill(api, skill, destination_root, force=force)
+
+
+def update_skills(roots: list[Path], selector: str | None = None) -> list[SkillUpdateInfo]:
+    """Re-sync managed marketplace skill installs from the bucket."""
+    skill_dirs = _iter_unique_skill_dirs(roots)
+    if selector is not None:
+        selector_lower = selector.strip().lower()
+        skill_dirs = [d for d in skill_dirs if d.name.lower() == selector_lower]
+        if not skill_dirs:
+            raise CLIError(f"No installed skill matches '{selector}'. Install it with `hf skills add {selector}`.")
+
+    api = get_hf_api()
+    with disable_progress_bars():
+        marketplace_skills = {skill.name.lower(): skill for skill in _load_marketplace_skills(api)}
+        return [_apply_single_update(api, skill_dir, marketplace_skills) for skill_dir in skill_dirs]
+
+
+def _load_marketplace_skills(api) -> list[MarketplaceSkill]:
+    payload = _load_marketplace_payload(api)
+    plugins = payload.get("plugins")
+    if not isinstance(plugins, list):
+        raise CLIError("Invalid marketplace payload: expected a top-level 'plugins' list.")
+
+    skills: list[MarketplaceSkill] = []
+    for plugin in plugins:
+        if not isinstance(plugin, dict):
+            continue
+        name = plugin.get("name")
+        source = plugin.get("source")
+        if not isinstance(name, str) or not isinstance(source, str):
+            continue
+        description = plugin.get("description")
+        skills.append(
+            MarketplaceSkill(
+                name=name,
+                repo_path=_normalize_repo_path(source),
+                description=description if isinstance(description, str) else None,
+            )
+        )
+    return skills
+
+
+def _install_marketplace_skill(api, skill: MarketplaceSkill, destination_root: Path, force: bool = False) -> Path:
+    """Install a marketplace skill into a local skills directory."""
+    destination_root = destination_root.expanduser().resolve()
+    destination_root.mkdir(parents=True, exist_ok=True)
+    install_dir = destination_root / skill.name
+    already_exists = install_dir.exists()
+
+    if already_exists and not force:
+        raise FileExistsError(f"Skill already exists: {install_dir}")
+
+    if already_exists:
+        # Stage the new content in a sibling tempdir and atomically rename, so the
+        # existing install stays intact if the download fails halfway through.
+        with tempfile.TemporaryDirectory(dir=destination_root, prefix=f".{install_dir.name}.install-") as tmp_dir_str:
+            staged_dir = Path(tmp_dir_str) / install_dir.name
+            _populate_install_dir(api, skill=skill, install_dir=staged_dir)
+            _atomic_replace_directory(existing_dir=install_dir, staged_dir=staged_dir)
+        return install_dir
+
+    try:
+        _populate_install_dir(api, skill=skill, install_dir=install_dir)
+    except Exception:
+        if install_dir.exists():
+            shutil.rmtree(install_dir)
+        raise
+    return install_dir
+
+
+def _load_marketplace_payload(api) -> dict[str, Any]:
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        local_path = Path(tmp_dir) / "marketplace.json"
+        api.download_bucket_files(
+            DEFAULT_SKILLS_BUCKET_ID,
+            [(MARKETPLACE_PATH, local_path)],
+            raise_on_missing_files=True,
+        )
+        parsed = json.loads(local_path.read_text(encoding="utf-8"))
+
+    if not isinstance(parsed, dict):
+        raise CLIError("Invalid marketplace payload: expected a JSON object.")
+    return parsed
+
+
+def _select_marketplace_skill(skills: list[MarketplaceSkill], selector: str) -> MarketplaceSkill | None:
+    selector_lower = selector.strip().lower()
+    for skill in skills:
+        if skill.name.lower() == selector_lower:
+            return skill
+    return None
+
+
+def _normalize_repo_path(path: str) -> str:
+    normalized = path.strip()
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+    normalized = normalized.strip("/")
+    if not normalized:
+        raise CLIError("Invalid marketplace entry: empty source path.")
+    return normalized
+
+
+def _populate_install_dir(api, skill: MarketplaceSkill, install_dir: Path) -> None:
+    install_dir.mkdir(parents=True, exist_ok=True)
+    bucket_files = _list_skill_files(api, skill)
+    _download_skill_files(api, skill, bucket_files, install_dir)
+    _validate_installed_skill_dir(install_dir)
+    (install_dir / MANAGED_MARKER_FILENAME).touch()
+
+
+def _validate_installed_skill_dir(skill_dir: Path) -> None:
+    skill_file = skill_dir / "SKILL.md"
+    if not skill_file.is_file():
+        raise RuntimeError(f"Installed skill is missing SKILL.md: {skill_file}")
+
+
+def _list_skill_files(api, skill: MarketplaceSkill) -> list[BucketFile]:
+    """List all files under `skill.repo_path` in the marketplace bucket."""
+    prefix = skill.repo_path.rstrip("/")
+    files: list[BucketFile] = [
+        item
+        for item in api.list_bucket_tree(DEFAULT_SKILLS_BUCKET_ID, prefix=prefix, recursive=True)
+        if isinstance(item, BucketFile)
+    ]
+    if not files:
+        raise FileNotFoundError(f"Path '{prefix}' not found in bucket '{DEFAULT_SKILLS_BUCKET_ID}'.")
+    return files
+
+
+def _download_skill_files(api, skill: MarketplaceSkill, files: list[BucketFile], install_dir: Path) -> None:
+    """Download bucket files into `install_dir`."""
+    prefix = skill.repo_path.rstrip("/")
+    prefix_with_slash = f"{prefix}/"
+
+    # `list_bucket_tree(prefix=...)` matches as a raw string prefix, so e.g. asking for
+    # "skills/gradio" can also return "skills/gradio-tools/...". Filter on the trailing
+    # slash to keep only files actually inside the directory, then strip it so files land
+    # directly under `install_dir` preserving any nested structure.
+    download_specs: list[tuple[str | BucketFile, str | Path]] = []
+    for bucket_file in files:
+        if not bucket_file.path.startswith(prefix_with_slash):
+            continue
+        relative = bucket_file.path[len(prefix_with_slash) :]
+        local_file = install_dir.joinpath(*PurePosixPath(relative).parts)
+        local_file.parent.mkdir(parents=True, exist_ok=True)
+        download_specs.append((bucket_file, local_file))
+
+    if not download_specs:
+        raise FileNotFoundError(f"No files found under '{prefix}' in bucket '{DEFAULT_SKILLS_BUCKET_ID}'.")
+
+    api.download_bucket_files(DEFAULT_SKILLS_BUCKET_ID, download_specs)
+
+
+def _atomic_replace_directory(existing_dir: Path, staged_dir: Path) -> None:
+    backup_dir = staged_dir.parent / f"{existing_dir.name}.backup"
+    try:
+        existing_dir.rename(backup_dir)
+        staged_dir.rename(existing_dir)
+        shutil.rmtree(backup_dir)
+    except Exception:
+        if backup_dir.exists() and not existing_dir.exists():
+            backup_dir.rename(existing_dir)
+        raise
+
+
+def _iter_unique_skill_dirs(roots: list[Path]) -> list[Path]:
+    seen: set[Path] = set()
+    discovered: list[Path] = []
+    for root in roots:
+        root = root.expanduser().resolve()
+        if not root.is_dir():
+            continue
+        for child in sorted(root.iterdir()):
+            if child.name.startswith("."):
+                continue
+            if not child.is_dir() and not child.is_symlink():
+                continue
+            resolved = child.resolve()
+            if resolved in seen or not resolved.is_dir():
+                continue
+            seen.add(resolved)
+            discovered.append(resolved)
+    return discovered
+
+
+def _apply_single_update(api, skill_dir: Path, marketplace_skills: dict[str, MarketplaceSkill]) -> SkillUpdateInfo:
+    base = SkillUpdateInfo(name=skill_dir.name, skill_dir=skill_dir, status="unmanaged")
+
+    if not (skill_dir / MANAGED_MARKER_FILENAME).exists():
+        return base
+
+    skill = marketplace_skills.get(skill_dir.name.lower())
+    if skill is None:
+        return replace(
+            base,
+            status="source_unreachable",
+            detail=f"Skill '{skill_dir.name}' is no longer available in {DEFAULT_SKILLS_BUCKET_ID}.",
+        )
+
+    try:
+        _install_marketplace_skill(api, skill, skill_dir.parent, force=True)
+    except Exception as exc:
+        return replace(base, status="source_unreachable", detail=str(exc))
+
+    return replace(base, status="up_to_date")

venv/Lib/site-packages/huggingface_hub/cli/auth.py

@@ -0,0 +1,174 @@
+# Copyright 2020 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains commands to authenticate to the Hugging Face Hub and interact with your repositories.
+
+Usage:
+    # login and save token locally.
+    hf auth login --token=hf_*** --add-to-git-credential
+
+    # switch between tokens
+    hf auth switch
+
+    # list all tokens
+    hf auth list
+
+    # logout from all tokens
+    hf auth logout
+
+    # check which account you are logged in as
+    hf auth whoami
+"""
+
+from typing import Annotated
+
+import typer
+
+from huggingface_hub.constants import ENDPOINT
+from huggingface_hub.hf_api import whoami
+
+from .._login import auth_list, auth_switch, login, logout
+from ..utils import get_stored_tokens, get_token, logging
+from ._cli_utils import TokenOpt, typer_factory
+from ._output import out
+
+
+logger = logging.get_logger(__name__)
+
+
+auth_cli = typer_factory(help="Manage authentication (login, logout, etc.).")
+
+
+@auth_cli.command(
+    "login",
+    examples=[
+        "hf auth login",
+        "hf auth login --token $HF_TOKEN",
+        "hf auth login --token $HF_TOKEN --add-to-git-credential",
+        "hf auth login --force",
+    ],
+)
+def auth_login(
+    token: TokenOpt = None,
+    add_to_git_credential: Annotated[
+        bool,
+        typer.Option(
+            help="Save to git credential helper. Useful only if you plan to run git commands directly.",
+        ),
+    ] = False,
+    force: Annotated[
+        bool,
+        typer.Option(
+            help="Force re-login even if already logged in.",
+        ),
+    ] = False,
+) -> None:
+    """Login using a token from huggingface.co/settings/tokens."""
+    login(token=token, add_to_git_credential=add_to_git_credential, skip_if_logged_in=not force)
+
+
+@auth_cli.command(
+    "logout",
+    examples=["hf auth logout", "hf auth logout --token-name my-token"],
+)
+def auth_logout(
+    token_name: Annotated[
+        str | None,
+        typer.Option(help="Name of token to logout"),
+    ] = None,
+) -> None:
+    """Logout from a specific token."""
+    logout(token_name=token_name)
+
+
+def _select_token_name() -> str | None:
+    token_names = list(get_stored_tokens().keys())
+
+    if not token_names:
+        logger.error("No stored tokens found. Please login first.")
+        return None
+
+    print("Available stored tokens:")
+    for i, token_name in enumerate(token_names, 1):
+        print(f"{i}. {token_name}")
+    while True:
+        try:
+            choice = input("Enter the number of the token to switch to (or 'q' to quit): ")
+            if choice.lower() == "q":
+                return None
+            index = int(choice) - 1
+            if 0 <= index < len(token_names):
+                return token_names[index]
+            else:
+                print("Invalid selection. Please try again.")
+        except ValueError:
+            print("Invalid input. Please enter a number or 'q' to quit.")
+
+
+@auth_cli.command(
+    "switch",
+    examples=["hf auth switch", "hf auth switch --token-name my-token"],
+)
+def auth_switch_cmd(
+    token_name: Annotated[
+        str | None,
+        typer.Option(
+            help="Name of the token to switch to",
+        ),
+    ] = None,
+    add_to_git_credential: Annotated[
+        bool,
+        typer.Option(
+            help="Save to git credential helper. Useful only if you plan to run git commands directly.",
+        ),
+    ] = False,
+) -> None:
+    """Switch between access tokens."""
+    if token_name is None:
+        token_name = _select_token_name()
+    if token_name is None:
+        print("No token name provided. Aborting.")
+        raise typer.Exit()
+    auth_switch(token_name, add_to_git_credential=add_to_git_credential)
+
+
+@auth_cli.command("list | ls", examples=["hf auth list"])
+def auth_list_cmd() -> None:
+    """List all stored access tokens."""
+    auth_list()
+
+
+@auth_cli.command("token", examples=["hf auth token", "hf auth token | xargs curl -H 'Authorization: Bearer {}'"])
+def auth_token() -> None:
+    """Print the current access token to stdout."""
+    token = get_token()
+    if token is None:
+        out.error("Not logged in. Run `hf auth login` first.")
+        raise typer.Exit(code=1)
+    print(token)
+    out.hint("Run `hf auth whoami` to see which account this token belongs to.")
+
+
+@auth_cli.command("whoami", examples=["hf auth whoami", "hf auth whoami --format json"])
+def auth_whoami() -> None:
+    """Find out which huggingface.co account you are logged in as."""
+
+    token = get_token()
+    if token is None:
+        out.error("Not logged in")
+        raise typer.Exit(code=1)
+
+    info = whoami(token)
+    orgs = ",".join(org["name"] for org in info["orgs"]) or None
+    endpoint = ENDPOINT if ENDPOINT != "https://huggingface.co" else None
+    out.result("Logged in", user=info["name"], orgs=orgs, endpoint=endpoint)

venv/Lib/site-packages/huggingface_hub/cli/buckets.py

@@ -0,0 +1,678 @@
+# Copyright 2025-present, the HuggingFace Inc. team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains commands to interact with buckets via the CLI."""
+
+from typing import Annotated
+
+import typer
+
+from huggingface_hub import logging
+from huggingface_hub._buckets import (
+    BUCKET_PREFIX,
+    BucketFile,
+    FilterMatcher,
+    _parse_bucket_uri,
+)
+
+from ..hf_api import REPO_REGIONS
+from ._cli_utils import (
+    SearchOpt,
+    TokenOpt,
+    get_hf_api,
+    typer_factory,
+)
+from ._cp import make_cp
+from ._file_listing import format_size, print_file_listing
+from ._output import OutputFormat, out
+
+
+logger = logging.get_logger(__name__)
+
+
+buckets_cli = typer_factory(help="Commands to interact with buckets.")
+
+
+@buckets_cli.command(
+    name="create",
+    examples=[
+        "hf buckets create my-bucket",
+        "hf buckets create user/my-bucket",
+        "hf buckets create hf://buckets/user/my-bucket",
+        "hf buckets create user/my-bucket --private",
+        "hf buckets create user/my-bucket --exist-ok",
+        "hf buckets create user/my-bucket --region us",
+    ],
+)
+def create(
+    bucket_id: Annotated[
+        str,
+        typer.Argument(
+            help="Bucket ID: bucket_name, namespace/bucket_name, or hf://buckets/namespace/bucket_name",
+        ),
+    ],
+    private: Annotated[
+        bool,
+        typer.Option(
+            "--private",
+            help="Create a private bucket.",
+        ),
+    ] = False,
+    region: Annotated[
+        REPO_REGIONS | None,
+        typer.Option(
+            "--region",
+            help="Cloud region in which to create the bucket. Can be one of 'us' or 'eu'. Requires Team plan or above.",
+        ),
+    ] = None,
+    exist_ok: Annotated[
+        bool,
+        typer.Option(
+            "--exist-ok",
+            help="Do not raise an error if the bucket already exists.",
+        ),
+    ] = False,
+    token: TokenOpt = None,
+) -> None:
+    """Create a new bucket."""
+    api = get_hf_api(token=token)
+
+    if bucket_id.startswith(BUCKET_PREFIX):
+        parsed = _parse_bucket_uri(bucket_id)
+        if parsed.path_in_repo:
+            raise typer.BadParameter(
+                f"Cannot specify a prefix for bucket creation: {bucket_id}."
+                f" Use namespace/bucket_name or {BUCKET_PREFIX}namespace/bucket_name."
+            )
+        bucket_id = parsed.id
+
+    bucket_url = api.create_bucket(
+        bucket_id,
+        private=private if private else None,
+        region=region,
+        exist_ok=exist_ok,
+    )
+    out.result("Bucket created", uri=bucket_url.uri.to_uri(), url=bucket_url.url)
+
+
+def _is_bucket_id(argument: str) -> bool:
+    """Check if argument is a bucket ID (namespace/name) vs just a namespace."""
+    if argument.startswith(BUCKET_PREFIX):
+        path = argument[len(BUCKET_PREFIX) :]
+    else:
+        path = argument
+    return "/" in path
+
+
+@buckets_cli.command(
+    name="list | ls",
+    examples=[
+        "hf buckets list",
+        "hf buckets list huggingface",
+        'hf buckets list --search "my-prefix"',
+        "hf buckets list user/my-bucket",
+        "hf buckets list user/my-bucket -R",
+        "hf buckets list user/my-bucket -h",
+        "hf buckets list user/my-bucket --tree",
+        "hf buckets list user/my-bucket --tree -h",
+        "hf buckets list hf://buckets/user/my-bucket",
+        "hf buckets list user/my-bucket/sub -R",
+    ],
+)
+def list_cmd(
+    argument: Annotated[
+        str | None,
+        typer.Argument(
+            help=(
+                "Namespace (user or org) to list buckets, or bucket ID"
+                " (namespace/bucket_name(/prefix) or hf://buckets/...) to list files."
+            ),
+        ),
+    ] = None,
+    human_readable: Annotated[
+        bool,
+        typer.Option(
+            "--human-readable",
+            "-h",
+            help="Show sizes in human readable format.",
+        ),
+    ] = False,
+    as_tree: Annotated[
+        bool,
+        typer.Option(
+            "--tree",
+            help="List files in tree format (only for listing files).",
+        ),
+    ] = False,
+    recursive: Annotated[
+        bool,
+        typer.Option(
+            "--recursive",
+            "-R",
+            help="List files recursively (only for listing files).",
+        ),
+    ] = False,
+    search: SearchOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """List buckets or files in a bucket.
+
+    When called with no argument or a namespace, lists buckets.
+    When called with a bucket ID (namespace/bucket_name), lists files in the bucket.
+    """
+    # Determine mode: listing buckets or listing files
+    is_file_mode = argument is not None and _is_bucket_id(argument)
+
+    if is_file_mode:
+        if search is not None:
+            raise typer.BadParameter("Cannot use --search when listing files.")
+        _list_files(
+            argument=argument,  # type: ignore
+            human_readable=human_readable,
+            as_tree=as_tree,
+            recursive=recursive,
+            token=token,
+        )
+    else:
+        _list_buckets(
+            namespace=argument,
+            search=search,
+            human_readable=human_readable,
+            as_tree=as_tree,
+            recursive=recursive,
+            token=token,
+        )
+
+
+def _list_buckets(
+    namespace: str | None,
+    search: str | None,
+    human_readable: bool,
+    as_tree: bool,
+    recursive: bool,
+    token: str | None,
+) -> None:
+    """List buckets in a namespace."""
+    # Validate incompatible flags
+    if as_tree:
+        raise typer.BadParameter("Cannot use --tree when listing buckets.")
+    if recursive:
+        raise typer.BadParameter("Cannot use --recursive when listing buckets.")
+
+    # Handle hf://buckets/namespace format
+    if namespace is not None and namespace.startswith(BUCKET_PREFIX):
+        namespace = namespace[len(BUCKET_PREFIX) :]
+        # Strip trailing slash if any
+        namespace = namespace.rstrip("/")
+
+    api = get_hf_api(token=token)
+    items = [
+        {
+            "id": bucket.id,
+            "private": bucket.private,
+            "size": format_size(bucket.size, human_readable) if human_readable else bucket.size,
+            "total_files": bucket.total_files,
+            "created_at": bucket.created_at,
+        }
+        for bucket in api.list_buckets(namespace=namespace, search=search)
+    ]
+    out.table(items, alignments={"size": "right"})
+
+
+def _list_files(
+    argument: str,
+    human_readable: bool,
+    as_tree: bool,
+    recursive: bool,
+    token: str | None,
+) -> None:
+    """List files in a bucket."""
+    if as_tree and out.mode == OutputFormat.json:
+        raise typer.BadParameter("Cannot use --tree with --format json.")
+
+    api = get_hf_api(token=token)
+    parsed = _parse_bucket_uri(argument)
+    items = list(
+        api.list_bucket_tree(
+            parsed.id,
+            prefix=parsed.path_in_repo or None,
+            recursive=recursive,
+        )
+    )
+
+    print_file_listing(items, human_readable=human_readable, as_tree=as_tree, recursive=recursive)
+
+
+@buckets_cli.command(
+    name="info",
+    examples=[
+        "hf buckets info user/my-bucket",
+        "hf buckets info hf://buckets/user/my-bucket",
+    ],
+)
+def info(
+    bucket_id: Annotated[
+        str,
+        typer.Argument(
+            help="Bucket ID: namespace/bucket_name or hf://buckets/namespace/bucket_name",
+        ),
+    ],
+    token: TokenOpt = None,
+) -> None:
+    """Get info about a bucket."""
+    api = get_hf_api(token=token)
+    parsed = _parse_bucket_uri(bucket_id)
+    bucket = api.bucket_info(parsed.id)
+    out.dict(bucket, id_key="id")
+
+
+@buckets_cli.command(
+    name="delete",
+    examples=[
+        "hf buckets delete user/my-bucket",
+        "hf buckets delete hf://buckets/user/my-bucket",
+        "hf buckets delete user/my-bucket --yes",
+        "hf buckets delete user/my-bucket --missing-ok",
+    ],
+)
+def delete(
+    bucket_id: Annotated[
+        str,
+        typer.Argument(
+            help="Bucket ID: namespace/bucket_name or hf://buckets/namespace/bucket_name",
+        ),
+    ],
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "--yes",
+            "-y",
+            help="Skip confirmation prompt.",
+        ),
+    ] = False,
+    missing_ok: Annotated[
+        bool,
+        typer.Option(
+            "--missing-ok",
+            help="Do not raise an error if the bucket does not exist.",
+        ),
+    ] = False,
+    token: TokenOpt = None,
+) -> None:
+    """Delete a bucket.
+
+    This deletes the entire bucket and all its contents. Use `hf buckets rm` to remove individual files.
+    """
+    if bucket_id.startswith(BUCKET_PREFIX):
+        parsed = _parse_bucket_uri(bucket_id)
+        if parsed.path_in_repo:
+            raise typer.BadParameter(
+                f"Cannot specify a prefix for bucket deletion: {bucket_id}."
+                f" Use namespace/bucket_name or {BUCKET_PREFIX}namespace/bucket_name."
+            )
+        bucket_id = parsed.id
+    elif "/" not in bucket_id:
+        raise typer.BadParameter(
+            f"Invalid bucket ID: {bucket_id}."
+            f" Must be in format namespace/bucket_name or {BUCKET_PREFIX}namespace/bucket_name."
+        )
+
+    out.confirm(f"Are you sure you want to delete bucket '{bucket_id}'?", yes=yes)
+
+    api = get_hf_api(token=token)
+    api.delete_bucket(bucket_id, missing_ok=missing_ok)
+    out.result("Bucket deleted", bucket_id=bucket_id)
+
+
+@buckets_cli.command(
+    name="remove | rm",
+    examples=[
+        "hf buckets remove user/my-bucket/file.txt",
+        "hf buckets rm hf://buckets/user/my-bucket/file.txt",
+        "hf buckets rm user/my-bucket/logs/ --recursive",
+        'hf buckets rm user/my-bucket --recursive --include "*.tmp"',
+        "hf buckets rm user/my-bucket/data/ --recursive --dry-run",
+    ],
+)
+def remove(
+    argument: Annotated[
+        str,
+        typer.Argument(
+            help=(
+                "Bucket path: namespace/bucket_name/path or hf://buckets/namespace/bucket_name/path."
+                " With --recursive, namespace/bucket_name is also accepted to target all files."
+            ),
+        ),
+    ],
+    recursive: Annotated[
+        bool,
+        typer.Option(
+            "--recursive",
+            "-R",
+            help="Remove files recursively under the given prefix.",
+        ),
+    ] = False,
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "--yes",
+            "-y",
+            help="Skip confirmation prompt.",
+        ),
+    ] = False,
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            "--dry-run",
+            help="Preview what would be deleted without actually deleting.",
+        ),
+    ] = False,
+    include: Annotated[
+        list[str] | None,
+        typer.Option(
+            help="Include only files matching pattern (can specify multiple). Requires --recursive.",
+        ),
+    ] = None,
+    exclude: Annotated[
+        list[str] | None,
+        typer.Option(
+            help="Exclude files matching pattern (can specify multiple). Requires --recursive.",
+        ),
+    ] = None,
+    token: TokenOpt = None,
+) -> None:
+    """Remove files from a bucket.
+
+    To delete an entire bucket, use `hf buckets delete` instead.
+    """
+    parsed = _parse_bucket_uri(argument)
+    bucket_id = parsed.id
+    prefix = parsed.path_in_repo
+
+    if prefix == "" and not recursive:
+        raise typer.BadParameter(
+            f"No file path specified. To remove files, provide a path"
+            f" (e.g. '{bucket_id}/FILE') or use --recursive to remove all files."
+            f" To delete the entire bucket, use `hf buckets delete {bucket_id}`."
+        )
+
+    if (include or exclude) and not recursive:
+        raise typer.BadParameter("--include and --exclude require --recursive.")
+
+    api = get_hf_api(token=token)
+
+    if recursive:
+        status = out.status("Listing files from remote")
+
+        all_files: list[BucketFile] = []
+        for item in api.list_bucket_tree(
+            bucket_id,
+            prefix=prefix or None,
+            recursive=True,
+        ):
+            if isinstance(item, BucketFile):
+                all_files.append(item)
+                status.update(f"Listing files from remote ({len(all_files)} files)")
+        status.done(f"Listing files from remote ({len(all_files)} files)")
+
+        if include or exclude:
+            matcher = FilterMatcher(include_patterns=include, exclude_patterns=exclude)
+            matched_files = [f for f in all_files if matcher.matches(f.path)]
+        else:
+            matched_files = all_files
+
+        file_paths = [f.path for f in matched_files]
+        total_size = sum(f.size for f in matched_files)
+        size_str = format_size(total_size, human_readable=True)
+
+        if not file_paths:
+            out.text("No files to remove.")
+            return
+
+        count_label = f"{len(file_paths)} file(s) totaling {size_str}"
+
+        if not yes and not dry_run:
+            out.text("\n".join(f"  {path}" for path in file_paths))
+            out.confirm(f"Remove {count_label} from '{bucket_id}'?", yes=False)
+
+        if dry_run:
+            out.text("\n".join(f"delete: {BUCKET_PREFIX}{bucket_id}/{path}" for path in file_paths))
+            out.text(f"(dry run) {count_label} would be removed.")
+            return
+
+        api.batch_bucket_files(bucket_id, delete=file_paths)
+        out.result(
+            f"Removed {count_label} from '{bucket_id}'",
+            bucket_id=bucket_id,
+            files_deleted=len(file_paths),
+            size=size_str,
+        )
+
+    else:
+        file_path = prefix
+        if not file_path:
+            raise typer.BadParameter("File path cannot be empty.")
+
+        if dry_run:
+            out.text(f"delete: {BUCKET_PREFIX}{bucket_id}/{file_path}")
+            out.text("(dry run) 1 file would be removed.")
+            return
+
+        out.confirm(f"Remove '{file_path}' from '{bucket_id}'?", yes=yes)
+
+        api.batch_bucket_files(bucket_id, delete=[file_path])
+        out.result("File removed", path=file_path, bucket_id=bucket_id)
+
+
+@buckets_cli.command(
+    name="move",
+    examples=[
+        "hf buckets move user/old-bucket user/new-bucket",
+        "hf buckets move user/my-bucket my-org/my-bucket",
+        "hf buckets move hf://buckets/user/old-bucket hf://buckets/user/new-bucket",
+    ],
+)
+def move(
+    from_id: Annotated[
+        str,
+        typer.Argument(
+            help="Source bucket ID: namespace/bucket_name or hf://buckets/namespace/bucket_name",
+        ),
+    ],
+    to_id: Annotated[
+        str,
+        typer.Argument(
+            help="Destination bucket ID: namespace/bucket_name or hf://buckets/namespace/bucket_name",
+        ),
+    ],
+    token: TokenOpt = None,
+) -> None:
+    """Move (rename) a bucket to a new name or namespace."""
+    # Parse from_id
+    parsed_from = _parse_bucket_uri(from_id)
+    if parsed_from.path_in_repo:
+        raise typer.BadParameter(
+            f"Cannot specify a prefix for bucket move: {from_id}."
+            f" Use namespace/bucket_name or {BUCKET_PREFIX}namespace/bucket_name."
+        )
+
+    # Parse to_id
+    parsed_to = _parse_bucket_uri(to_id)
+    if parsed_to.path_in_repo:
+        raise typer.BadParameter(
+            f"Cannot specify a prefix for bucket move: {to_id}."
+            f" Use namespace/bucket_name or {BUCKET_PREFIX}namespace/bucket_name."
+        )
+
+    api = get_hf_api(token=token)
+    api.move_bucket(from_id=parsed_from.id, to_id=parsed_to.id)
+    out.result("Bucket moved", from_id=parsed_from.id, to_id=parsed_to.id)
+
+
+# =============================================================================
+# Sync command
+# =============================================================================
+
+
+@buckets_cli.command(
+    name="sync",
+    examples=[
+        "hf buckets sync ./data hf://buckets/user/my-bucket",
+        "hf buckets sync hf://buckets/user/my-bucket ./data",
+        "hf buckets sync ./data hf://buckets/user/my-bucket --delete",
+        'hf buckets sync hf://buckets/user/my-bucket ./data --include "*.safetensors" --exclude "*.tmp"',
+        "hf buckets sync ./data hf://buckets/user/my-bucket --plan sync-plan.jsonl",
+        "hf buckets sync --apply sync-plan.jsonl",
+        "hf buckets sync ./data hf://buckets/user/my-bucket --dry-run",
+        "hf buckets sync ./data hf://buckets/user/my-bucket --dry-run | jq .",
+    ],
+)
+def sync(
+    source: Annotated[
+        str | None,
+        typer.Argument(
+            help="Source path: local directory or hf://buckets/namespace/bucket_name(/prefix)",
+        ),
+    ] = None,
+    dest: Annotated[
+        str | None,
+        typer.Argument(
+            help="Destination path: local directory or hf://buckets/namespace/bucket_name(/prefix)",
+        ),
+    ] = None,
+    delete: Annotated[
+        bool,
+        typer.Option(
+            help="Delete destination files not present in source.",
+        ),
+    ] = False,
+    ignore_times: Annotated[
+        bool,
+        typer.Option(
+            "--ignore-times",
+            help="Skip files only based on size, ignoring modification times.",
+        ),
+    ] = False,
+    ignore_sizes: Annotated[
+        bool,
+        typer.Option(
+            "--ignore-sizes",
+            help="Skip files only based on modification times, ignoring sizes.",
+        ),
+    ] = False,
+    plan: Annotated[
+        str | None,
+        typer.Option(
+            help="Save sync plan to JSONL file for review instead of executing.",
+        ),
+    ] = None,
+    apply: Annotated[
+        str | None,
+        typer.Option(
+            help="Apply a previously saved plan file.",
+        ),
+    ] = None,
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            "--dry-run",
+            help="Print sync plan to stdout as JSONL without executing.",
+        ),
+    ] = False,
+    include: Annotated[
+        list[str] | None,
+        typer.Option(
+            help="Include files matching pattern (can specify multiple).",
+        ),
+    ] = None,
+    exclude: Annotated[
+        list[str] | None,
+        typer.Option(
+            help="Exclude files matching pattern (can specify multiple).",
+        ),
+    ] = None,
+    filter_from: Annotated[
+        str | None,
+        typer.Option(
+            help="Read include/exclude patterns from file.",
+        ),
+    ] = None,
+    existing: Annotated[
+        bool,
+        typer.Option(
+            "--existing",
+            help="Skip creating new files on receiver (only update existing files).",
+        ),
+    ] = False,
+    ignore_existing: Annotated[
+        bool,
+        typer.Option(
+            "--ignore-existing",
+            help="Skip updating files that exist on receiver (only create new files).",
+        ),
+    ] = False,
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            help="Show detailed logging with reasoning.",
+        ),
+    ] = False,
+    token: TokenOpt = None,
+) -> None:
+    """Sync files between local directory and a bucket."""
+    api = get_hf_api(token=token)
+    api.sync_bucket(
+        source=source,
+        dest=dest,
+        delete=delete,
+        ignore_times=ignore_times,
+        ignore_sizes=ignore_sizes,
+        existing=existing,
+        ignore_existing=ignore_existing,
+        include=include,
+        exclude=exclude,
+        filter_from=filter_from,
+        plan=plan,
+        apply=apply,
+        dry_run=dry_run,
+        verbose=verbose,
+        quiet=out.is_quiet(),
+    )
+    if plan and not out.is_quiet():
+        out.hint(f"Run `hf buckets sync --apply {plan}` to execute this plan.")
+
+
+# =============================================================================
+# Cp command
+# =============================================================================
+
+
+# `hf buckets cp` is an alias for the top-level `hf cp` command (see `cli/_cp.py`).
+buckets_cli.command(
+    name="cp",
+    examples=[
+        # Download (repo or bucket -> local / stdout)
+        "hf buckets cp hf://buckets/username/my-bucket/config.json config.json",
+        "hf buckets cp hf://buckets/username/my-bucket/data.csv data/",
+        "hf buckets cp hf://buckets/username/my-bucket/config.json -",
+        # Upload (local / stdin -> bucket)
+        "hf buckets cp model.safetensors hf://buckets/username/my-bucket/model.safetensors",
+        "hf buckets cp config.json hf://buckets/username/my-bucket/logs/",
+        "hf buckets cp - hf://buckets/username/my-bucket/config.json",
+        # Remote to remote (repo or bucket -> bucket)
+        "hf buckets cp hf://buckets/username/my-bucket/data.csv hf://buckets/username/dest-bucket/",
+        "hf buckets cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/dest-bucket/logs/",
+    ],
+)(make_cp("buckets"))

venv/Lib/site-packages/huggingface_hub/cli/cache.py

@@ -0,0 +1,775 @@
+# Copyright 2025-present, the HuggingFace Inc. team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains the 'hf cache' command group with cache management subcommands."""
+
+import re
+import time
+from collections import defaultdict
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from enum import Enum
+from typing import Annotated, Any
+
+import typer
+
+from huggingface_hub.errors import CLIError
+
+from ..utils import (
+    ANSI,
+    CachedRepoInfo,
+    CachedRevisionInfo,
+    CacheNotFound,
+    HFCacheInfo,
+    _format_size,
+    parse_hf_uri,
+    scan_cache_dir,
+)
+from ..utils._parsing import parse_duration, parse_size
+from ._cli_utils import RepoIdArg, RepoTypeOpt, RevisionOpt, TokenOpt, get_hf_api, typer_factory
+from ._output import out
+
+
+cache_cli = typer_factory(help="Manage local cache directory.")
+
+
+#### Cache helper utilities
+
+
+@dataclass(frozen=True)
+class _DeletionResolution:
+    revisions: frozenset[str]
+    selected: dict[CachedRepoInfo, frozenset[CachedRevisionInfo]]
+    missing: tuple[str, ...]
+
+
+_FILTER_PATTERN = re.compile(r"^(?P<key>[a-zA-Z_]+)\s*(?P<op>==|!=|>=|<=|>|<|=)\s*(?P<value>.+)$")
+_ALLOWED_OPERATORS = {"=", "!=", ">", "<", ">=", "<="}
+_FILTER_KEYS = {"accessed", "modified", "refs", "size", "type"}
+_SORT_KEYS = {"accessed", "modified", "name", "size"}
+_SORT_PATTERN = re.compile(r"^(?P<key>[a-zA-Z_]+)(?::(?P<order>asc|desc))?$")
+_SORT_DEFAULT_ORDER = {
+    # Default ordering: accessed/modified/size are descending (newest/biggest first), name is ascending
+    "accessed": "desc",
+    "modified": "desc",
+    "size": "desc",
+    "name": "asc",
+}
+
+
+# Dynamically generate SortOptions enum from _SORT_KEYS
+_sort_options_dict = {}
+for key in sorted(_SORT_KEYS):
+    _sort_options_dict[key] = key
+    _sort_options_dict[f"{key}_asc"] = f"{key}:asc"
+    _sort_options_dict[f"{key}_desc"] = f"{key}:desc"
+
+SortOptions = Enum("SortOptions", _sort_options_dict, type=str, module=__name__)  # type: ignore
+
+
+@dataclass(frozen=True)
+class CacheDeletionCounts:
+    """Simple counters summarizing cache deletions for CLI messaging."""
+
+    repo_count: int
+    partial_revision_count: int
+    total_revision_count: int
+
+
+CacheEntry = tuple[CachedRepoInfo, CachedRevisionInfo | None]
+RepoRefsMap = dict[CachedRepoInfo, frozenset[str]]
+
+
+def summarize_deletions(
+    selected_by_repo: Mapping[CachedRepoInfo, frozenset[CachedRevisionInfo]],
+) -> CacheDeletionCounts:
+    """Summarize deletions across repositories."""
+    repo_count = 0
+    total_revisions = 0
+    revisions_in_full_repos = 0
+
+    for repo, revisions in selected_by_repo.items():
+        total_revisions += len(revisions)
+        if len(revisions) == len(repo.revisions):
+            repo_count += 1
+            revisions_in_full_repos += len(revisions)
+
+    partial_revision_count = total_revisions - revisions_in_full_repos
+    return CacheDeletionCounts(repo_count, partial_revision_count, total_revisions)
+
+
+def print_cache_selected_revisions(selected_by_repo: Mapping[CachedRepoInfo, frozenset[CachedRevisionInfo]]) -> None:
+    """Pretty-print selected cache revisions during confirmation prompts."""
+    for repo in sorted(selected_by_repo.keys(), key=lambda repo: (repo.repo_type, repo.repo_id.lower())):
+        repo_key = f"{repo.repo_type}/{repo.repo_id}"
+        revisions = sorted(selected_by_repo[repo], key=lambda rev: rev.commit_hash)
+        if len(revisions) == len(repo.revisions):
+            out.text(f"  - {repo_key} (entire repo)")
+            continue
+
+        out.text(f"  - {repo_key}:")
+        for revision in revisions:
+            refs = " ".join(sorted(revision.refs)) or "(detached)"
+            out.text(f"      {revision.commit_hash} [{refs}] {revision.size_on_disk_str}")
+
+
+def build_cache_index(
+    hf_cache_info: HFCacheInfo,
+) -> tuple[
+    dict[str, CachedRepoInfo],
+    dict[str, tuple[CachedRepoInfo, CachedRevisionInfo]],
+]:
+    """Create lookup tables so CLI commands can resolve repo ids and revisions quickly."""
+    repo_lookup: dict[str, CachedRepoInfo] = {}
+    revision_lookup: dict[str, tuple[CachedRepoInfo, CachedRevisionInfo]] = {}
+    for repo in hf_cache_info.repos:
+        repo_key = repo.cache_id.lower()
+        repo_lookup[repo_key] = repo
+        for revision in repo.revisions:
+            revision_lookup[revision.commit_hash.lower()] = (repo, revision)
+    return repo_lookup, revision_lookup
+
+
+def _repo_cache_id_from_target(target: str) -> str:
+    """Return the cache id matching a repo target passed to `hf cache rm`."""
+    if not target.startswith("hf://"):
+        return target
+
+    uri = parse_hf_uri(target)
+    if not uri.is_repo:
+        raise CLIError("Only repository hf:// URIs are supported by `hf cache rm`.")
+    if uri.revision is not None or uri.path_in_repo:
+        raise CLIError("Only repo-level hf:// URIs are supported by `hf cache rm` for now.")
+    return f"{uri.type}/{uri.id}"
+
+
+def collect_cache_entries(
+    hf_cache_info: HFCacheInfo, *, include_revisions: bool
+) -> tuple[list[CacheEntry], RepoRefsMap]:
+    """Flatten cache metadata into rows consumed by `hf cache ls`."""
+    entries: list[CacheEntry] = []
+    repo_refs_map: RepoRefsMap = {}
+    sorted_repos = sorted(hf_cache_info.repos, key=lambda repo: (repo.repo_type, repo.repo_id.lower()))
+    for repo in sorted_repos:
+        repo_refs_map[repo] = frozenset({ref for revision in repo.revisions for ref in revision.refs})
+        if include_revisions:
+            for revision in sorted(repo.revisions, key=lambda rev: rev.commit_hash):
+                entries.append((repo, revision))
+        else:
+            entries.append((repo, None))
+    if include_revisions:
+        entries.sort(
+            key=lambda entry: (
+                entry[0].cache_id,
+                entry[1].commit_hash if entry[1] is not None else "",
+            )
+        )
+    else:
+        entries.sort(key=lambda entry: entry[0].cache_id)
+    return entries, repo_refs_map
+
+
+def compile_cache_filter(
+    expr: str, repo_refs_map: RepoRefsMap
+) -> Callable[[CachedRepoInfo, CachedRevisionInfo | None, float], bool]:
+    """Convert a `hf cache ls` filter expression into the yes/no test we apply to each cache entry before displaying it."""
+    match = _FILTER_PATTERN.match(expr.strip())
+    if not match:
+        raise ValueError(f"Invalid filter expression: '{expr}'.")
+
+    key = match.group("key").lower()
+    op = match.group("op")
+    value_raw = match.group("value").strip()
+
+    if op not in _ALLOWED_OPERATORS:
+        raise ValueError(f"Unsupported operator '{op}' in filter '{expr}'. Must be one of {list(_ALLOWED_OPERATORS)}.")
+
+    if key not in _FILTER_KEYS:
+        raise ValueError(f"Unsupported filter key '{key}' in '{expr}'. Must be one of {list(_FILTER_KEYS)}.")
+    # at this point we know that key is in `_FILTER_KEYS`
+    if key == "size":
+        size_threshold = parse_size(value_raw)
+        return lambda repo, revision, _: _compare_numeric(
+            revision.size_on_disk if revision is not None else repo.size_on_disk,
+            op,
+            size_threshold,
+        )
+
+    if key in {"modified", "accessed"}:
+        seconds = parse_duration(value_raw.strip())
+
+        def _time_filter(repo: CachedRepoInfo, revision: CachedRevisionInfo | None, now: float) -> bool:
+            timestamp = (
+                repo.last_accessed
+                if key == "accessed"
+                else revision.last_modified
+                if revision is not None
+                else repo.last_modified
+            )
+            if timestamp is None:
+                return False
+            return _compare_numeric(now - timestamp, op, seconds)
+
+        return _time_filter
+
+    if key == "type":
+        expected = value_raw.lower()
+
+        if op != "=":
+            raise ValueError(f"Only '=' is supported for 'type' filters. Got '{op}'.")
+
+        def _type_filter(repo: CachedRepoInfo, revision: CachedRevisionInfo | None, _: float) -> bool:
+            return repo.repo_type.lower() == expected
+
+        return _type_filter
+
+    else:  # key == "refs"
+        if op != "=":
+            raise ValueError(f"Only '=' is supported for 'refs' filters. Got {op}.")
+
+        def _refs_filter(repo: CachedRepoInfo, revision: CachedRevisionInfo | None, _: float) -> bool:
+            refs = revision.refs if revision is not None else repo_refs_map.get(repo, frozenset())
+            return value_raw.lower() in [ref.lower() for ref in refs]
+
+        return _refs_filter
+
+
+def _compare_numeric(left: float | None, op: str, right: float) -> bool:
+    """Evaluate numeric comparisons for filters."""
+    if left is None:
+        return False
+
+    comparisons = {
+        "=": left == right,
+        "!=": left != right,
+        ">": left > right,
+        "<": left < right,
+        ">=": left >= right,
+        "<=": left <= right,
+    }
+
+    if op not in comparisons:
+        raise ValueError(f"Unsupported numeric comparison operator: {op}")
+
+    return comparisons[op]
+
+
+def compile_cache_sort(sort_expr: str) -> tuple[Callable[[CacheEntry], tuple[Any, ...]], bool]:
+    """Convert a `hf cache ls` sort expression into a key function for sorting entries.
+
+    Returns:
+        A tuple of (key_function, reverse_flag) where reverse_flag indicates whether
+        to sort in descending order (True) or ascending order (False).
+    """
+    match = _SORT_PATTERN.match(sort_expr.strip().lower())
+    if not match:
+        raise ValueError(f"Invalid sort expression: '{sort_expr}'. Expected format: 'key' or 'key:asc' or 'key:desc'.")
+
+    key = match.group("key").lower()
+    explicit_order = match.group("order")
+
+    if key not in _SORT_KEYS:
+        raise ValueError(f"Unsupported sort key '{key}' in '{sort_expr}'. Must be one of {list(_SORT_KEYS)}.")
+
+    # Use explicit order if provided, otherwise use default for the key
+    order = explicit_order if explicit_order else _SORT_DEFAULT_ORDER[key]
+    reverse = order == "desc"
+
+    def _sort_key(entry: CacheEntry) -> tuple[Any, ...]:
+        repo, revision = entry
+
+        if key == "name":
+            # Sort by cache_id (repo type/id)
+            value: Any = repo.cache_id.lower()
+            return (value,)
+
+        if key == "size":
+            # Use revision size if available, otherwise repo size
+            value = revision.size_on_disk if revision is not None else repo.size_on_disk
+            return (value,)
+
+        if key == "accessed":
+            # For revisions, accessed is not available per-revision, use repo's last_accessed
+            # For repos, use repo's last_accessed
+            value = repo.last_accessed if repo.last_accessed is not None else 0.0
+            return (value,)
+
+        if key == "modified":
+            # Use revision's last_modified if available, otherwise repo's last_modified
+            if revision is not None:
+                value = revision.last_modified if revision.last_modified is not None else 0.0
+            else:
+                value = repo.last_modified if repo.last_modified is not None else 0.0
+            return (value,)
+
+        # Should never reach here due to validation above
+        raise ValueError(f"Unsupported sort key: {key}")
+
+    return _sort_key, reverse
+
+
+def _resolve_deletion_targets(hf_cache_info: HFCacheInfo, targets: list[str]) -> _DeletionResolution:
+    """Resolve the deletion targets into a deletion resolution."""
+    repo_lookup, revision_lookup = build_cache_index(hf_cache_info)
+
+    selected: dict[CachedRepoInfo, set[CachedRevisionInfo]] = defaultdict(set)
+    revisions: set[str] = set()
+    missing: list[str] = []
+
+    for raw_target in targets:
+        target = raw_target.strip()
+        if not target:
+            continue
+        lowered = target.lower()
+
+        if re.fullmatch(r"[0-9a-fA-F]{40}", lowered):
+            match = revision_lookup.get(lowered)
+            if match is None:
+                missing.append(raw_target)
+                continue
+            repo, revision = match
+            selected[repo].add(revision)
+            revisions.add(revision.commit_hash)
+            continue
+
+        matched_repo = repo_lookup.get(_repo_cache_id_from_target(target).lower())
+        if matched_repo is None:
+            missing.append(raw_target)
+            continue
+
+        for revision in matched_repo.revisions:
+            selected[matched_repo].add(revision)
+            revisions.add(revision.commit_hash)
+
+    frozen_selected = {repo: frozenset(revs) for repo, revs in selected.items()}
+    return _DeletionResolution(
+        revisions=frozenset(revisions),
+        selected=frozen_selected,
+        missing=tuple(missing),
+    )
+
+
+#### Cache CLI commands
+
+
+@cache_cli.command(
+    "list | ls",
+    examples=[
+        "hf cache ls",
+        "hf cache ls --revisions",
+        'hf cache ls --filter "size>1GB" --limit 20',
+        "hf cache ls --format json",
+    ],
+)
+def ls(
+    cache_dir: Annotated[
+        str | None,
+        typer.Option(
+            help="Cache directory to scan (defaults to Hugging Face cache).",
+        ),
+    ] = None,
+    revisions: Annotated[
+        bool,
+        typer.Option(
+            help="Include revisions in the output instead of aggregated repositories.",
+        ),
+    ] = False,
+    filter: Annotated[
+        list[str] | None,
+        typer.Option(
+            "-f",
+            "--filter",
+            help="Filter entries (e.g. 'size>1GB', 'type=model', 'accessed>7d'). Can be used multiple times.",
+        ),
+    ] = None,
+    sort: Annotated[
+        SortOptions | None,
+        typer.Option(
+            help="Sort entries by key. Supported keys: 'accessed', 'modified', 'name', 'size'. "
+            "Append ':asc' or ':desc' to explicitly set the order (e.g., 'modified:asc'). "
+            "Defaults: 'accessed', 'modified', 'size' default to 'desc' (newest/biggest first); "
+            "'name' defaults to 'asc' (alphabetical).",
+        ),
+    ] = None,
+    limit: Annotated[
+        int | None,
+        typer.Option(
+            help="Limit the number of results returned. Returns only the top N entries after sorting.",
+        ),
+    ] = None,
+) -> None:
+    """List cached repositories or revisions."""
+    try:
+        hf_cache_info = scan_cache_dir(cache_dir)
+    except CacheNotFound as exc:
+        raise CLIError(f"Cache directory not found: {exc.cache_dir}") from exc
+
+    filters = filter or []
+
+    entries, repo_refs_map = collect_cache_entries(hf_cache_info, include_revisions=revisions)
+    try:
+        filter_fns = [compile_cache_filter(expr, repo_refs_map) for expr in filters]
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+    now = time.time()
+    for fn in filter_fns:
+        entries = [entry for entry in entries if fn(entry[0], entry[1], now)]
+
+    # Apply sorting if requested
+    if sort:
+        try:
+            sort_key_fn, reverse = compile_cache_sort(sort.value)
+            entries.sort(key=sort_key_fn, reverse=reverse)
+        except ValueError as exc:
+            raise typer.BadParameter(str(exc)) from exc
+
+    # Apply limit if requested
+    if limit is not None:
+        if limit < 0:
+            raise typer.BadParameter(f"Limit must be a positive integer, got {limit}.")
+        entries = entries[:limit]
+
+    if revisions:
+        items = [
+            {
+                "id": repo.cache_id,
+                "repo_id": repo.repo_id,
+                "repo_type": repo.repo_type,
+                "revision": revision.commit_hash,
+                "snapshot_path": str(revision.snapshot_path),
+                "size": revision.size_on_disk_str,
+                "last_modified": revision.last_modified_str,
+                "refs": sorted(revision.refs),
+            }
+            for repo, revision in entries
+            if revision is not None
+        ]
+        out.table(
+            items,
+            headers=["id", "revision", "size", "last_modified", "refs"],
+            id_key="revision",
+            alignments={"size": "right"},
+        )
+    else:
+        items = [
+            {
+                "id": repo.cache_id,
+                "repo_id": repo.repo_id,
+                "repo_type": repo.repo_type,
+                "size": repo.size_on_disk_str,
+                "last_accessed": repo.last_accessed_str or "",
+                "last_modified": repo.last_modified_str,
+                "refs": sorted(repo_refs_map.get(repo, frozenset())),
+            }
+            for repo, _ in entries
+        ]
+        out.table(
+            items,
+            headers=["id", "size", "last_accessed", "last_modified", "refs"],
+            id_key="id",
+            alignments={"size": "right"},
+        )
+
+    if entries:
+        unique_repos = {repo for repo, _ in entries}
+        repo_count = len(unique_repos)
+        if revisions:
+            revision_count = sum(1 for _, rev in entries if rev is not None)
+            total_size = sum(rev.size_on_disk for _, rev in entries if rev is not None)
+        else:
+            revision_count = sum(len(repo.revisions) for repo in unique_repos)
+            total_size = sum(repo.size_on_disk for repo in unique_repos)
+        out.text(
+            ANSI.bold(
+                f"\nFound {repo_count} repo(s) for a total of {revision_count} revision(s)"
+                f" and {_format_size(total_size)} on disk."
+            )
+        )
+
+
+@cache_cli.command(
+    examples=[
+        "hf cache rm model/gpt2",
+        "hf cache rm hf://models/openai-community/gpt2",
+        "hf cache rm <revision_hash>",
+        "hf cache rm model/gpt2 --dry-run",
+        "hf cache rm model/gpt2 --yes",
+    ],
+)
+def rm(
+    targets: Annotated[
+        list[str],
+        typer.Argument(
+            help="One or more repo IDs (e.g. model/bert-base-uncased), repo-level hf:// URIs, or revision hashes to delete.",
+        ),
+    ],
+    cache_dir: Annotated[
+        str | None,
+        typer.Option(
+            help="Cache directory to scan (defaults to Hugging Face cache).",
+        ),
+    ] = None,
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "-y",
+            "--yes",
+            help="Skip confirmation prompt.",
+        ),
+    ] = False,
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            help="Preview deletions without removing anything.",
+        ),
+    ] = False,
+) -> None:
+    """Remove cached repositories or revisions."""
+    try:
+        hf_cache_info = scan_cache_dir(cache_dir)
+    except CacheNotFound as exc:
+        raise CLIError(f"Cache directory not found: {exc.cache_dir}") from exc
+
+    resolution = _resolve_deletion_targets(hf_cache_info, targets)
+
+    if resolution.missing:
+        details = "\n".join(f"  - {entry}" for entry in resolution.missing)
+        out.warning(f"Could not find in cache:\n{details}")
+
+    if len(resolution.revisions) == 0:
+        out.text("Nothing to delete.")
+        raise typer.Exit(code=0)
+
+    strategy = hf_cache_info.delete_revisions(*sorted(resolution.revisions))
+    counts = summarize_deletions(resolution.selected)
+
+    summary_parts: list[str] = []
+    if counts.repo_count:
+        summary_parts.append(f"{counts.repo_count} repo(s)")
+    if counts.partial_revision_count:
+        summary_parts.append(f"{counts.partial_revision_count} revision(s)")
+    if not summary_parts:
+        summary_parts.append(f"{counts.total_revision_count} revision(s)")
+
+    summary_text = " and ".join(summary_parts)
+    out.text(f"About to delete {summary_text} totalling {strategy.expected_freed_size_str}.")
+    print_cache_selected_revisions(resolution.selected)
+
+    if dry_run:
+        out.result(
+            "Dry run: no files were deleted.",
+            dry_run=True,
+            repos=counts.repo_count,
+            revisions=counts.total_revision_count,
+            size=strategy.expected_freed_size_str,
+        )
+        return
+
+    out.confirm("Proceed with deletion?", yes=yes)
+
+    strategy.execute()
+    counts = summarize_deletions(resolution.selected)
+    out.result(
+        f"Deleted {counts.repo_count} repo(s) and {counts.total_revision_count} revision(s);"
+        f" freed {strategy.expected_freed_size_str}.",
+        repos_deleted=counts.repo_count,
+        revisions_deleted=counts.total_revision_count,
+        freed=strategy.expected_freed_size_str,
+    )
+
+
+@cache_cli.command(examples=["hf cache prune", "hf cache prune --dry-run"])
+def prune(
+    cache_dir: Annotated[
+        str | None,
+        typer.Option(
+            help="Cache directory to scan (defaults to Hugging Face cache).",
+        ),
+    ] = None,
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "-y",
+            "--yes",
+            help="Skip confirmation prompt.",
+        ),
+    ] = False,
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            help="Preview deletions without removing anything.",
+        ),
+    ] = False,
+) -> None:
+    """Remove detached revisions from the cache."""
+    try:
+        hf_cache_info = scan_cache_dir(cache_dir)
+    except CacheNotFound as exc:
+        raise CLIError(f"Cache directory not found: {exc.cache_dir}") from exc
+
+    selected: dict[CachedRepoInfo, frozenset[CachedRevisionInfo]] = {}
+    revisions: set[str] = set()
+    for repo in hf_cache_info.repos:
+        detached = frozenset(revision for revision in repo.revisions if len(revision.refs) == 0)
+        if not detached:
+            continue
+        selected[repo] = detached
+        revisions.update(revision.commit_hash for revision in detached)
+
+    if len(revisions) == 0:
+        out.text("No unreferenced revisions found. Nothing to prune.")
+        return
+
+    resolution = _DeletionResolution(
+        revisions=frozenset(revisions),
+        selected=selected,
+        missing=(),
+    )
+    strategy = hf_cache_info.delete_revisions(*sorted(resolution.revisions))
+    counts = summarize_deletions(selected)
+
+    out.text(
+        f"About to delete {counts.total_revision_count} unreferenced revision(s) ({strategy.expected_freed_size_str} total)."
+    )
+    print_cache_selected_revisions(selected)
+
+    if dry_run:
+        out.result(
+            "Dry run: no files were deleted.",
+            dry_run=True,
+            revisions=counts.total_revision_count,
+            size=strategy.expected_freed_size_str,
+        )
+        return
+
+    out.confirm("Proceed?", yes=yes)
+
+    strategy.execute()
+    out.result(
+        f"Deleted {counts.total_revision_count} unreferenced revision(s); freed {strategy.expected_freed_size_str}.",
+        revisions_deleted=counts.total_revision_count,
+        freed=strategy.expected_freed_size_str,
+    )
+
+
+@cache_cli.command(
+    examples=[
+        "hf cache verify gpt2",
+        "hf cache verify gpt2 --revision refs/pr/1",
+        "hf cache verify my-dataset --repo-type dataset",
+    ],
+)
+def verify(
+    repo_id: RepoIdArg,
+    repo_type: RepoTypeOpt = RepoTypeOpt.model,
+    revision: RevisionOpt = None,
+    cache_dir: Annotated[
+        str | None,
+        typer.Option(
+            help="Cache directory to use when verifying files from cache (defaults to Hugging Face cache).",
+        ),
+    ] = None,
+    local_dir: Annotated[
+        str | None,
+        typer.Option(
+            help="If set, verify files under this directory instead of the cache.",
+        ),
+    ] = None,
+    fail_on_missing_files: Annotated[
+        bool,
+        typer.Option(
+            "--fail-on-missing-files",
+            help="Fail if some files exist on the remote but are missing locally.",
+        ),
+    ] = False,
+    fail_on_extra_files: Annotated[
+        bool,
+        typer.Option(
+            "--fail-on-extra-files",
+            help="Fail if some files exist locally but are not present on the remote revision.",
+        ),
+    ] = False,
+    token: TokenOpt = None,
+) -> None:
+    """Verify checksums for a single repo revision from cache or a local directory.
+
+    Examples:
+      - Verify main revision in cache: `hf cache verify gpt2`
+      - Verify specific revision: `hf cache verify gpt2 --revision refs/pr/1`
+      - Verify dataset: `hf cache verify karpathy/fineweb-edu-100b-shuffle --repo-type dataset`
+      - Verify local dir: `hf cache verify deepseek-ai/DeepSeek-OCR --local-dir /path/to/repo`
+    """
+
+    if local_dir is not None and cache_dir is not None:
+        out.error("Cannot pass both --local-dir and --cache-dir. Use one or the other.")
+        raise typer.Exit(code=2)
+
+    api = get_hf_api(token=token)
+
+    result = api.verify_repo_checksums(
+        repo_id=repo_id,
+        repo_type=repo_type.value if hasattr(repo_type, "value") else str(repo_type),
+        revision=revision,
+        local_dir=local_dir,
+        cache_dir=cache_dir,
+        token=token,
+    )
+
+    exit_code = 0
+
+    if result.mismatches:
+        details = "\n".join(
+            f"  - {m['path']}: expected {m['expected']} ({m['algorithm']}), got {m['actual']}"
+            for m in result.mismatches
+        )
+        out.text(f"❌ Checksum verification failed for the following file(s):\n{details}")
+        exit_code = 1
+
+    if result.missing_paths:
+        if fail_on_missing_files:
+            details = "\n".join(f"  - {p}" for p in result.missing_paths)
+            out.text(f"❌ Missing files (present remotely, absent locally):\n{details}")
+            exit_code = 1
+        else:
+            out.warning(
+                f"{len(result.missing_paths)} remote file(s) are missing locally. "
+                "Use --fail-on-missing-files for details."
+            )
+
+    if result.extra_paths:
+        if fail_on_extra_files:
+            details = "\n".join(f"  - {p}" for p in result.extra_paths)
+            out.text(f"❌ Extra files (present locally, absent remotely):\n{details}")
+            exit_code = 1
+        else:
+            out.warning(
+                f"{len(result.extra_paths)} local file(s) do not exist on the remote repo. "
+                "Use --fail-on-extra-files for details."
+            )
+
+    verified_location = result.verified_path
+
+    if exit_code != 0:
+        out.error(
+            f"Verification failed for '{repo_id}' ({repo_type.value}) in {verified_location}.\n  Revision: {result.revision}"
+        )
+        raise typer.Exit(code=exit_code)
+
+    out.result(
+        f"Verified {result.checked_count} file(s) for {repo_type.value} '{repo_id}'. All checksums match.",
+        repo_id=repo_id,
+        repo_type=repo_type.value,
+        checked=result.checked_count,
+        path=str(verified_location),
+    )

venv/Lib/site-packages/huggingface_hub/cli/collections.py

@@ -0,0 +1,316 @@
+# Copyright 2026 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains commands to interact with collections on the Hugging Face Hub.
+
+Usage:
+    # list collections on the Hub
+    hf collections ls
+
+    # list collections for a specific user
+    hf collections ls --owner username
+
+    # get info about a collection
+    hf collections info username/collection-slug
+
+    # create a new collection
+    hf collections create "My Collection" --description "A collection of models"
+
+    # add an item to a collection
+    hf collections add-item username/collection-slug username/model-name model
+
+    # delete a collection
+    hf collections delete username/collection-slug
+"""
+
+import enum
+from typing import Annotated, get_args
+
+import typer
+
+from huggingface_hub.hf_api import CollectionItemType_T, CollectionSort_T
+
+from ._cli_utils import LimitOpt, TokenOpt, get_hf_api, typer_factory
+from ._output import _dataclass_to_dict, out
+
+
+# Build enums dynamically from Literal types to avoid duplication
+_COLLECTION_ITEM_TYPES = get_args(CollectionItemType_T)
+CollectionItemType = enum.Enum("CollectionItemType", {t: t for t in _COLLECTION_ITEM_TYPES}, type=str)  # type: ignore[misc]
+
+_COLLECTION_SORT_OPTIONS = get_args(CollectionSort_T)
+CollectionSort = enum.Enum("CollectionSort", {s: s for s in _COLLECTION_SORT_OPTIONS}, type=str)  # type: ignore[misc]
+
+
+collections_cli = typer_factory(help="Interact with collections on the Hub.")
+
+
+@collections_cli.command(
+    "list | ls",
+    examples=[
+        "hf collections ls",
+        "hf collections ls --owner nvidia",
+        "hf collections ls --item models/teknium/OpenHermes-2.5-Mistral-7B --limit 10",
+    ],
+)
+def collections_ls(
+    owner: Annotated[
+        str | None,
+        typer.Option(help="Filter by owner username or organization."),
+    ] = None,
+    item: Annotated[
+        str | None,
+        typer.Option(
+            help='Filter collections containing a specific item (e.g., "models/gpt2", "datasets/squad", "papers/2311.12983").'
+        ),
+    ] = None,
+    sort: Annotated[
+        CollectionSort | None,
+        typer.Option(help="Sort results by last modified, trending, or upvotes."),
+    ] = None,
+    limit: LimitOpt = 10,
+    token: TokenOpt = None,
+) -> None:
+    """List collections on the Hub."""
+    api = get_hf_api(token=token)
+    sort_key = sort.value if sort else None
+    results = [
+        _dataclass_to_dict(collection)
+        for collection in api.list_collections(
+            owner=owner,
+            item=item,
+            sort=sort_key,  # type: ignore[arg-type]
+            limit=limit,
+        )
+    ]
+    out.table(results)
+
+
+@collections_cli.command(
+    "info",
+    examples=[
+        "hf collections info username/my-collection-slug",
+    ],
+)
+def collections_info(
+    collection_slug: Annotated[str, typer.Argument(help="The collection slug (e.g., 'username/collection-slug').")],
+    token: TokenOpt = None,
+) -> None:
+    """Get info about a collection on the Hub."""
+    api = get_hf_api(token=token)
+    collection = api.get_collection(collection_slug)
+    out.dict(collection)
+
+
+@collections_cli.command(
+    "create",
+    examples=[
+        'hf collections create "My Models"',
+        'hf collections create "My Models" --description "A collection of my favorite models" --private',
+        'hf collections create "Org Collection" --namespace my-org',
+    ],
+)
+def collections_create(
+    title: Annotated[str, typer.Argument(help="The title of the collection.")],
+    namespace: Annotated[
+        str | None,
+        typer.Option(help="The namespace (username or organization). Defaults to the authenticated user."),
+    ] = None,
+    description: Annotated[
+        str | None,
+        typer.Option(help="A description for the collection."),
+    ] = None,
+    private: Annotated[
+        bool,
+        typer.Option(help="Create a private collection."),
+    ] = False,
+    exists_ok: Annotated[
+        bool,
+        typer.Option(help="Do not raise an error if the collection already exists."),
+    ] = False,
+    token: TokenOpt = None,
+) -> None:
+    """Create a new collection on the Hub."""
+    api = get_hf_api(token=token)
+    collection = api.create_collection(
+        title=title,
+        namespace=namespace,
+        description=description,
+        private=private,
+        exists_ok=exists_ok,
+    )
+    out.result("Collection created", slug=collection.slug, url=collection.url)
+
+
+@collections_cli.command(
+    "update",
+    examples=[
+        'hf collections update username/my-collection --title "New Title"',
+        'hf collections update username/my-collection --description "Updated description"',
+        "hf collections update username/my-collection --private --theme green",
+    ],
+)
+def collections_update(
+    collection_slug: Annotated[str, typer.Argument(help="The collection slug (e.g., 'username/collection-slug').")],
+    title: Annotated[
+        str | None,
+        typer.Option(help="The new title for the collection."),
+    ] = None,
+    description: Annotated[
+        str | None,
+        typer.Option(help="The new description for the collection."),
+    ] = None,
+    position: Annotated[
+        int | None,
+        typer.Option(help="The new position of the collection in the owner's list."),
+    ] = None,
+    private: Annotated[
+        bool | None,
+        typer.Option(help="Whether the collection should be private."),
+    ] = None,
+    theme: Annotated[
+        str | None,
+        typer.Option(help="The theme color for the collection (e.g., 'green', 'blue')."),
+    ] = None,
+    token: TokenOpt = None,
+) -> None:
+    """Update a collection's metadata on the Hub."""
+    api = get_hf_api(token=token)
+    collection = api.update_collection_metadata(
+        collection_slug=collection_slug,
+        title=title,
+        description=description,
+        position=position,
+        private=private,
+        theme=theme,
+    )
+    out.result("Collection updated", slug=collection.slug, url=collection.url)
+
+
+@collections_cli.command(
+    "delete",
+    examples=[
+        "hf collections delete username/my-collection",
+        "hf collections delete username/my-collection --missing-ok",
+    ],
+)
+def collections_delete(
+    collection_slug: Annotated[str, typer.Argument(help="The collection slug (e.g., 'username/collection-slug').")],
+    missing_ok: Annotated[
+        bool,
+        typer.Option(help="Do not raise an error if the collection doesn't exist."),
+    ] = False,
+    token: TokenOpt = None,
+) -> None:
+    """Delete a collection from the Hub."""
+    api = get_hf_api(token=token)
+    api.delete_collection(collection_slug, missing_ok=missing_ok)
+    out.result("Collection deleted", slug=collection_slug)
+
+
+@collections_cli.command(
+    "add-item",
+    examples=[
+        "hf collections add-item username/my-collection moonshotai/kimi-k2 model",
+        'hf collections add-item username/my-collection Qwen/DeepPlanning dataset --note "Useful dataset"',
+        "hf collections add-item username/my-collection Tongyi-MAI/Z-Image space",
+    ],
+)
+def collections_add_item(
+    collection_slug: Annotated[str, typer.Argument(help="The collection slug (e.g., 'username/collection-slug').")],
+    item_id: Annotated[
+        str, typer.Argument(help="The ID of the item to add (repo_id for repos, paper ID for papers).")
+    ],
+    item_type: Annotated[
+        CollectionItemType,
+        typer.Argument(help="The type of item (model, dataset, space, paper, collection, or bucket)."),
+    ],
+    note: Annotated[
+        str | None,
+        typer.Option(help="A note to attach to the item (max 500 characters)."),
+    ] = None,
+    exists_ok: Annotated[
+        bool,
+        typer.Option(help="Do not raise an error if the item is already in the collection."),
+    ] = False,
+    token: TokenOpt = None,
+) -> None:
+    """Add an item to a collection."""
+    api = get_hf_api(token=token)
+    collection = api.add_collection_item(
+        collection_slug=collection_slug,
+        item_id=item_id,
+        item_type=item_type.value,  # type: ignore[arg-type]
+        note=note,
+        exists_ok=exists_ok,
+    )
+    out.result("Item added to collection", slug=collection_slug, url=collection.url)
+
+
+@collections_cli.command(
+    "update-item",
+    examples=[
+        'hf collections update-item username/my-collection ITEM_OBJECT_ID --note "Updated note"',
+        "hf collections update-item username/my-collection ITEM_OBJECT_ID --position 0",
+    ],
+)
+def collections_update_item(
+    collection_slug: Annotated[str, typer.Argument(help="The collection slug (e.g., 'username/collection-slug').")],
+    item_object_id: Annotated[
+        str,
+        typer.Argument(help="The ID of the item in the collection (from 'item_object_id' field, not the repo_id)."),
+    ],
+    note: Annotated[
+        str | None,
+        typer.Option(help="A new note for the item (max 500 characters)."),
+    ] = None,
+    position: Annotated[
+        int | None,
+        typer.Option(help="The new position of the item in the collection."),
+    ] = None,
+    token: TokenOpt = None,
+) -> None:
+    """Update an item in a collection."""
+    api = get_hf_api(token=token)
+    api.update_collection_item(
+        collection_slug=collection_slug,
+        item_object_id=item_object_id,
+        note=note,
+        position=position,
+    )
+    out.result("Item updated in collection", slug=collection_slug)
+
+
+@collections_cli.command("delete-item")
+def collections_delete_item(
+    collection_slug: Annotated[str, typer.Argument(help="The collection slug (e.g., 'username/collection-slug').")],
+    item_object_id: Annotated[
+        str,
+        typer.Argument(
+            help="The ID of the item in the collection (retrieved from `item_object_id` field returned by 'hf collections info'."
+        ),
+    ],
+    missing_ok: Annotated[
+        bool,
+        typer.Option(help="Do not raise an error if the item doesn't exist."),
+    ] = False,
+    token: TokenOpt = None,
+) -> None:
+    """Delete an item from a collection."""
+    api = get_hf_api(token=token)
+    api.delete_collection_item(
+        collection_slug=collection_slug,
+        item_object_id=item_object_id,
+        missing_ok=missing_ok,
+    )
+    out.result("Item deleted from collection", slug=collection_slug)

venv/Lib/site-packages/huggingface_hub/cli/datasets.py

@@ -0,0 +1,284 @@
+# Copyright 2026 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains commands to interact with datasets on the Hugging Face Hub.
+
+Usage:
+    # list datasets on the Hub
+    hf datasets ls
+
+    # list datasets with a search query
+    hf datasets ls --search "code"
+
+    # get info about a dataset
+    hf datasets info HuggingFaceFW/fineweb
+"""
+
+import enum
+from typing import Annotated, get_args
+
+import typer
+
+from huggingface_hub._dataset_viewer import execute_raw_sql_query
+from huggingface_hub.errors import CLIError, RepositoryNotFoundError, RevisionNotFoundError
+from huggingface_hub.hf_api import DatasetSort_T, ExpandDatasetProperty_T
+from huggingface_hub.repocard import DatasetCard
+
+from ._cli_utils import (
+    REPO_LIST_DEFAULT_LIMIT,
+    AuthorOpt,
+    FilterOpt,
+    LimitOpt,
+    RevisionOpt,
+    SearchOpt,
+    TokenOpt,
+    get_hf_api,
+    make_expand_properties_parser,
+    typer_factory,
+)
+from ._file_listing import list_repo_files_cmd
+from ._output import _dataclass_to_dict, out
+
+
+_EXPAND_PROPERTIES = sorted(get_args(ExpandDatasetProperty_T))
+_SORT_OPTIONS = get_args(DatasetSort_T)
+DatasetSortEnum = enum.Enum("DatasetSortEnum", {s: s for s in _SORT_OPTIONS}, type=str)  # type: ignore[misc]
+
+
+ExpandOpt = Annotated[
+    str | None,
+    typer.Option(
+        help=f"Comma-separated properties to return. When used, only the listed properties (and id) are returned. Example: '--expand=downloads,likes,tags'. Valid: {', '.join(_EXPAND_PROPERTIES)}.",
+        callback=make_expand_properties_parser(_EXPAND_PROPERTIES),
+    ),
+]
+
+
+datasets_cli = typer_factory(help="Interact with datasets on the Hub.")
+
+
+@datasets_cli.command(
+    "list | ls",
+    examples=[
+        "hf datasets ls",
+        "hf datasets ls --sort downloads --limit 10",
+        'hf datasets ls --search "code"',
+        "hf datasets ls --filter benchmark:official",
+        "hf datasets ls HuggingFaceFW/fineweb",
+        "hf datasets ls HuggingFaceFW/fineweb -R",
+        "hf datasets ls HuggingFaceFW/fineweb --tree -h",
+    ],
+)
+def datasets_ls(
+    repo_id: Annotated[
+        str | None,
+        typer.Argument(help="Dataset ID (e.g. `username/repo-name`) to list files from. If omitted, lists datasets."),
+    ] = None,
+    search: SearchOpt = None,
+    author: AuthorOpt = None,
+    filter: FilterOpt = None,
+    sort: Annotated[
+        DatasetSortEnum | None,
+        typer.Option(help="Sort results."),
+    ] = None,
+    limit: LimitOpt = REPO_LIST_DEFAULT_LIMIT,
+    expand: ExpandOpt = None,
+    human_readable: Annotated[
+        bool,
+        typer.Option("--human-readable", "-h", help="Show sizes in human readable format (only for listing files)."),
+    ] = False,
+    as_tree: Annotated[
+        bool,
+        typer.Option("--tree", help="List files in tree format (only for listing files)."),
+    ] = False,
+    recursive: Annotated[
+        bool,
+        typer.Option("--recursive", "-R", help="List files recursively (only for listing files)."),
+    ] = False,
+    revision: RevisionOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """List datasets on the Hub, or files in a dataset repo.
+
+    When called with no argument, lists datasets on the Hub.
+    When called with a dataset ID, lists files in that dataset repo.
+    """
+    if repo_id is not None:
+        if search is not None:
+            raise typer.BadParameter("Cannot use --search when listing files.")
+        if author is not None:
+            raise typer.BadParameter("Cannot use --author when listing files.")
+        if filter is not None:
+            raise typer.BadParameter("Cannot use --filter when listing files.")
+        if sort is not None:
+            raise typer.BadParameter("Cannot use --sort when listing files.")
+        if limit != REPO_LIST_DEFAULT_LIMIT:
+            raise typer.BadParameter("Cannot use --limit when listing files.")
+        if expand is not None:
+            raise typer.BadParameter("Cannot use --expand when listing files.")
+        return list_repo_files_cmd(
+            repo_id=repo_id,
+            repo_type="dataset",
+            human_readable=human_readable,
+            as_tree=as_tree,
+            recursive=recursive,
+            revision=revision,
+            token=token,
+        )
+
+    if as_tree:
+        raise typer.BadParameter("Cannot use --tree when listing datasets.")
+    if recursive:
+        raise typer.BadParameter("Cannot use --recursive when listing datasets.")
+    if human_readable:
+        raise typer.BadParameter("Cannot use --human-readable when listing datasets.")
+    if revision is not None:
+        raise typer.BadParameter("Cannot use --revision when listing datasets.")
+
+    api = get_hf_api(token=token)
+    sort_key = sort.value if sort else None
+    results = [
+        _dataclass_to_dict(dataset_info)
+        for dataset_info in api.list_datasets(
+            filter=filter,
+            author=author,
+            search=search,
+            sort=sort_key,
+            limit=limit,
+            expand=expand,  # type: ignore
+        )
+    ]
+    out.table(results)
+
+
+@datasets_cli.command(
+    "leaderboard",
+    examples=[
+        "hf datasets leaderboard SWE-bench/SWE-bench_Verified",
+        "hf datasets leaderboard SWE-bench/SWE-bench_Verified --limit 5 --format json",
+        "hf datasets ls --filter benchmark:official  # list available leaderboards",
+    ],
+)
+def datasets_leaderboard(
+    dataset_id: Annotated[str, typer.Argument(help="The benchmark dataset ID (e.g. `SWE-bench/SWE-bench_Verified`).")],
+    limit: LimitOpt = 20,
+    token: TokenOpt = None,
+) -> None:
+    """List model scores from a dataset leaderboard. This command helps find the best models for a task or compare models by benchmark scores. Use 'hf datasets ls --filter benchmark:official' to list available leaderboards."""
+    api = get_hf_api(token=token)
+    leaderboard = api.get_dataset_leaderboard(repo_id=dataset_id)
+    results = [_dataclass_to_dict(entry) for entry in leaderboard[:limit]]
+    out.table(
+        results,
+        headers=["rank", "model_id", "value", "source"],
+        id_key="model_id",
+    )
+    out.hint("Use 'hf datasets ls --filter benchmark:official' to list available leaderboards.")
+    if leaderboard:
+        out.hint(f"Use 'hf models info {leaderboard[0].model_id}' to get details about a model.")
+
+
+@datasets_cli.command(
+    "info",
+    examples=[
+        "hf datasets info HuggingFaceFW/fineweb",
+        "hf datasets info my-dataset --expand downloads,likes,tags",
+    ],
+)
+def datasets_info(
+    dataset_id: Annotated[str, typer.Argument(help="The dataset ID (e.g. `username/repo-name`).")],
+    revision: RevisionOpt = None,
+    expand: ExpandOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Get info about a dataset on the Hub."""
+    api = get_hf_api(token=token)
+    try:
+        info = api.dataset_info(repo_id=dataset_id, revision=revision, expand=expand)  # type: ignore
+    except RepositoryNotFoundError as e:
+        raise CLIError(f"Dataset '{dataset_id}' not found.") from e
+    except RevisionNotFoundError as e:
+        raise CLIError(f"Revision '{revision}' not found on '{dataset_id}'.") from e
+    out.dict(info)
+
+
+@datasets_cli.command(
+    "parquet",
+    examples=[
+        "hf datasets parquet cfahlgren1/hub-stats",
+        "hf datasets parquet cfahlgren1/hub-stats --subset models",
+        "hf datasets parquet cfahlgren1/hub-stats --split train",
+        "hf datasets parquet cfahlgren1/hub-stats --format json",
+    ],
+)
+def datasets_parquet(
+    dataset_id: Annotated[str, typer.Argument(help="The dataset ID (e.g. `username/repo-name`).")],
+    subset: Annotated[str | None, typer.Option("--subset", help="Filter parquet entries by subset/config.")] = None,
+    split: Annotated[str | None, typer.Option(help="Filter parquet entries by split.")] = None,
+    token: TokenOpt = None,
+) -> None:
+    """List parquet file URLs available for a dataset."""
+    api = get_hf_api(token=token)
+    entries = api.list_dataset_parquet_files(repo_id=dataset_id, config=subset)
+    filtered = [entry for entry in entries if split is None or entry.split == split]
+    results = [
+        {"subset": entry.config, "split": entry.split, "url": entry.url, "size": entry.size} for entry in filtered
+    ]
+    out.table(results, headers=["subset", "split", "url", "size"], id_key="url")
+
+
+@datasets_cli.command(
+    "sql",
+    examples=[
+        "hf datasets sql \"SELECT COUNT(*) AS rows FROM read_parquet('https://huggingface.co/api/datasets/cfahlgren1/hub-stats/parquet/models/train/0.parquet')\"",
+        "hf datasets sql \"SELECT * FROM read_parquet('https://huggingface.co/api/datasets/cfahlgren1/hub-stats/parquet/models/train/0.parquet') LIMIT 5\" --format json",
+    ],
+)
+def datasets_sql(
+    sql: Annotated[str, typer.Argument(help="Raw SQL query to execute.")],
+    token: TokenOpt = None,
+) -> None:
+    """Execute a raw SQL query with DuckDB against dataset parquet URLs."""
+    try:
+        result = execute_raw_sql_query(sql_query=sql, token=token)
+    except ImportError as e:
+        raise CLIError(str(e)) from e
+    out.table(result)
+
+
+@datasets_cli.command(
+    "card",
+    examples=[
+        "hf datasets card HuggingFaceFW/fineweb",
+        "hf datasets card HuggingFaceFW/fineweb --metadata",
+        "hf datasets card HuggingFaceFW/fineweb --metadata --format json",
+        "hf datasets card HuggingFaceFW/fineweb --text",
+    ],
+)
+def datasets_card(
+    dataset_id: Annotated[str, typer.Argument(help="The dataset ID (e.g. `username/repo-name`).")],
+    metadata: Annotated[bool, typer.Option("--metadata", help="Output only the metadata from the card.")] = False,
+    text: Annotated[bool, typer.Option("--text", help="Output only the text body (no metadata).")] = False,
+    token: TokenOpt = None,
+) -> None:
+    """Get the dataset card (README) for a dataset on the Hub."""
+    if metadata and text:
+        raise CLIError("--metadata and --text are mutually exclusive.")
+    card = DatasetCard.load(dataset_id, token=token)
+    if metadata:
+        out.dict(card.data.to_dict())
+    elif text:
+        out.text(card.text)
+    else:
+        out.text(card.content)
+        out.hint(f"Use `hf datasets card {dataset_id} --metadata` to extract only the card metadata.")

venv/Lib/site-packages/huggingface_hub/cli/deprecated_cli.py

@@ -0,0 +1,35 @@
+"""Deprecated `huggingface-cli` entry point. Warns and exits."""
+
+import shutil
+import sys
+
+from ._output import out
+
+
+def main() -> None:
+    out.warning("`huggingface-cli` is deprecated and no longer works. Use `hf` instead.\n")
+
+    if shutil.which("hf"):
+        from huggingface_hub.cli._cli_utils import check_cli_update
+
+        check_cli_update("huggingface_hub")
+        out.hint("`hf` is already installed! Use it directly.\n")
+    else:
+        out.hint(
+            "Install `hf`:\n"
+            "  Standalone (recommended): curl -LsSf https://hf.co/cli/install.sh | bash\n"
+            "  Using Homebrew:           brew install hf\n"
+            "  Using pip:                pip install huggingface_hub\n",
+        )
+
+    out.hint(
+        "Examples:\n"
+        "  hf auth login\n"
+        "  hf download unsloth/gemma-4-31B-it-GGUF\n"
+        "  hf upload my-cool-model . .\n"
+        '  hf models ls --search "gemma"\n'
+        "  hf repos ls --format json\n"
+        "  hf jobs run python:3.12 python -c 'print(\"Hello!\")'\n"
+        "  hf --help\n",
+    )
+    sys.exit(1)

venv/Lib/site-packages/huggingface_hub/cli/discussions.py

@@ -0,0 +1,448 @@
+# Copyright 2026 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains commands to interact with discussions and pull requests on the Hugging Face Hub."""
+
+import enum
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from huggingface_hub import constants
+
+from ._cli_utils import (
+    AuthorOpt,
+    LimitOpt,
+    RepoIdArg,
+    RepoType,
+    RepoTypeOpt,
+    TokenOpt,
+    get_hf_api,
+    typer_factory,
+)
+from ._output import _dataclass_to_dict, out
+
+
+class DiscussionStatus(str, enum.Enum):
+    open = "open"
+    closed = "closed"
+    merged = "merged"
+    draft = "draft"
+    all = "all"
+
+
+class DiscussionKind(str, enum.Enum):
+    all = "all"
+    discussion = "discussion"
+    pull_request = "pull_request"
+
+
+# "merged" and "draft" are valid Discussion statuses but the Hub API filter
+# (DiscussionStatusFilter) only accepts "all", "open", "closed". When the user
+# asks for merged/draft we fetch with api_status=None (i.e. all) and filter
+# client-side.
+_CLIENT_SIDE_STATUSES = {"merged", "draft"}
+
+
+DiscussionNumArg = Annotated[
+    int,
+    typer.Argument(
+        help="The discussion or pull request number.",
+        min=1,
+    ),
+]
+
+
+def _read_body(body: str | None, body_file: Path | None) -> str | None:
+    """Resolve body text from --body or --body-file (supports '-' for stdin)."""
+    if body is not None and body_file is not None:
+        raise typer.BadParameter("Cannot use both --body and --body-file.")
+    if body_file is not None:
+        if str(body_file) == "-":
+            return sys.stdin.read()
+        return body_file.read_text(encoding="utf-8")
+    return body
+
+
+discussions_cli = typer_factory(help="Manage discussions and pull requests on the Hub.")
+
+
+@discussions_cli.command(
+    "list | ls",
+    examples=[
+        "hf discussions list username/my-model",
+        "hf discussions list username/my-model --kind pull_request --status merged",
+        "hf discussions list username/my-dataset --type dataset --status closed",
+        "hf discussions list username/my-model --author alice --format json",
+    ],
+)
+def discussion_list(
+    repo_id: RepoIdArg,
+    status: Annotated[
+        DiscussionStatus,
+        typer.Option(
+            "-s",
+            "--status",
+            help="Filter by status (open, closed, merged, draft, all).",
+        ),
+    ] = DiscussionStatus.open,
+    kind: Annotated[
+        DiscussionKind,
+        typer.Option(
+            "-k",
+            "--kind",
+            help="Filter by kind (discussion, pull_request, all).",
+        ),
+    ] = DiscussionKind.all,
+    author: AuthorOpt = None,
+    limit: LimitOpt = 30,
+    repo_type: RepoTypeOpt = RepoType.model,
+    token: TokenOpt = None,
+) -> None:
+    """List discussions and pull requests on a repo."""
+    api = get_hf_api(token=token)
+
+    api_status: constants.DiscussionStatusFilter | None
+    if status == DiscussionStatus.open:
+        api_status = "open"
+    elif status == DiscussionStatus.closed:
+        api_status = "closed"
+    else:
+        api_status = None
+
+    api_discussion_type: constants.DiscussionTypeFilter | None
+    if kind == DiscussionKind.all:
+        api_discussion_type = None
+    else:
+        api_discussion_type = kind.value  # type: ignore[assignment]
+
+    discussions = []
+    for d in api.get_repo_discussions(
+        repo_id=repo_id,
+        author=author,
+        discussion_type=api_discussion_type,
+        discussion_status=api_status,
+        repo_type=repo_type.value,
+    ):
+        if status.value in _CLIENT_SIDE_STATUSES and d.status != status.value:
+            continue
+        discussions.append(d)
+        if len(discussions) >= limit:
+            break
+
+    items = [_dataclass_to_dict(d) for d in discussions]
+    out.table(
+        items,
+        headers=["num", "title", "is_pull_request", "status", "author", "created_at"],
+        id_key="num",
+    )
+
+
+@discussions_cli.command(
+    "info",
+    examples=[
+        "hf discussions info username/my-model 5",
+        "hf discussions info username/my-model 5 --format json",
+    ],
+)
+def discussion_info(
+    repo_id: RepoIdArg,
+    num: DiscussionNumArg,
+    repo_type: RepoTypeOpt = RepoType.model,
+    token: TokenOpt = None,
+) -> None:
+    """Get info about a discussion or pull request."""
+    api = get_hf_api(token=token)
+    details = api.get_discussion_details(
+        repo_id=repo_id,
+        discussion_num=num,
+        repo_type=repo_type.value,
+    )
+    out.dict(details)
+
+
+@discussions_cli.command(
+    "create",
+    examples=[
+        'hf discussions create username/my-model --title "Bug report"',
+        'hf discussions create username/my-model --title "Feature request" --body "Please add X"',
+        'hf discussions create username/my-model --title "Fix typo" --pull-request',
+        'hf discussions create username/my-dataset --type dataset --title "Data quality issue"',
+    ],
+)
+def discussion_create(
+    repo_id: RepoIdArg,
+    title: Annotated[
+        str,
+        typer.Option(
+            "--title",
+            help="The title of the discussion or pull request.",
+        ),
+    ],
+    body: Annotated[
+        str | None,
+        typer.Option(
+            "--body",
+            help="The description (supports Markdown).",
+        ),
+    ] = None,
+    body_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--body-file",
+            help="Read the description from a file. Use '-' for stdin.",
+        ),
+    ] = None,
+    pull_request: Annotated[
+        bool,
+        typer.Option(
+            "--pull-request",
+            "--pr",
+            help="Create a pull request instead of a discussion.",
+        ),
+    ] = False,
+    repo_type: RepoTypeOpt = RepoType.model,
+    token: TokenOpt = None,
+) -> None:
+    """Create a new discussion or pull request on a repo."""
+    description = _read_body(body, body_file)
+    api = get_hf_api(token=token)
+    discussion = api.create_discussion(
+        repo_id=repo_id,
+        title=title,
+        description=description,
+        repo_type=repo_type.value,
+        pull_request=pull_request,
+    )
+    kind = "pull request" if pull_request else "discussion"
+    ref = f"refs/pr/{discussion.num}" if pull_request else None
+    out.result(f"Created {kind} #{discussion.num} on {repo_id}", num=discussion.num, url=discussion.url, ref=ref)
+
+
+@discussions_cli.command(
+    "comment",
+    examples=[
+        'hf discussions comment username/my-model 5 --body "Thanks for reporting!"',
+        'hf discussions comment username/my-model 5 --body "LGTM!"',
+    ],
+)
+def discussion_comment(
+    repo_id: RepoIdArg,
+    num: DiscussionNumArg,
+    body: Annotated[
+        str | None,
+        typer.Option(
+            "--body",
+            help="The comment text (supports Markdown).",
+        ),
+    ] = None,
+    body_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--body-file",
+            help="Read the comment from a file. Use '-' for stdin.",
+        ),
+    ] = None,
+    repo_type: RepoTypeOpt = RepoType.model,
+    token: TokenOpt = None,
+) -> None:
+    """Comment on a discussion or pull request."""
+    comment = _read_body(body, body_file)
+    if comment is None:
+        raise typer.BadParameter("Either --body or --body-file is required.")
+    api = get_hf_api(token=token)
+    api.comment_discussion(
+        repo_id=repo_id,
+        discussion_num=num,
+        comment=comment,
+        repo_type=repo_type.value,
+    )
+    out.result(f"Commented on #{num} in {repo_id}", num=num, repo=repo_id)
+
+
+@discussions_cli.command(
+    "close",
+    examples=[
+        "hf discussions close username/my-model 5",
+        'hf discussions close username/my-model 5 --comment "Closing as resolved."',
+    ],
+)
+def discussion_close(
+    repo_id: RepoIdArg,
+    num: DiscussionNumArg,
+    comment: Annotated[
+        str | None,
+        typer.Option(
+            "--comment",
+            help="An optional comment to post when closing.",
+        ),
+    ] = None,
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "--yes",
+            "-y",
+            help="Skip confirmation prompt.",
+        ),
+    ] = False,
+    repo_type: RepoTypeOpt = RepoType.model,
+    token: TokenOpt = None,
+) -> None:
+    """Close a discussion or pull request."""
+    out.confirm(f"Close #{num} on '{repo_id}'?", yes=yes)
+    api = get_hf_api(token=token)
+    api.change_discussion_status(
+        repo_id=repo_id,
+        discussion_num=num,
+        new_status="closed",
+        comment=comment,
+        repo_type=repo_type.value,
+    )
+    out.result(f"Closed #{num} in {repo_id}", num=num, repo=repo_id)
+
+
+@discussions_cli.command(
+    "reopen",
+    examples=[
+        "hf discussions reopen username/my-model 5",
+        'hf discussions reopen username/my-model 5 --comment "Reopening for further investigation."',
+    ],
+)
+def discussion_reopen(
+    repo_id: RepoIdArg,
+    num: DiscussionNumArg,
+    comment: Annotated[
+        str | None,
+        typer.Option(
+            "--comment",
+            help="An optional comment to post when reopening.",
+        ),
+    ] = None,
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "--yes",
+            "-y",
+            help="Skip confirmation prompt.",
+        ),
+    ] = False,
+    repo_type: RepoTypeOpt = RepoType.model,
+    token: TokenOpt = None,
+) -> None:
+    """Reopen a closed discussion or pull request."""
+    out.confirm(f"Reopen #{num} on '{repo_id}'?", yes=yes)
+    api = get_hf_api(token=token)
+    api.change_discussion_status(
+        repo_id=repo_id,
+        discussion_num=num,
+        new_status="open",
+        comment=comment,
+        repo_type=repo_type.value,
+    )
+    out.result(f"Reopened #{num} in {repo_id}", num=num, repo=repo_id)
+
+
+@discussions_cli.command(
+    "rename",
+    examples=[
+        'hf discussions rename username/my-model 5 "Updated title"',
+    ],
+)
+def discussion_rename(
+    repo_id: RepoIdArg,
+    num: DiscussionNumArg,
+    new_title: Annotated[
+        str,
+        typer.Argument(
+            help="The new title.",
+        ),
+    ],
+    repo_type: RepoTypeOpt = RepoType.model,
+    token: TokenOpt = None,
+) -> None:
+    """Rename a discussion or pull request."""
+    api = get_hf_api(token=token)
+    api.rename_discussion(
+        repo_id=repo_id,
+        discussion_num=num,
+        new_title=new_title,
+        repo_type=repo_type.value,
+    )
+    out.result(f"Renamed #{num} in {repo_id}", num=num, repo=repo_id, title=new_title)
+
+
+@discussions_cli.command(
+    "merge",
+    examples=[
+        "hf discussions merge username/my-model 5",
+        'hf discussions merge username/my-model 5 --comment "Merging, thanks!"',
+    ],
+)
+def discussion_merge(
+    repo_id: RepoIdArg,
+    num: DiscussionNumArg,
+    comment: Annotated[
+        str | None,
+        typer.Option(
+            "--comment",
+            help="An optional comment to post when merging.",
+        ),
+    ] = None,
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "--yes",
+            "-y",
+            help="Skip confirmation prompt.",
+        ),
+    ] = False,
+    repo_type: RepoTypeOpt = RepoType.model,
+    token: TokenOpt = None,
+) -> None:
+    """Merge a pull request."""
+    out.confirm(f"Merge #{num} on '{repo_id}'?", yes=yes)
+    api = get_hf_api(token=token)
+    api.merge_pull_request(
+        repo_id=repo_id,
+        discussion_num=num,
+        comment=comment,
+        repo_type=repo_type.value,
+    )
+    out.result(f"Merged #{num} in {repo_id}", num=num, repo=repo_id)
+
+
+@discussions_cli.command(
+    "diff",
+    examples=[
+        "hf discussions diff username/my-model 5",
+    ],
+)
+def discussion_diff(
+    repo_id: RepoIdArg,
+    num: DiscussionNumArg,
+    repo_type: RepoTypeOpt = RepoType.model,
+    token: TokenOpt = None,
+) -> None:
+    """Show the diff of a pull request."""
+    api = get_hf_api(token=token)
+    details = api.get_discussion_details(
+        repo_id=repo_id,
+        discussion_num=num,
+        repo_type=repo_type.value,
+    )
+    if details.diff:
+        out.text(details.diff)
+    else:
+        out.text("No diff available.")

venv/Lib/site-packages/huggingface_hub/cli/download.py

@@ -0,0 +1,254 @@
+# Copyright 202-present, the HuggingFace Inc. team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains command to download files from the Hub with the CLI.
+
+Usage:
+    hf download --help
+
+    # Download file
+    hf download gpt2 config.json
+
+    # Download entire repo
+    hf download fffiloni/zeroscope --repo-type=space --revision=refs/pr/78
+
+    # Download repo with filters
+    hf download gpt2 --include="*.safetensors"
+
+    # Download with token
+    hf download Wauplin/private-model --token=hf_***
+
+    # Download quietly (no progress bar, no warnings, only the returned path)
+    hf download gpt2 config.json --quiet
+
+    # Download to local dir
+    hf download gpt2 --local-dir=./models/gpt2
+
+    # Download a subfolder
+    hf download HuggingFaceM4/FineVision art/ --repo-type=dataset
+
+    # Download using an hf:// URI (repo type, revision and file path are read from the URI)
+    hf download hf://datasets/HuggingFaceM4/FineVision@refs/pr/1/data/train.parquet
+"""
+
+import warnings
+from typing import Annotated
+
+import typer
+
+from huggingface_hub import constants
+from huggingface_hub._snapshot_download import snapshot_download
+from huggingface_hub.errors import CLIError
+from huggingface_hub.file_download import DryRunFileInfo, hf_hub_download
+from huggingface_hub.utils import _format_size, parse_hf_uri
+
+from ._cli_utils import RepoIdArg, RepoType, RepoTypeOptionalOpt, RevisionOpt, TokenOpt
+from ._output import out
+
+
+DOWNLOAD_EXAMPLES = [
+    "hf download meta-llama/Llama-3.2-1B-Instruct",
+    "hf download meta-llama/Llama-3.2-1B-Instruct config.json tokenizer.json",
+    'hf download meta-llama/Llama-3.2-1B-Instruct --include "*.safetensors" --exclude "*.bin"',
+    "hf download meta-llama/Llama-3.2-1B-Instruct --local-dir ./models/llama",
+    "hf download HuggingFaceM4/FineVision art/ --repo-type dataset",
+    "hf download hf://datasets/HuggingFaceH4/ultrachat_200k",
+]
+
+
+def download(
+    repo_id: RepoIdArg,
+    filenames: Annotated[
+        list[str] | None,
+        typer.Argument(
+            help="Files to download (e.g. `config.json`, `data/metadata.jsonl`).",
+        ),
+    ] = None,
+    repo_type: RepoTypeOptionalOpt = None,
+    revision: RevisionOpt = None,
+    include: Annotated[
+        list[str] | None,
+        typer.Option(
+            help="Glob patterns to include from files to download. eg: *.json",
+        ),
+    ] = None,
+    exclude: Annotated[
+        list[str] | None,
+        typer.Option(
+            help="Glob patterns to exclude from files to download.",
+        ),
+    ] = None,
+    cache_dir: Annotated[
+        str | None,
+        typer.Option(
+            help="Directory where to save files.",
+        ),
+    ] = None,
+    local_dir: Annotated[
+        str | None,
+        typer.Option(
+            help="If set, the downloaded file will be placed under this directory. Check out https://huggingface.co/docs/huggingface_hub/guides/download#download-files-to-a-local-folder for more details.",
+        ),
+    ] = None,
+    force_download: Annotated[
+        bool,
+        typer.Option(
+            help="If True, the files will be downloaded even if they are already cached.",
+        ),
+    ] = False,
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            help="If True, perform a dry run without actually downloading the file.",
+        ),
+    ] = False,
+    token: TokenOpt = None,
+    max_workers: Annotated[
+        int,
+        typer.Option(
+            help="Maximum number of workers to use for downloading files. Default is 8.",
+        ),
+    ] = 8,
+) -> None:
+    """Download files from the Hub."""
+    if local_dir is not None and cache_dir is not None:
+        raise CLIError(
+            "Cannot use both `--local-dir` and `--cache-dir` at the same time. "
+            "Use `--cache-dir` (or set the HF_HOME environment variable) for shared caching, "
+            "or `--local-dir` for a one-off download to a specific directory."
+        )
+
+    # `repo_id` may be a plain repo id or an `hf://` URI (e.g. `hf://datasets/my-org/my-dataset@v1.0/data/`).
+    # When a URI is provided, it is authoritative for the repo type, revision and (optionally) file path,
+    # so explicit `--repo-type` / `--revision` options are forbidden alongside it.
+    # We branch on the `hf://` prefix (the user's *intent*) rather than on whether the string parses as a
+    # valid URI: a malformed URI then surfaces a precise `HfUriError` (formatted globally in `cli/_errors.py`)
+    # instead of silently falling through to the plain-repo-id path and failing later with an opaque error.
+    if repo_id.startswith(constants.HF_PROTOCOL):
+        if repo_type is not None:
+            raise CLIError(f"'--repo-type' cannot be used with an 'hf://' URI ('{repo_id}').")
+        if revision is not None:
+            raise CLIError(f"'--revision' cannot be used with an 'hf://' URI ('{repo_id}').")
+        uri = parse_hf_uri(repo_id)
+        if uri.is_bucket:
+            raise CLIError("Buckets are not supported by `hf download`. Use `hf sync` instead.")
+        # The URI parser strips trailing slashes, but `hf download` uses a trailing '/' to denote a subfolder
+        # download (e.g. `data/` -> `data/**`). Re-append it when the URI explicitly ended with '/' so a folder
+        # URI keeps routing through the subfolder code path below.
+        path_in_repo = uri.path_in_repo
+        if path_in_repo and repo_id.endswith("/"):
+            path_in_repo += "/"
+        repo_id, repo_type_str, revision = uri.id, uri.type, uri.revision
+        if path_in_repo:
+            if filenames:
+                raise CLIError(
+                    f"Cannot combine a file path in the hf:// URI ('{path_in_repo}') with positional filenames {filenames}."
+                )
+            filenames = [path_in_repo]
+    else:
+        repo_type_str = (repo_type or RepoType.model).value
+
+    def run_download() -> str | DryRunFileInfo | list[DryRunFileInfo]:
+        filenames_list = filenames if filenames is not None else []
+
+        # Separate subfolder patterns (ending with '/') from regular filenames
+        # Subfolders like "art/" are converted to include patterns like "art/**"
+        subfolders = [f for f in filenames_list if f.endswith("/")]
+        subfolder_patterns = [f"{f.rstrip('/')}/**" for f in subfolders]
+        regular_filenames = [f for f in filenames_list if not f.endswith("/")]
+
+        # Error if subfolder patterns are combined with --include/--exclude
+        # Guide user to use --include instead of subfolder argument
+        if len(subfolder_patterns) > 0:
+            if include is not None and len(include) > 0:
+                raise CLIError(
+                    f"Cannot combine subfolder argument ('{subfolders[0]}') with `--include`. "
+                    f'Please use `--include "{subfolders[0]}*"` instead.'
+                )
+            if exclude is not None and len(exclude) > 0:
+                raise CLIError(
+                    f"Cannot combine subfolder argument ('{subfolders[0]}') with `--exclude`. "
+                    f'Please use `--include "{subfolders[0]}*"` with `--exclude` instead.'
+                )
+
+        # Warn user if patterns are ignored (only if regular filenames are provided)
+        if len(regular_filenames) > 0:
+            if include is not None and len(include) > 0:
+                warnings.warn("Ignoring `--include` since filenames have been explicitly set.")
+            if exclude is not None and len(exclude) > 0:
+                warnings.warn("Ignoring `--exclude` since filenames have been explicitly set.")
+
+        # Single file to download (not a subfolder): use `hf_hub_download`
+        if len(regular_filenames) == 1 and len(subfolder_patterns) == 0:
+            return hf_hub_download(
+                repo_id=repo_id,
+                repo_type=repo_type_str,
+                revision=revision,
+                filename=regular_filenames[0],
+                cache_dir=cache_dir,
+                force_download=force_download,
+                token=token,
+                local_dir=local_dir,
+                library_name="huggingface-cli",
+                dry_run=dry_run,
+            )
+
+        # Otherwise: use `snapshot_download` to ensure all files comes from same revision
+        if len(regular_filenames) == 0 and len(subfolder_patterns) == 0:
+            # No filenames provided: use include/exclude patterns
+            allow_patterns = include
+            ignore_patterns = exclude
+        else:
+            # Combine regular filenames and subfolder patterns as allow_patterns
+            allow_patterns = regular_filenames + subfolder_patterns
+            ignore_patterns = None
+
+        return snapshot_download(
+            repo_id=repo_id,
+            repo_type=repo_type_str,
+            revision=revision,
+            allow_patterns=allow_patterns,
+            ignore_patterns=ignore_patterns,
+            force_download=force_download,
+            cache_dir=cache_dir,
+            token=token,
+            local_dir=local_dir,
+            library_name="huggingface-cli",
+            max_workers=max_workers,
+            dry_run=dry_run,
+        )
+
+    def _print_result(result: str | DryRunFileInfo | list[DryRunFileInfo]) -> None:
+        if isinstance(result, str):
+            out.result("Downloaded", path=result)
+            return
+
+        # Print dry run info
+        if isinstance(result, DryRunFileInfo):
+            result = [result]
+        will_download = [r for r in result if r.will_download]
+        out.text(
+            f"[dry-run] Will download {len(will_download)} files"
+            f" (out of {len(result)})"
+            f" totalling {_format_size(sum(r.file_size for r in will_download))}."
+        )
+        items = [
+            {
+                "file": info.filename,
+                "size": _format_size(info.file_size) if info.will_download else "-",
+            }
+            for info in sorted(result, key=lambda x: x.filename)
+        ]
+        out.table(items)
+
+    _print_result(run_download())

venv/Lib/site-packages/huggingface_hub/cli/extensions.py

@@ -0,0 +1,627 @@
+# Copyright 2026 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains helper utilities for hf CLI extensions."""
+
+import errno
+import json
+import os
+import re
+import shutil
+import subprocess
+import venv
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Annotated, Literal
+
+import typer
+
+from huggingface_hub.errors import CLIError, CLIExtensionInstallError, ConfirmationError
+from huggingface_hub.utils import get_session, logging
+
+from ._cli_utils import typer_factory
+from ._output import out
+
+
+DEFAULT_EXTENSION_OWNER = "huggingface"
+EXTENSIONS_ROOT = Path("~/.local/share/hf/extensions")
+MANIFEST_FILENAME = "manifest.json"
+EXTENSIONS_HELP = (
+    "Manage hf CLI extensions.\n\n"
+    "Security Warning: extensions are third-party executables or Python packages. "
+    "Install only from sources you trust."
+)
+extensions_cli = typer_factory(help=EXTENSIONS_HELP)
+_EXTENSIONS_DEFAULT_BRANCH = "main"  # Fallback when the GitHub API is unreachable.
+_EXTENSIONS_GITHUB_TOPIC = "hf-extension"
+_EXTENSIONS_DOWNLOAD_TIMEOUT = 10
+_EXTENSIONS_PIP_INSTALL_TIMEOUT = 300
+
+logger = logging.get_logger(__name__)
+
+
+@dataclass
+class ExtensionManifest:
+    owner: str
+    repo: str
+    repo_id: str
+    short_name: str
+    executable_name: str
+    executable_path: str
+    type: Literal["binary", "python"]
+    installed_at: datetime
+    source: str
+    description: str | None = None
+
+    @classmethod
+    def load(cls, path: Path) -> "ExtensionManifest":
+        manifest_path = path / MANIFEST_FILENAME
+        if not manifest_path.is_file():
+            raise CLIError(f"Manifest file not found at {manifest_path}. Your extension may be corrupted.")
+        data = json.loads(manifest_path.read_text())
+        data["installed_at"] = datetime.fromisoformat(data["installed_at"])
+        return ExtensionManifest(**data)
+
+    def save(self, path: Path) -> None:
+        manifest_path = path / MANIFEST_FILENAME
+        manifest_path.parent.mkdir(parents=True, exist_ok=True)
+        data = asdict(self)
+        data["installed_at"] = self.installed_at.isoformat()
+        manifest_path.write_text(json.dumps(data, indent=2, sort_keys=True))
+
+
+@extensions_cli.command(
+    "install",
+    examples=[
+        "hf extensions install hf-claude",
+        "hf extensions install hanouticelina/hf-claude",
+        "hf extensions install alvarobartt/hf-mem",
+    ],
+)
+def extension_install(
+    ctx: typer.Context,
+    repo_id: Annotated[
+        str,
+        typer.Argument(help="GitHub extension repository in `[OWNER/]hf-<name>` format."),
+    ],
+    force: Annotated[bool, typer.Option("--force", help="Overwrite if already installed.")] = False,
+) -> None:
+    """Install an extension from a public GitHub repository.
+
+    Security warning: this installs a third-party executable or Python package.
+    Install only from sources you trust.
+    """
+    owner, repo_name, short_name = _normalize_repo_id(repo_id)
+    root_ctx = ctx.find_root()
+    reserved_commands = set(getattr(root_ctx.command, "commands", {}).keys())
+    if short_name in reserved_commands:
+        raise CLIError(
+            f"Cannot install extension '{short_name}' because it conflicts with an existing `hf {short_name}` command."
+        )
+
+    extension_dir = _get_extension_dir(short_name)
+    extension_exists = extension_dir.exists()
+    if extension_exists and not force:
+        raise CLIError(f"Extension '{short_name}' is already installed. Use --force to overwrite.")
+
+    branch, description = _resolve_github_repo_info(owner=owner, repo_name=repo_name)
+
+    if extension_exists:
+        shutil.rmtree(extension_dir)
+
+    manifest = _install_extension_from_github(
+        owner=owner,
+        repo_name=repo_name,
+        short_name=short_name,
+        extension_dir=extension_dir,
+        branch=branch,
+        description=description,
+    )
+    ext_type = manifest.type.capitalize()
+    out.result(
+        f"{ext_type} extension installed",
+        source=f"{owner}/{repo_name}",
+        command=f"hf {short_name}",
+    )
+    out.hint(f"Run it with: hf {short_name}")
+
+
+@extensions_cli.command(
+    "exec",
+    context_settings={"allow_extra_args": True, "allow_interspersed_args": False, "ignore_unknown_options": True},
+    examples=[
+        "hf extensions exec claude -- --help",
+        "hf extensions exec claude --model zai-org/GLM-5",
+    ],
+)
+def extension_exec(
+    ctx: typer.Context,
+    name: Annotated[
+        str,
+        typer.Argument(help="Extension name (with or without `hf-` prefix)."),
+    ],
+) -> None:
+    """Execute an installed extension."""
+    short_name = _normalize_extension_name(name)
+    executable_path = _resolve_installed_executable_path(short_name)
+
+    if not executable_path.is_file():
+        raise CLIError(f"Extension '{short_name}' is not installed.")
+
+    exit_code = _execute_extension_binary(executable_path=executable_path, args=list(ctx.args))
+    raise typer.Exit(code=exit_code)
+
+
+@extensions_cli.command("list | ls", examples=["hf extensions list"])
+def extension_list() -> None:
+    """List installed extension commands."""
+    rows = [
+        {
+            "command": f"hf {manifest.short_name}",
+            "source": str(manifest.repo_id),
+            "type": str(manifest.type),
+            "installed": manifest.installed_at.strftime("%Y-%m-%d"),
+            "description": manifest.description,
+        }
+        for manifest in _list_installed_extensions()
+    ]
+    out.table(rows, id_key="command")
+
+
+@extensions_cli.command("search", examples=["hf extensions search"])
+def extension_search() -> None:
+    """Search extensions available on GitHub (tagged with 'hf-extension' topic)."""
+    response = get_session().get(
+        "https://api.github.com/search/repositories",
+        params={"q": f"topic:{_EXTENSIONS_GITHUB_TOPIC}", "sort": "stars", "order": "desc", "per_page": 100},
+        follow_redirects=True,
+        timeout=_EXTENSIONS_DOWNLOAD_TIMEOUT,
+    )
+    response.raise_for_status()
+    data = response.json()
+
+    installed = {m.short_name for m in _list_installed_extensions()}
+
+    rows = []
+    for repo in data.get("items", []):
+        repo_name = repo["name"]
+        short_name = repo_name[3:] if repo_name.startswith("hf-") else repo_name
+        rows.append(
+            {
+                "name": short_name,
+                "repo": repo["full_name"],
+                "stars": repo.get("stargazers_count", 0),
+                "description": repo.get("description") or "",
+                "installed": "yes" if short_name in installed else "",
+            }
+        )
+
+    out.table(rows, id_key="repo")
+
+
+@extensions_cli.command("remove | rm", examples=["hf extensions remove claude"])
+def extension_remove(
+    name: Annotated[
+        str,
+        typer.Argument(help="Extension name to remove (with or without `hf-` prefix)."),
+    ],
+) -> None:
+    """Remove an installed extension."""
+    short_name = _normalize_extension_name(name)
+    extension_dir = _get_extension_dir(short_name)
+
+    if not extension_dir.is_dir():
+        raise CLIError(f"Extension '{short_name}' is not installed.")
+
+    shutil.rmtree(extension_dir)
+    out.result("Extension removed", name=short_name)
+
+
+### HELPER FUNCTIONS
+
+
+def _list_installed_extensions() -> list[ExtensionManifest]:
+    """Return manifests for all validly-installed extensions, sorted by directory name."""
+    root_dir = EXTENSIONS_ROOT.expanduser()
+    if not root_dir.is_dir():
+        return []
+    manifests = []
+    for extension_dir in sorted(root_dir.iterdir()):
+        if not extension_dir.is_dir() or not extension_dir.name.startswith("hf-"):
+            continue
+        try:
+            manifests.append(ExtensionManifest.load(extension_dir))
+        except Exception as e:
+            logger.debug(f"Failed to load manifest for extension '{extension_dir.name}': {e}")
+            continue
+    return manifests
+
+
+def list_installed_extensions_for_help() -> list[tuple[str, str]]:
+    entries = []
+    for manifest in _list_installed_extensions():
+        tag = f"[extension {manifest.repo_id}]"
+        help_text = f"{manifest.description} {tag}" if manifest.description is not None else tag
+        entries.append((manifest.short_name, help_text))
+    return entries
+
+
+def dispatch_unknown_top_level_extension(args: list[str], known_commands: set[str]) -> int | None:
+    if not args:
+        return None
+
+    command_name = args[0]
+    if command_name.startswith("-"):
+        return None
+    all_known = {a.strip() for cmd in known_commands for a in cmd.split("|")}
+    if command_name in all_known:
+        return None
+
+    short_name = command_name[3:] if command_name.startswith("hf-") else command_name
+    if not short_name:
+        return None
+
+    executable_path: Path | None = None
+    try:
+        executable_path = _resolve_installed_executable_path(short_name)
+    except Exception:
+        executable_path = _auto_install_official_extension(short_name)
+
+    if executable_path is None or not executable_path.is_file():
+        return None
+
+    return _execute_extension_binary(executable_path=executable_path, args=list(args[1:]))
+
+
+def _auto_install_official_extension(short_name: str) -> Path | None:
+    """Try to auto-install huggingface/hf-<name>. Returns executable path or None."""
+    owner, repo_name = DEFAULT_EXTENSION_OWNER, f"hf-{short_name}"
+    try:
+        extension_dir = _get_extension_dir(short_name)
+    except Exception:
+        return None
+    if extension_dir.exists():
+        return None
+    try:
+        response = get_session().get(
+            f"https://api.github.com/repos/{owner}/{repo_name}",
+            follow_redirects=True,
+            timeout=_EXTENSIONS_DOWNLOAD_TIMEOUT,
+        )
+        if response.status_code == 404:
+            return None
+        response.raise_for_status()
+        branch = response.json()["default_branch"]
+    except Exception:
+        return None
+    try:
+        out.confirm(f"'{short_name}' is an official Hugging Face extension ({owner}/{repo_name}). Install it?")
+    except ConfirmationError:
+        return None
+    try:
+        manifest = _install_extension_from_github(
+            owner=owner, repo_name=repo_name, short_name=short_name, extension_dir=extension_dir, branch=branch
+        )
+        return Path(manifest.executable_path).expanduser()
+    except Exception:
+        shutil.rmtree(extension_dir, ignore_errors=True)
+        return None
+
+
+def _install_extension_from_github(
+    *,
+    owner: str,
+    repo_name: str,
+    short_name: str,
+    extension_dir: Path,
+    branch: str,
+    description: str | None = None,
+) -> ExtensionManifest:
+    """Fetch, install (binary or Python), and save manifest for a GitHub extension."""
+    try:
+        binary = _fetch_remote_binary(owner=owner, repo_name=repo_name, branch=branch, short_name=short_name)
+    except Exception:
+        binary = None
+    if binary is not None:
+        manifest = _install_binary_extension(
+            owner=owner, repo_name=repo_name, short_name=short_name, extension_dir=extension_dir, binary=binary
+        )
+    else:
+        manifest = _install_python_extension(
+            owner=owner, repo_name=repo_name, short_name=short_name, extension_dir=extension_dir, branch=branch
+        )
+    manifest.description = _try_fetch_remote_description(
+        owner=owner, repo_name=repo_name, branch=branch, candidate_description=description
+    )
+    manifest.save(extension_dir)
+    return manifest
+
+
+def _fetch_remote_binary(owner: str, repo_name: str, branch: str, short_name: str) -> bytes:
+    executable_name = _get_executable_name(short_name)
+    raw_url = f"https://raw.githubusercontent.com/{owner}/{repo_name}/refs/heads/{branch}/{executable_name}"
+    response = get_session().get(raw_url, follow_redirects=True, timeout=_EXTENSIONS_DOWNLOAD_TIMEOUT)
+    response.raise_for_status()
+    return response.content
+
+
+def _install_binary_extension(
+    *, owner: str, repo_name: str, short_name: str, extension_dir: Path, binary: bytes
+) -> ExtensionManifest:
+    # Save extension binary
+    executable_name = _get_executable_name(short_name)
+    extension_dir.mkdir(parents=True, exist_ok=False)
+    executable_path = extension_dir / executable_name
+    executable_path.write_bytes(binary)
+
+    # Make it executable
+    if os.name != "nt":
+        os.chmod(executable_path, 0o755)
+
+    # Create manifest
+    return ExtensionManifest(
+        owner=owner,
+        repo=repo_name,
+        repo_id=f"{owner}/{repo_name}",
+        short_name=short_name,
+        executable_name=executable_name,
+        executable_path=str(executable_path),
+        type="binary",
+        installed_at=datetime.now(timezone.utc),
+        source=f"https://github.com/{owner}/{repo_name}",
+    )
+
+
+def _install_python_extension(
+    *, owner: str, repo_name: str, short_name: str, extension_dir: Path, branch: str
+) -> ExtensionManifest:
+    source_url = f"https://github.com/{owner}/{repo_name}/archive/refs/heads/{branch}.zip"
+    venv_dir = extension_dir / "venv"
+    installed = False
+
+    status = out.status()
+    try:
+        status.update(f"Creating virtual environment in {venv_dir}")
+        if extension_dir.exists():
+            shutil.rmtree(extension_dir, ignore_errors=True)
+        extension_dir.mkdir(parents=True, exist_ok=False)
+
+        uv_path = shutil.which("uv")
+        venv_python = _get_venv_python_path(venv_dir)
+        if uv_path:
+            subprocess.run([uv_path, "venv", str(venv_dir)], check=True)
+            status.done(f"Virtual environment created in {venv_dir}")
+
+            status.update(f"Installing package from {source_url}")
+            subprocess.run(
+                [uv_path, "pip", "install", "--python", str(venv_python), source_url],
+                check=True,
+                timeout=_EXTENSIONS_PIP_INSTALL_TIMEOUT,
+            )
+        else:
+            venv.EnvBuilder(with_pip=True).create(str(venv_dir))
+            status.done(f"Virtual environment created in {venv_dir}")
+
+            status.update(f"Installing package from {source_url}")
+            subprocess.run(
+                [
+                    str(venv_python),
+                    "-m",
+                    "pip",
+                    "install",
+                    "--disable-pip-version-check",
+                    "--no-input",
+                    source_url,
+                ],
+                check=True,
+                timeout=_EXTENSIONS_PIP_INSTALL_TIMEOUT,
+            )
+        status.done(f"Package installed from {source_url}")
+
+        executable_name = _get_executable_name(short_name)
+        venv_executable = _get_venv_extension_executable_path(venv_dir, short_name)
+        if not venv_executable.is_file():
+            raise CLIError(
+                f"Installed package from '{owner}/{repo_name}' does not expose the required console script "
+                f"'{executable_name}'."
+            )
+
+        manifest = ExtensionManifest(
+            owner=owner,
+            repo=repo_name,
+            repo_id=f"{owner}/{repo_name}",
+            short_name=short_name,
+            executable_name=executable_name,
+            executable_path=str(venv_executable.resolve()),
+            type="python",
+            installed_at=datetime.now(timezone.utc),
+            source=f"https://github.com/{owner}/{repo_name}",
+        )
+        installed = True
+        return manifest
+    except CLIError:
+        raise
+    except subprocess.TimeoutExpired as e:
+        raise CLIExtensionInstallError(
+            f"Pip install timed out after {_EXTENSIONS_PIP_INSTALL_TIMEOUT}s for '{owner}/{repo_name}'. "
+            "See pip output above for details."
+        ) from e
+    except subprocess.CalledProcessError as e:
+        raise CLIExtensionInstallError(
+            f"Failed to install pip package from '{owner}/{repo_name}' (exit code {e.returncode}). "
+            "See pip output above for details."
+        ) from e
+    except Exception as e:
+        raise CLIExtensionInstallError(f"Failed to set up pip extension from '{owner}/{repo_name}': {e}") from e
+    finally:
+        if not installed:
+            shutil.rmtree(extension_dir, ignore_errors=True)
+
+
+def _try_fetch_remote_description(
+    owner: str, repo_name: str, branch: str, candidate_description: str | None
+) -> str | None:
+    """Try to fetch project description either from:
+    - manifest.json
+    - pyproject.toml
+
+    Only best effort, no error handling.
+    """
+    # from manifest.json
+    try:
+        response = get_session().get(
+            f"https://raw.githubusercontent.com/{owner}/{repo_name}/refs/heads/{branch}/{MANIFEST_FILENAME}",
+            follow_redirects=True,
+        )
+        response.raise_for_status()
+        data = response.json()
+        description = data.get("description")
+        if isinstance(description, str):
+            return description
+    except Exception:
+        pass
+
+    # from pyproject.toml
+    try:
+        response = get_session().get(
+            f"https://raw.githubusercontent.com/{owner}/{repo_name}/refs/heads/{branch}/pyproject.toml",
+            follow_redirects=True,
+        )
+        response.raise_for_status()
+
+        # Weak parser but ok for "best effort"
+        for line in response.text.splitlines():
+            line = line.strip()
+            if line.startswith("description"):
+                _, _, value = line.partition("=")
+                return value.strip().strip("\"'")
+    except Exception:
+        pass
+
+    # fallback to value fetched from GH API directly
+    return candidate_description
+
+
+def _get_extensions_root() -> Path:
+    root_dir = EXTENSIONS_ROOT.expanduser()
+    root_dir.mkdir(parents=True, exist_ok=True)
+    return root_dir
+
+
+def _get_extension_dir(short_name: str) -> Path:
+    safe_name = _validate_extension_short_name(short_name, original_input=short_name)
+    root = _get_extensions_root().resolve()
+    target = (root / f"hf-{safe_name}").resolve()
+    if root not in target.parents:
+        raise CLIError(f"Invalid extension name '{short_name}'.")
+    return target
+
+
+def _resolve_github_repo_info(owner: str, repo_name: str) -> tuple[str, str | None]:
+    try:
+        response = get_session().get(
+            f"https://api.github.com/repos/{owner}/{repo_name}",
+            follow_redirects=True,
+            timeout=_EXTENSIONS_DOWNLOAD_TIMEOUT,
+        )
+        response.raise_for_status()
+        data = response.json()
+        return data["default_branch"], data.get("description")
+    except Exception:
+        return _EXTENSIONS_DEFAULT_BRANCH, None
+
+
+def _get_executable_name(short_name: str) -> str:
+    name = f"hf-{short_name}"
+    if os.name == "nt":
+        name += ".exe"
+    return name
+
+
+def _resolve_installed_executable_path(short_name: str) -> Path:
+    extension_dir = _get_extension_dir(short_name)
+    manifest = ExtensionManifest.load(extension_dir)
+    return Path(manifest.executable_path).expanduser()
+
+
+def _get_venv_python_path(venv_dir: Path) -> Path:
+    if os.name == "nt":
+        return venv_dir / "Scripts" / "python.exe"
+    return venv_dir / "bin" / "python"
+
+
+def _get_venv_extension_executable_path(venv_dir: Path, short_name: str) -> Path:
+    executable_name = _get_executable_name(short_name)
+    if os.name == "nt":
+        return venv_dir / "Scripts" / executable_name
+    return venv_dir / "bin" / executable_name
+
+
+_ALLOWED_EXTENSION_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+
+def _validate_extension_short_name(short_name: str, *, original_input: str) -> str:
+    name = short_name.strip()
+    if not name:
+        raise CLIError("Extension name cannot be empty.")
+    if any(sep in name for sep in ("/", "\\")):
+        raise CLIError(f"Invalid extension name '{original_input}'.")
+    if ".." in name or ":" in name:
+        raise CLIError(f"Invalid extension name '{original_input}'.")
+    if not _ALLOWED_EXTENSION_NAME.fullmatch(name):
+        raise CLIError(
+            f"Invalid extension name '{original_input}'. Allowed characters: letters, digits, '.', '_' and '-'."
+        )
+    return name
+
+
+def _normalize_repo_id(repo_id: str) -> tuple[str, str, str]:
+    if "://" in repo_id:
+        raise CLIError("Only GitHub repositories in `[OWNER/]hf-<name>` format are supported.")
+
+    parts = repo_id.split("/")
+    if len(parts) == 1:
+        owner = DEFAULT_EXTENSION_OWNER
+        repo_name = parts[0]
+    elif len(parts) == 2 and all(parts):
+        owner, repo_name = parts
+    else:
+        raise CLIError(f"Expected `[OWNER/]REPO` format, got '{repo_id}'.")
+
+    if not repo_name.startswith("hf-"):
+        raise CLIError(f"Extension repository name must start with 'hf-', got '{repo_name}'.")
+
+    short_name = repo_name[3:]
+    if not short_name:
+        raise CLIError("Invalid extension repository name 'hf-'.")
+    _validate_extension_short_name(short_name, original_input=repo_id)
+
+    return owner, repo_name, short_name
+
+
+def _normalize_extension_name(name: str) -> str:
+    candidate = name.strip()
+    if not candidate:
+        raise CLIError("Extension name cannot be empty.")
+    normalized = candidate[3:] if candidate.startswith("hf-") else candidate
+    return _validate_extension_short_name(normalized, original_input=name)
+
+
+def _execute_extension_binary(executable_path: Path, args: list[str]) -> int:
+    try:
+        return subprocess.call([str(executable_path)] + args)
+    except OSError as e:
+        if os.name == "nt" or e.errno != errno.ENOEXEC:
+            raise
+        return subprocess.call(["sh", str(executable_path)] + args)

venv/Lib/site-packages/huggingface_hub/cli/hf.py

@@ -0,0 +1,130 @@
+# Copyright 2020 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import sys
+import traceback
+from typing import Annotated
+
+import typer
+
+from huggingface_hub import __version__, constants
+from huggingface_hub.cli._cli_utils import check_cli_update, fallback_typer_group_factory, typer_factory
+from huggingface_hub.cli._cp import CP_EXAMPLES, make_cp
+from huggingface_hub.cli._errors import format_known_exception
+from huggingface_hub.cli.auth import auth_cli
+from huggingface_hub.cli.buckets import buckets_cli, sync
+from huggingface_hub.cli.cache import cache_cli
+from huggingface_hub.cli.collections import collections_cli
+from huggingface_hub.cli.datasets import datasets_cli
+from huggingface_hub.cli.discussions import discussions_cli
+from huggingface_hub.cli.download import DOWNLOAD_EXAMPLES, download
+from huggingface_hub.cli.extensions import (
+    dispatch_unknown_top_level_extension,
+    extensions_cli,
+    list_installed_extensions_for_help,
+)
+from huggingface_hub.cli.inference_endpoints import ie_cli
+from huggingface_hub.cli.jobs import jobs_cli
+from huggingface_hub.cli.lfs import lfs_enable_largefiles, lfs_multipart_upload
+from huggingface_hub.cli.models import models_cli
+from huggingface_hub.cli.papers import papers_cli
+from huggingface_hub.cli.repo_files import repo_files_cli
+from huggingface_hub.cli.repos import repos_cli
+from huggingface_hub.cli.skills import skills_cli
+from huggingface_hub.cli.spaces import spaces_cli
+from huggingface_hub.cli.system import env, update, version
+from huggingface_hub.cli.upload import UPLOAD_EXAMPLES, upload
+from huggingface_hub.cli.upload_large_folder import UPLOAD_LARGE_FOLDER_EXAMPLES, upload_large_folder
+from huggingface_hub.cli.webhooks import webhooks_cli
+from huggingface_hub.utils import ANSI, logging
+
+
+app = typer_factory(
+    help="Hugging Face Hub CLI",
+    cls=fallback_typer_group_factory(
+        dispatch_unknown_top_level_extension,
+        extra_commands_provider=list_installed_extensions_for_help,
+    ),
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        print(__version__)
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def app_callback(
+    version: Annotated[
+        bool | None, typer.Option("-v", "--version", callback=_version_callback, is_eager=True, hidden=True)
+    ] = None,
+) -> None:
+    pass
+
+
+# top level single commands (defined in their respective files)
+app.command(examples=CP_EXAMPLES)(make_cp())
+app.command()(sync)
+app.command(examples=DOWNLOAD_EXAMPLES)(download)
+app.command(examples=UPLOAD_EXAMPLES)(upload)
+app.command(examples=UPLOAD_LARGE_FOLDER_EXAMPLES)(upload_large_folder)
+
+app.command(topic="help")(env)
+app.command(topic="help")(update)
+app.command(topic="help")(version)
+
+app.command(hidden=True)(lfs_enable_largefiles)
+app.command(hidden=True)(lfs_multipart_upload)
+
+# command groups
+app.add_typer(auth_cli, name="auth")
+app.add_typer(buckets_cli, name="buckets")
+app.add_typer(cache_cli, name="cache")
+app.add_typer(collections_cli, name="collections")
+app.add_typer(datasets_cli, name="datasets")
+app.add_typer(discussions_cli, name="discussions")
+app.add_typer(jobs_cli, name="jobs")
+app.add_typer(models_cli, name="models")
+app.add_typer(papers_cli, name="papers")
+app.add_typer(repos_cli, name="repos | repo")
+app.add_typer(repo_files_cli, name="repo-files", hidden=True)
+app.add_typer(skills_cli, name="skills")
+app.add_typer(spaces_cli, name="spaces")
+app.add_typer(webhooks_cli, name="webhooks")
+app.add_typer(ie_cli, name="endpoints")
+app.add_typer(extensions_cli, name="extensions | ext")
+
+
+def main():
+    if not constants.HF_DEBUG:
+        logging.set_verbosity_info()
+    check_cli_update("huggingface_hub")
+
+    try:
+        app()
+    except Exception as e:
+        message = format_known_exception(e)
+        if message:
+            print(f"Error: {message}", file=sys.stderr)
+            if constants.HF_DEBUG:
+                traceback.print_exc()
+            else:
+                print(ANSI.gray("Set HF_DEBUG=1 as environment variable for full traceback."))
+            sys.exit(1)
+        raise
+
+
+if __name__ == "__main__":
+    main()

venv/Lib/site-packages/huggingface_hub/cli/inference_endpoints.py

@@ -0,0 +1,438 @@
+"""CLI commands for Hugging Face Inference Endpoints."""
+
+from typing import Annotated
+
+import typer
+
+from huggingface_hub._inference_endpoints import InferenceEndpointScalingMetric
+from huggingface_hub.errors import HfHubHTTPError
+
+from ._cli_utils import TokenOpt, get_hf_api, typer_factory
+from ._output import out
+
+
+ie_cli = typer_factory(help="Manage Hugging Face Inference Endpoints.")
+
+catalog_app = typer_factory(help="Interact with the Inference Endpoints catalog.")
+
+
+NameArg = Annotated[
+    str,
+    typer.Argument(help="Endpoint name."),
+]
+NameOpt = Annotated[
+    str | None,
+    typer.Option(help="Endpoint name."),
+]
+
+NamespaceOpt = Annotated[
+    str | None,
+    typer.Option(
+        help="The namespace associated with the Inference Endpoint. Defaults to the current user's namespace.",
+    ),
+]
+
+
+@ie_cli.command("list | ls", examples=["hf endpoints ls", "hf endpoints ls --namespace my-org"])
+def ls(
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Lists all Inference Endpoints for the given namespace."""
+    api = get_hf_api(token=token)
+    try:
+        endpoints = api.list_inference_endpoints(namespace=namespace, token=token)
+    except HfHubHTTPError as error:
+        out.error(f"Listing failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    results = []
+    for endpoint in endpoints:
+        raw = endpoint.raw
+        status = raw.get("status", {})
+        model = raw.get("model", {})
+        compute = raw.get("compute", {})
+        provider = raw.get("provider", {})
+        results.append(
+            {
+                "name": raw.get("name", ""),
+                "model": model.get("repository", "") if isinstance(model, dict) else "",
+                "status": status.get("state", "") if isinstance(status, dict) else "",
+                "task": model.get("task", "") if isinstance(model, dict) else "",
+                "framework": model.get("framework", "") if isinstance(model, dict) else "",
+                "instance": compute.get("instanceType", "") if isinstance(compute, dict) else "",
+                "vendor": provider.get("vendor", "") if isinstance(provider, dict) else "",
+                "region": provider.get("region", "") if isinstance(provider, dict) else "",
+            }
+        )
+    out.table(results, id_key="name")
+
+
+@ie_cli.command(name="deploy", examples=["hf endpoints deploy my-endpoint --repo gpt2 --framework pytorch ..."])
+def deploy(
+    name: NameArg,
+    repo: Annotated[
+        str,
+        typer.Option(
+            help="The name of the model repository associated with the Inference Endpoint (e.g. 'openai/gpt-oss-120b').",
+        ),
+    ],
+    framework: Annotated[
+        str,
+        typer.Option(
+            help="The machine learning framework used for the model (e.g. 'vllm').",
+        ),
+    ],
+    accelerator: Annotated[
+        str,
+        typer.Option(
+            help="The hardware accelerator to be used for inference (e.g. 'cpu').",
+        ),
+    ],
+    instance_size: Annotated[
+        str,
+        typer.Option(
+            help="The size or type of the instance to be used for hosting the model (e.g. 'x4').",
+        ),
+    ],
+    instance_type: Annotated[
+        str,
+        typer.Option(
+            help="The cloud instance type where the Inference Endpoint will be deployed (e.g. 'intel-icl').",
+        ),
+    ],
+    region: Annotated[
+        str,
+        typer.Option(
+            help="The cloud region in which the Inference Endpoint will be created (e.g. 'us-east-1').",
+        ),
+    ],
+    vendor: Annotated[
+        str,
+        typer.Option(
+            help="The cloud provider or vendor where the Inference Endpoint will be hosted (e.g. 'aws').",
+        ),
+    ],
+    *,
+    namespace: NamespaceOpt = None,
+    task: Annotated[
+        str | None,
+        typer.Option(
+            help="The task on which to deploy the model (e.g. 'text-classification').",
+        ),
+    ] = None,
+    token: TokenOpt = None,
+    min_replica: Annotated[
+        int,
+        typer.Option(
+            help="The minimum number of replicas (instances) to keep running for the Inference Endpoint.",
+        ),
+    ] = 1,
+    max_replica: Annotated[
+        int,
+        typer.Option(
+            help="The maximum number of replicas (instances) to scale to for the Inference Endpoint.",
+        ),
+    ] = 1,
+    scale_to_zero_timeout: Annotated[
+        int | None,
+        typer.Option(
+            help="The duration in minutes before an inactive endpoint is scaled to zero.",
+        ),
+    ] = None,
+    scaling_metric: Annotated[
+        InferenceEndpointScalingMetric | None,
+        typer.Option(
+            help="The metric reference for scaling.",
+        ),
+    ] = None,
+    scaling_threshold: Annotated[
+        float | None,
+        typer.Option(
+            help="The scaling metric threshold used to trigger a scale up. Ignored when scaling metric is not provided.",
+        ),
+    ] = None,
+) -> None:
+    """Deploy an Inference Endpoint from a Hub repository."""
+    api = get_hf_api(token=token)
+    endpoint = api.create_inference_endpoint(
+        name=name,
+        repository=repo,
+        framework=framework,
+        accelerator=accelerator,
+        instance_size=instance_size,
+        instance_type=instance_type,
+        region=region,
+        vendor=vendor,
+        namespace=namespace,
+        task=task,
+        token=token,
+        min_replica=min_replica,
+        max_replica=max_replica,
+        scaling_metric=scaling_metric,
+        scaling_threshold=scaling_threshold,
+        scale_to_zero_timeout=scale_to_zero_timeout,
+    )
+    out.dict(endpoint.raw)
+
+
+@catalog_app.command(name="deploy", examples=["hf endpoints catalog deploy --repo meta-llama/Llama-3.2-1B-Instruct"])
+def deploy_from_catalog(
+    repo: Annotated[
+        str,
+        typer.Option(
+            help="The name of the model repository associated with the Inference Endpoint (e.g. 'openai/gpt-oss-120b').",
+        ),
+    ],
+    name: NameOpt = None,
+    accelerator: Annotated[
+        str | None,
+        typer.Option(
+            help="The hardware accelerator to be used for inference (e.g. 'cpu', 'gpu', 'neuron').",
+        ),
+    ] = None,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Deploy an Inference Endpoint from the Model Catalog."""
+    api = get_hf_api(token=token)
+    try:
+        endpoint = api.create_inference_endpoint_from_catalog(
+            repo_id=repo,
+            name=name,
+            accelerator=accelerator,
+            namespace=namespace,
+            token=token,
+        )
+    except HfHubHTTPError as error:
+        out.error(f"Deployment failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    out.dict(endpoint.raw)
+
+
+def list_catalog(
+    token: TokenOpt = None,
+) -> None:
+    """List available Catalog models."""
+    api = get_hf_api(token=token)
+    try:
+        models = api.list_inference_catalog(token=token)
+    except HfHubHTTPError as error:
+        out.error(f"Catalog fetch failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    out.dict({"models": models})
+
+
+catalog_app.command(name="list | ls", examples=["hf endpoints catalog ls"])(list_catalog)
+ie_cli.command(name="list-catalog", hidden=True)(list_catalog)
+
+
+ie_cli.add_typer(catalog_app, name="catalog")
+
+
+@ie_cli.command(examples=["hf endpoints describe my-endpoint"])
+def describe(
+    name: NameArg,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Get information about an existing endpoint."""
+    api = get_hf_api(token=token)
+    try:
+        endpoint = api.get_inference_endpoint(name=name, namespace=namespace, token=token)
+    except HfHubHTTPError as error:
+        out.error(f"Fetch failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    out.dict(endpoint.raw)
+
+
+@ie_cli.command(examples=["hf endpoints update my-endpoint --min-replica 2"])
+def update(
+    name: NameArg,
+    namespace: NamespaceOpt = None,
+    repo: Annotated[
+        str | None,
+        typer.Option(
+            help="The name of the model repository associated with the Inference Endpoint (e.g. 'openai/gpt-oss-120b').",
+        ),
+    ] = None,
+    accelerator: Annotated[
+        str | None,
+        typer.Option(
+            help="The hardware accelerator to be used for inference (e.g. 'cpu').",
+        ),
+    ] = None,
+    instance_size: Annotated[
+        str | None,
+        typer.Option(
+            help="The size or type of the instance to be used for hosting the model (e.g. 'x4').",
+        ),
+    ] = None,
+    instance_type: Annotated[
+        str | None,
+        typer.Option(
+            help="The cloud instance type where the Inference Endpoint will be deployed (e.g. 'intel-icl').",
+        ),
+    ] = None,
+    framework: Annotated[
+        str | None,
+        typer.Option(
+            help="The machine learning framework used for the model (e.g. 'custom').",
+        ),
+    ] = None,
+    revision: Annotated[
+        str | None,
+        typer.Option(
+            help="The specific model revision to deploy on the Inference Endpoint (e.g. '6c0e6080953db56375760c0471a8c5f2929baf11').",
+        ),
+    ] = None,
+    task: Annotated[
+        str | None,
+        typer.Option(
+            help="The task on which to deploy the model (e.g. 'text-classification').",
+        ),
+    ] = None,
+    min_replica: Annotated[
+        int | None,
+        typer.Option(
+            help="The minimum number of replicas (instances) to keep running for the Inference Endpoint.",
+        ),
+    ] = None,
+    max_replica: Annotated[
+        int | None,
+        typer.Option(
+            help="The maximum number of replicas (instances) to scale to for the Inference Endpoint.",
+        ),
+    ] = None,
+    scale_to_zero_timeout: Annotated[
+        int | None,
+        typer.Option(
+            help="The duration in minutes before an inactive endpoint is scaled to zero.",
+        ),
+    ] = None,
+    scaling_metric: Annotated[
+        InferenceEndpointScalingMetric | None,
+        typer.Option(
+            help="The metric reference for scaling.",
+        ),
+    ] = None,
+    scaling_threshold: Annotated[
+        float | None,
+        typer.Option(
+            help="The scaling metric threshold used to trigger a scale up. Ignored when scaling metric is not provided.",
+        ),
+    ] = None,
+    token: TokenOpt = None,
+) -> None:
+    """Update an existing endpoint."""
+    api = get_hf_api(token=token)
+    try:
+        endpoint = api.update_inference_endpoint(
+            name=name,
+            namespace=namespace,
+            repository=repo,
+            framework=framework,
+            revision=revision,
+            task=task,
+            accelerator=accelerator,
+            instance_size=instance_size,
+            instance_type=instance_type,
+            min_replica=min_replica,
+            max_replica=max_replica,
+            scale_to_zero_timeout=scale_to_zero_timeout,
+            scaling_metric=scaling_metric,
+            scaling_threshold=scaling_threshold,
+            token=token,
+        )
+    except HfHubHTTPError as error:
+        out.error(f"Update failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+    out.dict(endpoint.raw)
+
+
+@ie_cli.command(examples=["hf endpoints delete my-endpoint"])
+def delete(
+    name: NameArg,
+    namespace: NamespaceOpt = None,
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", help="Skip confirmation prompts."),
+    ] = False,
+    token: TokenOpt = None,
+) -> None:
+    """Delete an Inference Endpoint permanently."""
+    out.confirm(f"Delete endpoint '{name}'?", yes=yes)
+
+    api = get_hf_api(token=token)
+    try:
+        api.delete_inference_endpoint(name=name, namespace=namespace, token=token)
+    except HfHubHTTPError as error:
+        out.error(f"Delete failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    out.result(f"Deleted '{name}'.", name=name)
+
+
+@ie_cli.command(examples=["hf endpoints pause my-endpoint"])
+def pause(
+    name: NameArg,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Pause an Inference Endpoint."""
+    api = get_hf_api(token=token)
+    try:
+        endpoint = api.pause_inference_endpoint(name=name, namespace=namespace, token=token)
+    except HfHubHTTPError as error:
+        out.error(f"Pause failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    out.dict(endpoint.raw)
+
+
+@ie_cli.command(examples=["hf endpoints resume my-endpoint"])
+def resume(
+    name: NameArg,
+    namespace: NamespaceOpt = None,
+    fail_if_already_running: Annotated[
+        bool,
+        typer.Option(
+            "--fail-if-already-running",
+            help="If `True`, the method will raise an error if the Inference Endpoint is already running.",
+        ),
+    ] = False,
+    token: TokenOpt = None,
+) -> None:
+    """Resume an Inference Endpoint."""
+    api = get_hf_api(token=token)
+    try:
+        endpoint = api.resume_inference_endpoint(
+            name=name,
+            namespace=namespace,
+            token=token,
+            running_ok=not fail_if_already_running,
+        )
+    except HfHubHTTPError as error:
+        out.error(f"Resume failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+    out.dict(endpoint.raw)
+
+
+@ie_cli.command(examples=["hf endpoints scale-to-zero my-endpoint"])
+def scale_to_zero(
+    name: NameArg,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Scale an Inference Endpoint to zero."""
+    api = get_hf_api(token=token)
+    try:
+        endpoint = api.scale_to_zero_inference_endpoint(name=name, namespace=namespace, token=token)
+    except HfHubHTTPError as error:
+        out.error(f"Scale To Zero failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    out.dict(endpoint.raw)

venv/Lib/site-packages/huggingface_hub/cli/jobs.py

@@ -0,0 +1,1172 @@
+# Copyright 2025 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains commands to interact with jobs on the Hugging Face Hub.
+
+Usage:
+    # run a job
+    hf jobs run <image> <command>
+
+    # List running or completed jobs
+    hf jobs ps [-a] [-f key=value]
+
+    # Print logs from a job (non-blocking)
+    hf jobs logs <job-id>
+
+    # Stream logs from a job (blocking, like `docker logs -f`)
+    hf jobs logs -f <job-id>
+
+    # Stream resources usage stats and metrics from a job
+    hf jobs stats <job-id>
+
+    # Inspect detailed information about a job
+    hf jobs inspect <job-id>
+
+    # Cancel a running job
+    hf jobs cancel <job-id>
+
+    # List available hardware options
+    hf jobs hardware
+
+    # Run a UV script
+    hf jobs uv run <script>
+
+    # Schedule a job
+    hf jobs scheduled run <schedule> <image> <command>
+
+    # List scheduled jobs
+    hf jobs scheduled ps [-a] [-f key=value]
+
+    # Inspect a scheduled job
+    hf jobs scheduled inspect <scheduled_job_id>
+
+    # Suspend a scheduled job
+    hf jobs scheduled suspend <scheduled_job_id>
+
+    # Resume a scheduled job
+    hf jobs scheduled resume <scheduled_job_id>
+
+    # Delete a scheduled job
+    hf jobs scheduled delete <scheduled_job_id>
+
+"""
+
+import multiprocessing
+import multiprocessing.pool
+import shutil
+import time
+from collections.abc import Callable, Iterable
+from fnmatch import fnmatch
+from queue import Empty, Queue
+from typing import Annotated, Any, TypeVar
+
+import typer
+
+from huggingface_hub import JobHardware
+from huggingface_hub.errors import CLIError, HfHubHTTPError
+from huggingface_hub.utils import logging
+from huggingface_hub.utils._cache_manager import _format_size
+from huggingface_hub.utils._parsing import format_duration
+
+from ._cli_utils import (
+    EnvFileOpt,
+    EnvOpt,
+    SecretsFileOpt,
+    SecretsOpt,
+    SoftChoice,
+    TokenOpt,
+    VolumesOpt,
+    get_hf_api,
+    parse_env_map,
+    parse_volumes,
+    typer_factory,
+)
+from ._output import _dataclass_to_dict, out
+
+
+logger = logging.get_logger(__name__)
+
+
+def _parse_namespace_from_job_id(job_id: str, namespace: str | None) -> tuple[str, str | None]:
+    """Extract namespace from job_id if provided in 'namespace/job_id' format.
+
+    Allows users to pass job IDs copied from the Hub UI (e.g. 'username/job_id')
+    instead of only bare job IDs. If the namespace is also provided explicitly via
+    --namespace and conflicts, a CLIError is raised.
+    """
+    if not job_id:
+        raise CLIError("Job ID cannot be empty.")
+
+    if job_id.count("/") > 1:
+        raise CLIError(f"Job ID must be in the form 'job_id' or 'namespace/job_id': '{job_id}'.")
+
+    if "/" not in job_id:
+        return job_id, namespace
+
+    extracted_namespace, parsed_job_id = job_id.split("/", 1)
+    if not extracted_namespace or not parsed_job_id:
+        raise CLIError(f"Job ID must be in the form 'job_id' or 'namespace/job_id': '{job_id}'.")
+
+    if namespace is not None and namespace != extracted_namespace:
+        raise CLIError(
+            f"Conflicting namespace: got --namespace='{namespace}' but job ID implies namespace='{extracted_namespace}'"
+        )
+
+    return parsed_job_id, extracted_namespace
+
+
+STATS_UPDATE_MIN_INTERVAL = 0.1  # we set a limit here since there is one update per second per job
+
+# Common job-related options
+ImageArg = Annotated[
+    str,
+    typer.Argument(
+        help="The Docker image to use.",
+    ),
+]
+
+ImageOpt = Annotated[
+    str | None,
+    typer.Option(
+        help="Use a custom Docker image with `uv` installed.",
+    ),
+]
+
+FlavorOpt = Annotated[
+    str | None,
+    typer.Option(
+        help="Flavor for the hardware. Run 'hf jobs hardware' to list available flavors. Defaults to `cpu-basic`.",
+        click_type=SoftChoice(JobHardware),
+    ),
+]
+
+LabelsOpt = Annotated[
+    list[str] | None,
+    typer.Option(
+        "-l",
+        "--label",
+        help="Set labels. E.g. --label KEY=VALUE or --label LABEL",
+    ),
+]
+
+TimeoutOpt = Annotated[
+    str | None,
+    typer.Option(
+        help="Max duration: int/float with s (seconds, default), m (minutes), h (hours) or d (days).",
+    ),
+]
+
+DetachOpt = Annotated[
+    bool,
+    typer.Option(
+        "-d",
+        "--detach",
+        help="Run the Job in the background and print the Job ID.",
+    ),
+]
+
+NamespaceOpt = Annotated[
+    str | None,
+    typer.Option(
+        help="The namespace where the job will be running. Defaults to the current user's namespace.",
+    ),
+]
+
+ExposeOpt = Annotated[
+    list[int] | None,
+    typer.Option(
+        "--expose",
+        help="Expose a container port through the jobs proxy. Repeat the flag for multiple ports (e.g. `--expose 8000 --expose 8001`). Each exposed port is reachable on the public jobs domain; access requires an HF token with read access to the job's namespace.",
+    ),
+]
+
+WithOpt = Annotated[
+    list[str] | None,
+    typer.Option(
+        "--with",
+        help="Run with the given packages installed",
+    ),
+]
+
+PythonOpt = Annotated[
+    str | None,
+    typer.Option(
+        "-p",
+        "--python",
+        help="The Python interpreter to use for the run environment",
+    ),
+]
+
+SuspendOpt = Annotated[
+    bool | None,
+    typer.Option(
+        help="Suspend (pause) the scheduled Job",
+    ),
+]
+
+ConcurrencyOpt = Annotated[
+    bool | None,
+    typer.Option(
+        help="Allow multiple instances of this Job to run concurrently",
+    ),
+]
+
+ScheduleArg = Annotated[
+    str,
+    typer.Argument(
+        help="One of annually, yearly, monthly, weekly, daily, hourly, or a CRON schedule expression.",
+    ),
+]
+
+ScriptArg = Annotated[
+    str,
+    typer.Argument(
+        help="UV script to run (local file or URL)",
+    ),
+]
+
+ScriptArgsArg = Annotated[
+    list[str] | None,
+    typer.Argument(
+        help="Arguments for the script",
+    ),
+]
+
+
+CommandArg = Annotated[
+    list[str],
+    typer.Argument(
+        help="The command to run.",
+    ),
+]
+
+JobIdArg = Annotated[
+    str,
+    typer.Argument(
+        help="Job ID (or 'namespace/job_id')",
+    ),
+]
+
+JobIdsArg = Annotated[
+    list[str] | None,
+    typer.Argument(
+        help="Job IDs (or 'namespace/job_id')",
+    ),
+]
+
+ScheduledJobIdArg = Annotated[
+    str,
+    typer.Argument(
+        help="Scheduled Job ID (or 'namespace/scheduled_job_id')",
+    ),
+]
+
+
+jobs_cli = typer_factory(help="Run and manage Jobs on the Hub.")
+
+
+@jobs_cli.command(
+    "run",
+    context_settings={"ignore_unknown_options": True},
+    examples=[
+        "hf jobs run python:3.12 python -c 'print(\"Hello!\")'",
+        "hf jobs run --detach python:3.12 python script.py",
+        "hf jobs run -e FOO=foo python:3.12 python script.py",
+        "hf jobs run --secrets HF_TOKEN python:3.12 python script.py",
+        "hf jobs run -v hf://org/my-model:/data -v hf://buckets/org/b:/mnt python:3.12 python script.py",
+    ],
+)
+def jobs_run(
+    image: ImageArg,
+    command: CommandArg,
+    env: EnvOpt = None,
+    secrets: SecretsOpt = None,
+    label: LabelsOpt = None,
+    volume: VolumesOpt = None,
+    env_file: EnvFileOpt = None,
+    secrets_file: SecretsFileOpt = None,
+    flavor: FlavorOpt = None,
+    timeout: TimeoutOpt = None,
+    detach: DetachOpt = False,
+    expose: ExposeOpt = None,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Run a Job."""
+    env_map = parse_env_map(env, env_file)
+    secrets_map = parse_env_map(secrets, secrets_file)
+
+    api = get_hf_api(token=token)
+    job = api.run_job(
+        image=image,
+        command=command,
+        env=env_map,
+        secrets=secrets_map,
+        labels=_parse_labels_map(label),
+        volumes=parse_volumes(volume),
+        flavor=flavor,
+        timeout=timeout,
+        expose=expose,
+        namespace=namespace,
+    )
+    out.result("Job started", id=job.id, url=job.url)
+    if isinstance(job.status.expose_urls, list):
+        urls = "\n".join(f"  {url}" for url in job.status.expose_urls)
+        out.hint(f"Exposed ports are reachable at (requires an HF token with read access to the job):\n{urls}")
+    if detach:
+        job_ref = f"{job.owner.name}/{job.id}"
+        out.hint(f"Use `hf jobs logs -f {job_ref}` to stream logs, or `hf jobs inspect {job_ref}` to check status.")
+        return
+    for log in api.fetch_job_logs(job_id=job.id, namespace=job.owner.name, follow=True):
+        out.text(log)
+
+
+@jobs_cli.command(
+    "logs",
+    examples=[
+        "hf jobs logs <job_id>",
+        "hf jobs logs -f <job_id>",
+        "hf jobs logs --tail 20 <job_id>",
+        "hf jobs logs -f --tail 100 <job_id>",
+    ],
+)
+def jobs_logs(
+    job_id: JobIdArg,
+    follow: Annotated[
+        bool,
+        typer.Option(
+            "-f",
+            "--follow",
+            help="Follow log output (stream until the job completes). Without this flag, only currently available logs are printed.",
+        ),
+    ] = False,
+    tail: Annotated[
+        int | None,
+        typer.Option(
+            "-n",
+            "--tail",
+            help="Number of lines to show from the end of the logs. When combined with --follow, starts streaming from the last N lines.",
+        ),
+    ] = None,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Fetch the logs of a Job.
+
+    By default, prints currently available logs and exits (non-blocking).
+    Use --follow/-f to stream logs in real-time until the job completes.
+    Use --tail/-n to limit the number of lines returned (server-side when supported).
+
+    Note: following exits when the log stream ends, regardless of whether the Job
+    succeeded or failed. Run `hf jobs inspect <job_id>` to check the final status.
+    """
+    job_id, namespace = _parse_namespace_from_job_id(job_id, namespace)
+
+    api = get_hf_api(token=token)
+    try:
+        logs = api.fetch_job_logs(job_id=job_id, namespace=namespace, follow=follow, tail=tail)
+        for log in logs:
+            out.text(log)
+        if follow:
+            job_ref = f"{namespace}/{job_id}" if namespace else job_id
+            out.hint(
+                f"Stream ended. Run `hf jobs inspect {job_ref}` to check the final status (e.g. COMPLETED or ERROR)."
+            )
+    except HfHubHTTPError as e:
+        status = e.response.status_code if e.response is not None else None
+        if status == 404:
+            raise CLIError("Job not found. Please check the job ID.") from e
+        elif status == 403:
+            raise CLIError("Access denied. You may not have permission to view this job.") from e
+        else:
+            raise CLIError(f"Failed to fetch job logs: {e}") from e
+
+
+def _matches_filters(job_properties: dict[str, str], filters: list[tuple[str, str, str]]) -> bool:
+    """Check if scheduled job matches all specified filters."""
+    for key, op_str, pattern in filters:
+        value = job_properties.get(key)
+        if value is None:
+            if op_str == "!=":
+                continue
+            return False
+        match = fnmatch(value.lower(), pattern.lower())
+        if (op_str == "=" and not match) or (op_str == "!=" and match):
+            return False
+    return True
+
+
+def _clear_line(n: int) -> None:
+    LINE_UP = "\033[1A"
+    LINE_CLEAR = "\x1b[2K"
+    for i in range(n):
+        print(LINE_UP, end=LINE_CLEAR)
+
+
+def _get_jobs_stats_rows(
+    job_id: str, metrics_stream: Iterable[dict[str, Any]], table_headers: list[str]
+) -> Iterable[tuple[bool, str, list[list[str | int]]]]:
+    for metrics in metrics_stream:
+        row = [
+            job_id,
+            f"{metrics['cpu_usage_pct']}%",
+            round(metrics["cpu_millicores"] / 1000.0, 1),
+            f"{round(100 * metrics['memory_used_bytes'] / metrics['memory_total_bytes'], 2)}%",
+            f"{_format_size(metrics['memory_used_bytes'])}B / {_format_size(metrics['memory_total_bytes'])}B",
+            f"{_format_size(metrics['rx_bps'])}bps / {_format_size(metrics['tx_bps'])}bps",
+        ]
+        if metrics["gpus"] and isinstance(metrics["gpus"], dict):
+            rows = [row] + [[""] * len(row)] * (len(metrics["gpus"]) - 1)
+            for row, gpu_id in zip(rows, sorted(metrics["gpus"])):
+                gpu = metrics["gpus"][gpu_id]
+                row += [
+                    f"{gpu['utilization']}%",
+                    f"{round(100 * gpu['memory_used_bytes'] / gpu['memory_total_bytes'], 2)}%",
+                    f"{_format_size(gpu['memory_used_bytes'])}B / {_format_size(gpu['memory_total_bytes'])}B",
+                ]
+        else:
+            row += ["N/A"] * (len(table_headers) - len(row))
+            rows = [row]
+        yield False, job_id, rows
+    yield True, job_id, []
+
+
+@jobs_cli.command("stats", examples=["hf jobs stats <job_id>"])
+def jobs_stats(
+    job_ids: JobIdsArg = None,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Fetch the resource usage statistics and metrics of Jobs"""
+    if job_ids is not None:
+        parsed_ids = []
+        for job_id in job_ids:
+            job_id, namespace = _parse_namespace_from_job_id(job_id, namespace)
+            parsed_ids.append(job_id)
+        job_ids = parsed_ids
+    api = get_hf_api(token=token)
+    if namespace is None:
+        namespace = api.whoami()["name"]
+    if job_ids is None:
+        job_ids = [
+            job.id
+            for job in api.list_jobs(namespace=namespace)
+            if (job.status.stage if job.status else "UNKNOWN") in ("RUNNING", "UPDATING")
+        ]
+    if len(job_ids) == 0:
+        out.text("No running jobs found")
+        return
+    table_headers = [
+        "JOB ID",
+        "CPU %",
+        "NUM CPU",
+        "MEM %",
+        "MEM USAGE",
+        "NET I/O",
+        "GPU UTIL %",
+        "GPU MEM %",
+        "GPU MEM USAGE",
+    ]
+    try:
+        with multiprocessing.pool.ThreadPool(len(job_ids)) as pool:
+            rows_per_job_id: dict[str, list[list[str | int]]] = {}
+            for job_id in job_ids:
+                row: list[str | int] = [job_id]
+                row += ["-- / --" if ("/" in header or "USAGE" in header) else "--" for header in table_headers[1:]]
+                rows_per_job_id[job_id] = [row]
+            last_update_time = time.time()
+            total_rows = [row for job_id in rows_per_job_id for row in rows_per_job_id[job_id]]
+            # In-place refresh (cursor-up + clear) requires a fixed line count and layout —
+            # `out.table`'s mode-dependent formatting would break it.
+            print(_tabulate(total_rows, headers=table_headers))
+
+            kwargs_list = [
+                {
+                    "job_id": job_id,
+                    "metrics_stream": api.fetch_job_metrics(job_id=job_id, namespace=namespace),
+                    "table_headers": table_headers,
+                }
+                for job_id in job_ids
+            ]
+            for done, job_id, rows in iflatmap_unordered(pool, _get_jobs_stats_rows, kwargs_list=kwargs_list):
+                if done:
+                    rows_per_job_id.pop(job_id, None)
+                else:
+                    rows_per_job_id[job_id] = rows
+                now = time.time()
+                if now - last_update_time >= STATS_UPDATE_MIN_INTERVAL:
+                    _clear_line(2 + len(total_rows))
+                    total_rows = [row for job_id in rows_per_job_id for row in rows_per_job_id[job_id]]
+                    print(_tabulate(total_rows, headers=table_headers))
+                    last_update_time = now
+    except HfHubHTTPError as e:
+        status = e.response.status_code if e.response is not None else None
+        if status == 404:
+            raise CLIError("Job not found. Please check the job ID.") from e
+        elif status == 403:
+            raise CLIError("Access denied. You may not have permission to view this job.") from e
+        else:
+            raise CLIError(f"Failed to fetch job stats: {e}") from e
+
+
+@jobs_cli.command("ps", examples=["hf jobs ps", "hf jobs ps -a"])
+def jobs_ps(
+    all: Annotated[
+        bool,
+        typer.Option(
+            "-a",
+            "--all",
+            help="Show all Jobs (default shows just running)",
+        ),
+    ] = False,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+    filter: Annotated[
+        list[str] | None,
+        typer.Option(
+            "-f",
+            "--filter",
+            help="Filter output based on conditions provided (format: key=value)",
+        ),
+    ] = None,
+) -> None:
+    """List Jobs."""
+    api = get_hf_api(token=token)
+    jobs = api.list_jobs(namespace=namespace)
+
+    filters: list[tuple[str, str, str]] = []
+    labels_filters: list[tuple[str, str, str]] = []
+    for f in filter or []:
+        if f.startswith("label!=") or f.startswith("label="):
+            if f.startswith("label!="):
+                label_part = f[len("label!=") :]
+                if "=" in label_part:
+                    out.warning(f"Ignoring invalid label filter format 'label!={label_part}'. Use label!=key format.")
+                    continue
+                label_key, op, label_value = label_part, "!=", "*"
+            else:
+                label_part = f[len("label=") :]
+                if "=" in label_part:
+                    label_key, label_value = label_part.split("=", 1)
+                else:
+                    label_key, label_value = label_part, "*"
+                # Negate predicate in case of key!=value
+                if label_key.endswith("!"):
+                    op = "!="
+                    label_key = label_key[:-1]
+                else:
+                    op = "="
+            labels_filters.append((label_key.lower(), op, label_value.lower()))
+        elif "=" in f:
+            key, value = f.split("=", 1)
+            # Negate predicate in case of key!=value
+            if key.endswith("!"):
+                op = "!="
+                key = key[:-1]
+            else:
+                op = "="
+            filters.append((key.lower(), op, value.lower()))
+        else:
+            out.warning(f"Ignoring invalid filter format '{f}'. Use key=value format.")
+
+    # Filter jobs (operating on JobInfo objects to preserve existing filter behavior)
+    filtered_jobs = []
+    for job in jobs:
+        status = job.status.stage if job.status else "UNKNOWN"
+        if not all and status not in ("RUNNING", "UPDATING"):
+            continue
+        image_or_space = job.docker_image or "N/A"
+        cmd = job.command or []
+        command_str = " ".join(cmd) if cmd else "N/A"
+        props = {"id": job.id, "image": image_or_space, "status": status.lower(), "command": command_str}
+        if not _matches_filters(props, filters):
+            continue
+        if not _matches_filters(job.labels or {}, labels_filters):
+            continue
+        filtered_jobs.append(job)
+
+    # Build display items. Augment the raw api dict with curated, table-friendly columns.
+    items: list[dict[str, Any]] = []
+    for job in filtered_jobs:
+        item = _dataclass_to_dict(job)
+        durations = item.get("durations") or {}
+        cmd = item.get("command") or []
+        item["job_id"] = item.get("id", "")
+        item["image/space"] = item.get("docker_image") or "N/A"
+        item["command"] = " ".join(cmd) if cmd else "N/A"
+        item["created"] = item["created_at"][:19].replace("T", " ") if item.get("created_at") else "N/A"
+        item["status"] = (item.get("status") or {}).get("stage", "UNKNOWN")
+        item["runtime"] = format_duration(durations.get("running_secs"))
+        items.append(item)
+
+    out.table(
+        items,
+        headers=["job_id", "image/space", "command", "created", "status", "runtime"],
+        id_key="job_id",
+    )
+    if not items:
+        if filters:
+            filters_msg = ", ".join(f"{k}{o}{v}" for k, o, v in filters)
+            out.text(f"No jobs matched filters: {filters_msg}")
+        elif not all and not labels_filters:
+            out.hint("No running jobs. Use `-a`/`--all` to include finished (and failed) jobs.")
+
+
+@jobs_cli.command("hardware", examples=["hf jobs hardware"])
+def jobs_hardware() -> None:
+    """List available hardware options for Jobs"""
+    api = get_hf_api()
+    hardware_list = api.list_jobs_hardware()
+    items = []
+    for hw in hardware_list:
+        accelerator_info = ""
+        if hw.accelerator:
+            accelerator_info = f"{hw.accelerator.quantity}x {hw.accelerator.model} ({hw.accelerator.vram})"
+        cost_min = f"${hw.unit_cost_usd:.4f}" if hw.unit_cost_usd else "free"
+        cost_hour = f"${hw.unit_cost_usd * 60:.2f}" if hw.unit_cost_usd else "free"
+        items.append(
+            {
+                "name": hw.name,
+                "pretty name": hw.pretty_name,
+                "cpu": hw.cpu,
+                "ram": hw.ram,
+                "storage": hw.ephemeral_storage,
+                "accelerator": accelerator_info,
+                "cost/min": cost_min,
+                "cost/hour": cost_hour,
+            }
+        )
+    out.table(items)
+    out.hint("Use `hf jobs run --flavor <name> ...` to request a specific hardware flavor.")
+
+
+@jobs_cli.command("inspect", examples=["hf jobs inspect <job_id>"])
+def jobs_inspect(
+    job_ids: Annotated[
+        list[str],
+        typer.Argument(
+            help="Job IDs to inspect (or 'namespace/job_id')",
+        ),
+    ],
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Display detailed information on one or more Jobs"""
+    parsed_ids = []
+    for job_id in job_ids:
+        job_id, namespace = _parse_namespace_from_job_id(job_id, namespace)
+        parsed_ids.append(job_id)
+    job_ids = parsed_ids
+    api = get_hf_api(token=token)
+    try:
+        jobs = [api.inspect_job(job_id=job_id, namespace=namespace) for job_id in job_ids]
+    except HfHubHTTPError as e:
+        status = e.response.status_code if e.response is not None else None
+        if status == 404:
+            raise CLIError("Job not found. Please check the job ID.") from e
+        elif status == 403:
+            raise CLIError("Access denied. You may not have permission to view this job.") from e
+        else:
+            raise CLIError(f"Failed to inspect job: {e}") from e
+    out.table([_dataclass_to_dict(job) for job in jobs])
+
+
+@jobs_cli.command("cancel", examples=["hf jobs cancel <job_id>"])
+def jobs_cancel(
+    job_id: JobIdArg,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Cancel a Job"""
+    job_id, namespace = _parse_namespace_from_job_id(job_id, namespace)
+    api = get_hf_api(token=token)
+    try:
+        api.cancel_job(job_id=job_id, namespace=namespace)
+    except HfHubHTTPError as e:
+        status = e.response.status_code if e.response is not None else None
+        if status == 404:
+            raise CLIError("Job not found. Please check the job ID.") from e
+        elif status == 403:
+            raise CLIError("Access denied. You may not have permission to cancel this job.") from e
+        else:
+            raise CLIError(f"Failed to cancel job: {e}") from e
+    out.result("Job cancelled", id=job_id)
+
+
+@jobs_cli.command(
+    "labels",
+    examples=[
+        "hf jobs labels <job_id> --label env=prod --label team=ml",
+        "hf jobs labels <job_id> --clear",
+    ],
+)
+def jobs_labels(
+    job_id: JobIdArg,
+    label: LabelsOpt = None,
+    clear: Annotated[bool, typer.Option("--clear", help="Remove all labels from the job.")] = False,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Update labels on a Job. Replaces all existing labels."""
+    if not label and not clear:
+        raise CLIError("Please set at least one label with --label. To remove all labels, pass --clear.")
+    if label and clear:
+        raise CLIError(
+            "Cannot set labels and clear them at the same time. Please use either --label or --clear, not both."
+        )
+    job_id, namespace = _parse_namespace_from_job_id(job_id, namespace)
+    labels = _parse_labels_map(label) or {}
+    api = get_hf_api(token=token)
+    job = api.update_job_labels(job_id=job_id, labels=labels, namespace=namespace)
+    out.result("Labels updated", id=job.id)
+
+
+uv_app = typer_factory(help="Run UV scripts (Python with inline dependencies) on HF infrastructure.")
+jobs_cli.add_typer(uv_app, name="uv")
+
+
+@uv_app.command(
+    "run",
+    context_settings={"ignore_unknown_options": True},
+    examples=[
+        "hf jobs uv run my_script.py",
+        "hf jobs uv run --detach my_script.py",
+        "hf jobs uv run ml_training.py --flavor a10g-small",
+        "hf jobs uv run --with transformers train.py",
+        "hf jobs uv run -v hf://org/my-model:/data -v hf://buckets/org/b:/mnt script.py",
+    ],
+)
+def jobs_uv_run(
+    script: ScriptArg,
+    script_args: ScriptArgsArg = None,
+    image: ImageOpt = None,
+    flavor: FlavorOpt = None,
+    env: EnvOpt = None,
+    secrets: SecretsOpt = None,
+    label: LabelsOpt = None,
+    volume: VolumesOpt = None,
+    env_file: EnvFileOpt = None,
+    secrets_file: SecretsFileOpt = None,
+    timeout: TimeoutOpt = None,
+    detach: DetachOpt = False,
+    expose: ExposeOpt = None,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+    with_: WithOpt = None,
+    python: PythonOpt = None,
+) -> None:
+    """Run a UV script (local file or URL) on HF infrastructure"""
+    env_map = parse_env_map(env, env_file)
+    secrets_map = parse_env_map(secrets, secrets_file)
+
+    api = get_hf_api(token=token)
+    job = api.run_uv_job(
+        script=script,
+        script_args=script_args or [],
+        dependencies=with_,
+        python=python,
+        image=image,
+        env=env_map,
+        secrets=secrets_map,
+        labels=_parse_labels_map(label),
+        volumes=parse_volumes(volume),
+        flavor=flavor,
+        timeout=timeout,
+        expose=expose,
+        namespace=namespace,
+    )
+    out.result("Job started", id=job.id, url=job.url)
+    if isinstance(job.status.expose_urls, list):
+        urls = "\n".join(f"  {url}" for url in job.status.expose_urls)
+        out.hint(f"Exposed ports are reachable at (requires an HF token with read access to the job):\n{urls}")
+    if detach:
+        job_ref = f"{job.owner.name}/{job.id}"
+        out.hint(f"Use `hf jobs logs -f {job_ref}` to stream logs, or `hf jobs inspect {job_ref}` to check status.")
+        return
+    for log in api.fetch_job_logs(job_id=job.id, namespace=job.owner.name, follow=True):
+        out.text(log)
+
+
+scheduled_app = typer_factory(help="Create and manage scheduled Jobs on the Hub.")
+jobs_cli.add_typer(scheduled_app, name="scheduled")
+
+
+@scheduled_app.command(
+    "run",
+    context_settings={"ignore_unknown_options": True},
+    examples=['hf jobs scheduled run "0 0 * * *" python:3.12 python script.py'],
+)
+def scheduled_run(
+    schedule: ScheduleArg,
+    image: ImageArg,
+    command: CommandArg,
+    suspend: SuspendOpt = None,
+    concurrency: ConcurrencyOpt = None,
+    env: EnvOpt = None,
+    secrets: SecretsOpt = None,
+    label: LabelsOpt = None,
+    volume: VolumesOpt = None,
+    env_file: EnvFileOpt = None,
+    secrets_file: SecretsFileOpt = None,
+    flavor: FlavorOpt = None,
+    timeout: TimeoutOpt = None,
+    expose: ExposeOpt = None,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Schedule a Job."""
+    env_map = parse_env_map(env, env_file)
+    secrets_map = parse_env_map(secrets, secrets_file)
+
+    api = get_hf_api(token=token)
+    scheduled_job = api.create_scheduled_job(
+        image=image,
+        command=command,
+        schedule=schedule,
+        suspend=suspend,
+        concurrency=concurrency,
+        env=env_map,
+        secrets=secrets_map,
+        labels=_parse_labels_map(label),
+        volumes=parse_volumes(volume),
+        flavor=flavor,
+        timeout=timeout,
+        expose=expose,
+        namespace=namespace,
+    )
+    out.result("Scheduled Job created", id=scheduled_job.id)
+    out.hint(f"Use `hf jobs scheduled inspect {scheduled_job.id}` to view its details.")
+
+
+@scheduled_app.command("ps", examples=["hf jobs scheduled ps"])
+def scheduled_ps(
+    all: Annotated[
+        bool,
+        typer.Option(
+            "-a",
+            "--all",
+            help="Show all scheduled Jobs (default hides suspended)",
+        ),
+    ] = False,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+    filter: Annotated[
+        list[str] | None,
+        typer.Option(
+            "-f",
+            "--filter",
+            help="Filter output based on conditions provided (format: key=value)",
+        ),
+    ] = None,
+) -> None:
+    """List scheduled Jobs"""
+    api = get_hf_api(token=token)
+    scheduled_jobs = api.list_scheduled_jobs(namespace=namespace)
+    filters: list[tuple[str, str, str]] = []
+    for f in filter or []:
+        if "=" in f:
+            key, value = f.split("=", 1)
+            # Negate predicate in case of key!=value
+            if key.endswith("!"):
+                op = "!="
+                key = key[:-1]
+            else:
+                op = "="
+            filters.append((key.lower(), op, value.lower()))
+        else:
+            out.warning(f"Ignoring invalid filter format '{f}'. Use key=value format.")
+
+    # Filter scheduled jobs (operating on ScheduledJobInfo objects to preserve existing filter behavior)
+    filtered_jobs = []
+    for scheduled_job in scheduled_jobs:
+        suspend = scheduled_job.suspend or False
+        if not all and suspend:
+            continue
+        image_or_space = scheduled_job.job_spec.docker_image or "N/A"
+        cmd = scheduled_job.job_spec.command or []
+        command_str = " ".join(cmd) if cmd else "N/A"
+        props = {"id": scheduled_job.id, "image": image_or_space, "suspend": str(suspend), "command": command_str}
+        if not _matches_filters(props, filters):
+            continue
+        filtered_jobs.append(scheduled_job)
+
+    # Build display items. Augment with curated columns.
+    items: list[dict[str, Any]] = []
+    for sj in filtered_jobs:
+        item = _dataclass_to_dict(sj)
+        job_spec = item.get("job_spec") or {}
+        status_dict = item.get("status") or {}
+        last_job = status_dict.get("last_job")
+        cmd = job_spec.get("command") or []
+        item["image/space"] = job_spec.get("docker_image") or "N/A"
+        item["command"] = " ".join(cmd) if cmd else "N/A"
+        item["last_run"] = last_job["at"][:19].replace("T", " ") if last_job and last_job.get("at") else "N/A"
+        item["next_run"] = (
+            status_dict["next_job_run_at"][:19].replace("T", " ") if status_dict.get("next_job_run_at") else "N/A"
+        )
+        item["suspend"] = item.get("suspend") or False
+        items.append(item)
+
+    out.table(
+        items,
+        headers=["id", "schedule", "image/space", "command", "last_run", "next_run", "suspend"],
+        id_key="id",
+    )
+    if not items and filters:
+        filters_msg = ", ".join(f"{k}{o}{v}" for k, o, v in filters)
+        out.text(f"No scheduled jobs matched filters: {filters_msg}")
+
+
+@scheduled_app.command("inspect", examples=["hf jobs scheduled inspect <id>"])
+def scheduled_inspect(
+    scheduled_job_ids: Annotated[
+        list[str],
+        typer.Argument(
+            help="Scheduled Job IDs to inspect (or 'namespace/scheduled_job_id')",
+        ),
+    ],
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Display detailed information on one or more scheduled Jobs"""
+    parsed_ids = []
+    for job_id in scheduled_job_ids:
+        job_id, namespace = _parse_namespace_from_job_id(job_id, namespace)
+        parsed_ids.append(job_id)
+    scheduled_job_ids = parsed_ids
+    api = get_hf_api(token=token)
+    scheduled_jobs = [
+        api.inspect_scheduled_job(scheduled_job_id=scheduled_job_id, namespace=namespace)
+        for scheduled_job_id in scheduled_job_ids
+    ]
+    out.table([_dataclass_to_dict(scheduled_job) for scheduled_job in scheduled_jobs])
+
+
+@scheduled_app.command("delete", examples=["hf jobs scheduled delete <id>"])
+def scheduled_delete(
+    scheduled_job_id: ScheduledJobIdArg,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Delete a scheduled Job."""
+    scheduled_job_id, namespace = _parse_namespace_from_job_id(scheduled_job_id, namespace)
+    api = get_hf_api(token=token)
+    api.delete_scheduled_job(scheduled_job_id=scheduled_job_id, namespace=namespace)
+    out.result("Scheduled Job deleted", id=scheduled_job_id)
+
+
+@scheduled_app.command("suspend", examples=["hf jobs scheduled suspend <id>"])
+def scheduled_suspend(
+    scheduled_job_id: ScheduledJobIdArg,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Suspend (pause) a scheduled Job."""
+    scheduled_job_id, namespace = _parse_namespace_from_job_id(scheduled_job_id, namespace)
+    api = get_hf_api(token=token)
+    api.suspend_scheduled_job(scheduled_job_id=scheduled_job_id, namespace=namespace)
+    out.result("Scheduled Job suspended", id=scheduled_job_id)
+    out.hint(f"Use `hf jobs scheduled resume {scheduled_job_id}` to resume it.")
+
+
+@scheduled_app.command("resume", examples=["hf jobs scheduled resume <id>"])
+def scheduled_resume(
+    scheduled_job_id: ScheduledJobIdArg,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Resume (unpause) a scheduled Job."""
+    scheduled_job_id, namespace = _parse_namespace_from_job_id(scheduled_job_id, namespace)
+    api = get_hf_api(token=token)
+    api.resume_scheduled_job(scheduled_job_id=scheduled_job_id, namespace=namespace)
+    out.result("Scheduled Job resumed", id=scheduled_job_id)
+
+
+@scheduled_app.command(
+    "labels",
+    examples=[
+        "hf jobs scheduled labels <id> --label env=prod --label team=ml",
+        "hf jobs scheduled labels <id> --clear",
+    ],
+)
+def scheduled_labels(
+    scheduled_job_id: ScheduledJobIdArg,
+    label: LabelsOpt = None,
+    clear: Annotated[bool, typer.Option("--clear", help="Remove all labels from the scheduled job.")] = False,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Update labels on a scheduled Job. Replaces all existing labels."""
+    if not label and not clear:
+        raise CLIError("Please set at least one label with --label. To remove all labels, pass --clear.")
+    if label and clear:
+        raise CLIError(
+            "Cannot set labels and clear them at the same time. Please use either --label or --clear, not both."
+        )
+    scheduled_job_id, namespace = _parse_namespace_from_job_id(scheduled_job_id, namespace)
+    labels = _parse_labels_map(label) or {}
+    api = get_hf_api(token=token)
+    scheduled_job = api.update_scheduled_job_labels(
+        scheduled_job_id=scheduled_job_id, labels=labels, namespace=namespace
+    )
+    out.result("Labels updated", id=scheduled_job.id)
+
+
+scheduled_uv_app = typer_factory(help="Schedule UV scripts on HF infrastructure.")
+scheduled_app.add_typer(scheduled_uv_app, name="uv")
+
+
+@scheduled_uv_app.command(
+    "run",
+    context_settings={"ignore_unknown_options": True},
+    examples=[
+        'hf jobs scheduled uv run "0 0 * * *" script.py',
+        'hf jobs scheduled uv run "0 0 * * *" script.py --with pandas',
+    ],
+)
+def scheduled_uv_run(
+    schedule: ScheduleArg,
+    script: ScriptArg,
+    script_args: ScriptArgsArg = None,
+    suspend: SuspendOpt = None,
+    concurrency: ConcurrencyOpt = None,
+    image: ImageOpt = None,
+    flavor: FlavorOpt = None,
+    env: EnvOpt = None,
+    secrets: SecretsOpt = None,
+    label: LabelsOpt = None,
+    volume: VolumesOpt = None,
+    env_file: EnvFileOpt = None,
+    secrets_file: SecretsFileOpt = None,
+    timeout: TimeoutOpt = None,
+    expose: ExposeOpt = None,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+    with_: WithOpt = None,
+    python: PythonOpt = None,
+) -> None:
+    """Run a UV script (local file or URL) on HF infrastructure"""
+    env_map = parse_env_map(env, env_file)
+    secrets_map = parse_env_map(secrets, secrets_file)
+
+    api = get_hf_api(token=token)
+    job = api.create_scheduled_uv_job(
+        script=script,
+        script_args=script_args or [],
+        schedule=schedule,
+        suspend=suspend,
+        concurrency=concurrency,
+        dependencies=with_,
+        python=python,
+        image=image,
+        env=env_map,
+        secrets=secrets_map,
+        labels=_parse_labels_map(label),
+        volumes=parse_volumes(volume),
+        flavor=flavor,
+        timeout=timeout,
+        expose=expose,
+        namespace=namespace,
+    )
+    out.result("Scheduled Job created", id=job.id)
+    out.hint(f"Use `hf jobs scheduled inspect {job.id}` to view its details.")
+
+
+### UTILS
+
+
+def _parse_labels_map(labels: list[str] | None) -> dict[str, str] | None:
+    """Parse label key-value pairs from CLI arguments.
+
+    Args:
+        labels: List of label strings in KEY=VALUE format. If KEY only, then VALUE is set to empty string.
+
+    Returns:
+        Dictionary mapping label keys to values, or None if no labels provided.
+    """
+    if not labels:
+        return None
+    labels_map: dict[str, str] = {}
+    for label_var in labels:
+        key, value = label_var.split("=", 1) if "=" in label_var else (label_var, "")
+        labels_map[key] = value
+    return labels_map
+
+
+def _tabulate(rows: list[list[str | int]], headers: list[str]) -> str:
+    """
+    Inspired by:
+
+    - stackoverflow.com/a/8356620/593036
+    - stackoverflow.com/questions/9535954/printing-lists-as-tabular-data
+    """
+    col_widths = [max(len(str(x)) for x in col) for col in zip(*rows, headers)]
+    terminal_width = max(shutil.get_terminal_size().columns, len(headers) * 12)
+    while len(headers) + sum(col_widths) > terminal_width:
+        col_to_minimize = col_widths.index(max(col_widths))
+        col_widths[col_to_minimize] //= 2
+        if len(headers) + sum(col_widths) <= terminal_width:
+            col_widths[col_to_minimize] = terminal_width - sum(col_widths) - len(headers) + col_widths[col_to_minimize]
+    row_format = ("{{:{}}} " * len(headers)).format(*col_widths)
+    lines = []
+    lines.append(row_format.format(*headers))
+    lines.append(row_format.format(*["-" * w for w in col_widths]))
+    for row in rows:
+        row_format_args = [
+            str(x)[: col_width - 3] + "..." if len(str(x)) > col_width else str(x)
+            for x, col_width in zip(row, col_widths)
+        ]
+        lines.append(row_format.format(*row_format_args))
+    return "\n".join(lines)
+
+
+T = TypeVar("T")
+
+
+def _write_generator_to_queue(queue: Queue[T], func: Callable[..., Iterable[T]], kwargs: dict) -> None:
+    for result in func(**kwargs):
+        queue.put(result)
+
+
+def iflatmap_unordered(
+    pool: multiprocessing.pool.ThreadPool,
+    func: Callable[..., Iterable[T]],
+    *,
+    kwargs_list: list[dict],
+) -> Iterable[T]:
+    """
+    Takes a function that returns an iterable of items, and run it in parallel using threads to return the flattened iterable of items as they arrive.
+
+    This is inspired by those three `map()` variants, and is the mix of all three:
+
+    * `imap()`: like `map()` but returns an iterable instead of a list of results
+    * `imap_unordered()`: like `imap()` but the output is sorted by time of arrival
+    * `flatmap()`: like `map()` but given a function which returns a list, `flatmap()` returns the flattened list that is the concatenation of all the output lists
+    """
+    queue: Queue[T] = Queue()
+    async_results = [pool.apply_async(_write_generator_to_queue, (queue, func, kwargs)) for kwargs in kwargs_list]
+    try:
+        while True:
+            try:
+                yield queue.get(timeout=0.05)
+            except Empty:
+                if all(async_result.ready() for async_result in async_results) and queue.empty():
+                    break
+    except KeyboardInterrupt:
+        pass
+    finally:
+        # we get the result in case there's an error to raise
+        try:
+            [async_result.get(timeout=0.05) for async_result in async_results]
+        except multiprocessing.TimeoutError:
+            pass

venv/Lib/site-packages/huggingface_hub/cli/lfs.py

@@ -0,0 +1,176 @@
+"""
+Implementation of a custom transfer agent for the transfer type "multipart" for
+git-lfs.
+
+Inspired by:
+github.com/cbartz/git-lfs-swift-transfer-agent/blob/master/git_lfs_swift_transfer.py
+
+Spec is: github.com/git-lfs/git-lfs/blob/master/docs/custom-transfers.md
+
+
+To launch debugger while developing:
+
+``` [lfs "customtransfer.multipart"]
+path = /path/to/huggingface_hub/.venv/bin/python args = -m debugpy --listen 5678
+--wait-for-client
+/path/to/huggingface_hub/src/huggingface_hub/commands/huggingface_cli.py
+lfs-multipart-upload ```"""
+
+import json
+import os
+import subprocess
+import sys
+from typing import Annotated
+
+import typer
+
+from huggingface_hub.errors import CLIError
+from huggingface_hub.lfs import LFS_MULTIPART_UPLOAD_COMMAND
+
+from ..utils import get_session, hf_raise_for_status, logging
+from ..utils._lfs import SliceFileObj
+from ._output import out
+
+
+logger = logging.get_logger(__name__)
+
+
+def lfs_enable_largefiles(
+    path: Annotated[
+        str,
+        typer.Argument(
+            help="Local path to repository you want to configure.",
+        ),
+    ],
+) -> None:
+    """
+    Configure your repository to enable upload of files > 5GB.
+
+    This command sets up git-lfs to use the custom multipart transfer agent
+    which enables efficient uploading of large files in chunks.
+    """
+    local_path = os.path.abspath(path)
+    if not os.path.isdir(local_path):
+        raise CLIError("This does not look like a valid git repo.")
+    subprocess.run(
+        "git config lfs.customtransfer.multipart.path hf".split(),
+        check=True,
+        cwd=local_path,
+    )
+    subprocess.run(
+        f"git config lfs.customtransfer.multipart.args {LFS_MULTIPART_UPLOAD_COMMAND}".split(),
+        check=True,
+        cwd=local_path,
+    )
+    out.result("Local repo set up for largefiles", path=local_path)
+
+
+def write_msg(msg: dict):
+    """Write out the message in Line delimited JSON."""
+    msg_str = json.dumps(msg) + "\n"
+    sys.stdout.write(msg_str)
+    sys.stdout.flush()
+
+
+def read_msg() -> dict | None:
+    """Read Line delimited JSON from stdin."""
+    msg = json.loads(sys.stdin.readline().strip())
+
+    if "terminate" in (msg.get("type"), msg.get("event")):
+        # terminate message received
+        return None
+
+    if msg.get("event") not in ("download", "upload"):
+        logger.critical("Received unexpected message")
+        sys.exit(1)
+
+    return msg
+
+
+def lfs_multipart_upload() -> None:
+    """Internal git-lfs custom transfer agent for multipart uploads.
+
+    This function implements the custom transfer protocol for git-lfs multipart uploads.
+    Handles chunked uploads of large files to Hugging Face Hub.
+    """
+    # Immediately after invoking a custom transfer process, git-lfs
+    # sends initiation data to the process over stdin.
+    # This tells the process useful information about the configuration.
+    init_msg = json.loads(sys.stdin.readline().strip())
+    if not (init_msg.get("event") == "init" and init_msg.get("operation") == "upload"):
+        write_msg({"error": {"code": 32, "message": "Wrong lfs init operation"}})
+        sys.exit(1)
+
+    # The transfer process should use the information it needs from the
+    # initiation structure, and also perform any one-off setup tasks it
+    # needs to do. It should then respond on stdout with a simple empty
+    # confirmation structure, as follows:
+    write_msg({})
+
+    # After the initiation exchange, git-lfs will send any number of
+    # transfer requests to the stdin of the transfer process, in a serial sequence.
+    while True:
+        msg = read_msg()
+        if msg is None:
+            # When all transfers have been processed, git-lfs will send
+            # a terminate event to the stdin of the transfer process.
+            # On receiving this message the transfer process should
+            # clean up and terminate. No response is expected.
+            sys.exit(0)
+
+        oid = msg["oid"]
+        filepath = msg["path"]
+        completion_url = msg["action"]["href"]
+        header = msg["action"]["header"]
+        chunk_size = int(header.pop("chunk_size"))
+        presigned_urls: list[str] = list(header.values())
+
+        # Send a "started" progress event to allow other workers to start.
+        # Otherwise they're delayed until first "progress" event is reported,
+        # i.e. after the first 5GB by default (!)
+        write_msg(
+            {
+                "event": "progress",
+                "oid": oid,
+                "bytesSoFar": 1,
+                "bytesSinceLast": 0,
+            }
+        )
+
+        parts = []
+        with open(filepath, "rb") as file:
+            for i, presigned_url in enumerate(presigned_urls):
+                with SliceFileObj(
+                    file,
+                    seek_from=i * chunk_size,
+                    read_limit=chunk_size,
+                ) as data:
+                    r = get_session().put(presigned_url, data=data)
+                    hf_raise_for_status(r)
+                    parts.append(
+                        {
+                            "etag": r.headers.get("etag"),
+                            "partNumber": i + 1,
+                        }
+                    )
+                    # In order to support progress reporting while data is uploading / downloading,
+                    # the transfer process should post messages to stdout
+                    write_msg(
+                        {
+                            "event": "progress",
+                            "oid": oid,
+                            "bytesSoFar": (i + 1) * chunk_size,
+                            "bytesSinceLast": chunk_size,
+                        }
+                    )
+
+        r = get_session().post(
+            completion_url,
+            json={
+                "oid": oid,
+                "parts": parts,
+            },
+        )
+        hf_raise_for_status(r)
+
+        write_msg({"event": "complete", "oid": oid})

venv/Lib/site-packages/huggingface_hub/cli/models.py

@@ -0,0 +1,217 @@
+# Copyright 2026 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains commands to interact with models on the Hugging Face Hub.
+
+Usage:
+    # list models on the Hub
+    hf models ls
+
+    # list models with a search query
+    hf models ls --search "llama"
+
+    # get info about a model
+    hf models info Lightricks/LTX-2
+"""
+
+import enum
+from typing import Annotated, get_args
+
+import typer
+
+from huggingface_hub.errors import CLIError, RepositoryNotFoundError, RevisionNotFoundError
+from huggingface_hub.hf_api import ExpandModelProperty_T, ModelSort_T
+from huggingface_hub.repocard import ModelCard
+
+from ._cli_utils import (
+    REPO_LIST_DEFAULT_LIMIT,
+    AuthorOpt,
+    FilterOpt,
+    LimitOpt,
+    RevisionOpt,
+    SearchOpt,
+    TokenOpt,
+    get_hf_api,
+    make_expand_properties_parser,
+    typer_factory,
+)
+from ._file_listing import list_repo_files_cmd
+from ._output import _dataclass_to_dict, out
+
+
+_EXPAND_PROPERTIES = sorted(get_args(ExpandModelProperty_T))
+_SORT_OPTIONS = get_args(ModelSort_T)
+ModelSortEnum = enum.Enum("ModelSortEnum", {s: s for s in _SORT_OPTIONS}, type=str)  # type: ignore[misc]
+
+
+ExpandOpt = Annotated[
+    str | None,
+    typer.Option(
+        help=f"Comma-separated properties to return. When used, only the listed properties (and id) are returned. Example: '--expand=downloads,likes,tags'. Valid: {', '.join(_EXPAND_PROPERTIES)}.",
+        callback=make_expand_properties_parser(_EXPAND_PROPERTIES),
+    ),
+]
+
+
+models_cli = typer_factory(help="Interact with models on the Hub.")
+
+
+@models_cli.command(
+    "list | ls",
+    examples=[
+        "hf models ls --sort downloads --limit 10",
+        'hf models ls --search "llama" --author meta-llama',
+        "hf models ls --num-parameters min:6B,max:128B --sort likes",
+        "hf models ls meta-llama/Llama-3.2-1B-Instruct",
+        "hf models ls meta-llama/Llama-3.2-1B-Instruct -R",
+        "hf models ls meta-llama/Llama-3.2-1B-Instruct --tree -h",
+    ],
+)
+def models_ls(
+    repo_id: Annotated[
+        str | None,
+        typer.Argument(help="Model ID (e.g. `username/repo-name`) to list files from. If omitted, lists models."),
+    ] = None,
+    search: SearchOpt = None,
+    author: AuthorOpt = None,
+    filter: FilterOpt = None,
+    num_parameters: Annotated[
+        str | None,
+        typer.Option(help="Filter by parameter count, e.g. 'min:6B,max:128B'."),
+    ] = None,
+    sort: Annotated[
+        ModelSortEnum | None,
+        typer.Option(help="Sort results."),
+    ] = None,
+    limit: LimitOpt = REPO_LIST_DEFAULT_LIMIT,
+    expand: ExpandOpt = None,
+    human_readable: Annotated[
+        bool,
+        typer.Option("--human-readable", "-h", help="Show sizes in human readable format (only for listing files)."),
+    ] = False,
+    as_tree: Annotated[
+        bool,
+        typer.Option("--tree", help="List files in tree format (only for listing files)."),
+    ] = False,
+    recursive: Annotated[
+        bool,
+        typer.Option("--recursive", "-R", help="List files recursively (only for listing files)."),
+    ] = False,
+    revision: RevisionOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """List models on the Hub, or files in a model repo.
+
+    When called with no argument, lists models on the Hub.
+    When called with a model ID, lists files in that model repo.
+    """
+    if repo_id is not None:
+        if search is not None:
+            raise typer.BadParameter("Cannot use --search when listing files.")
+        if author is not None:
+            raise typer.BadParameter("Cannot use --author when listing files.")
+        if filter is not None:
+            raise typer.BadParameter("Cannot use --filter when listing files.")
+        if num_parameters is not None:
+            raise typer.BadParameter("Cannot use --num-parameters when listing files.")
+        if sort is not None:
+            raise typer.BadParameter("Cannot use --sort when listing files.")
+        if limit != REPO_LIST_DEFAULT_LIMIT:
+            raise typer.BadParameter("Cannot use --limit when listing files.")
+        if expand is not None:
+            raise typer.BadParameter("Cannot use --expand when listing files.")
+        return list_repo_files_cmd(
+            repo_id=repo_id,
+            repo_type="model",
+            human_readable=human_readable,
+            as_tree=as_tree,
+            recursive=recursive,
+            revision=revision,
+            token=token,
+        )
+
+    if as_tree:
+        raise typer.BadParameter("Cannot use --tree when listing models.")
+    if recursive:
+        raise typer.BadParameter("Cannot use --recursive when listing models.")
+    if human_readable:
+        raise typer.BadParameter("Cannot use --human-readable when listing models.")
+    if revision is not None:
+        raise typer.BadParameter("Cannot use --revision when listing models.")
+    api = get_hf_api(token=token)
+    sort_key = sort.value if sort else None
+    results = [
+        _dataclass_to_dict(model_info)
+        for model_info in api.list_models(
+            filter=filter,
+            author=author,
+            search=search,
+            num_parameters=num_parameters,
+            sort=sort_key,
+            limit=limit,
+            expand=expand,  # type: ignore
+        )
+    ]
+    out.table(results)
+
+
+@models_cli.command(
+    "info",
+    examples=[
+        "hf models info meta-llama/Llama-3.2-1B-Instruct",
+        "hf models info Qwen/Qwen3.5-9B --expand downloads,likes,tags",
+    ],
+)
+def models_info(
+    model_id: Annotated[str, typer.Argument(help="The model ID (e.g. `username/repo-name`).")],
+    revision: RevisionOpt = None,
+    expand: ExpandOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Get info about a model on the Hub."""
+    api = get_hf_api(token=token)
+    try:
+        info = api.model_info(repo_id=model_id, revision=revision, expand=expand)  # type: ignore
+    except RepositoryNotFoundError as e:
+        raise CLIError(f"Model '{model_id}' not found.") from e
+    except RevisionNotFoundError as e:
+        raise CLIError(f"Revision '{revision}' not found on '{model_id}'.") from e
+    out.dict(info)
+
+
+@models_cli.command(
+    "card",
+    examples=[
+        "hf models card google/gemma-4-31B-it",
+        "hf models card google/gemma-4-31B-it --metadata",
+        "hf models card google/gemma-4-31B-it --metadata --format json",
+        "hf models card google/gemma-4-31B-it --text",
+    ],
+)
+def models_card(
+    model_id: Annotated[str, typer.Argument(help="The model ID (e.g. `username/repo-name`).")],
+    metadata: Annotated[bool, typer.Option("--metadata", help="Output only the metadata from the card.")] = False,
+    text: Annotated[bool, typer.Option("--text", help="Output only the text body (no metadata).")] = False,
+    token: TokenOpt = None,
+) -> None:
+    """Get the model card (README) for a model on the Hub."""
+    if metadata and text:
+        raise CLIError("--metadata and --text are mutually exclusive.")
+    card = ModelCard.load(model_id, token=token)
+    if metadata:
+        out.dict(card.data.to_dict())
+    elif text:
+        out.text(card.text)
+    else:
+        out.text(card.content)
+        out.hint(f"Use `hf models card {model_id} --metadata` to extract only the card metadata.")

venv/Lib/site-packages/huggingface_hub/cli/papers.py

@@ -0,0 +1,197 @@
+# Copyright 2025 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains commands to interact with papers on the Hugging Face Hub.
+
+Usage:
+    # list daily papers (most recently submitted)
+    hf papers ls
+
+    # list trending papers
+    hf papers ls --sort=trending
+
+    # list papers from a specific date, ordered by upvotes
+    hf papers ls --date=2025-01-23
+
+    # list today's papers, ordered by upvotes
+    hf papers ls --date=today
+
+    # list papers from a specific week
+    hf papers ls --week=2025-W09
+
+    # list papers by a specific submitter
+    hf papers ls --submitter=someuser
+
+    # search papers
+    hf papers search "vision language"
+
+    # get info about a paper
+    hf papers info 2502.08025
+
+    # read a paper as markdown
+    hf papers read 2502.08025
+"""
+
+import datetime
+import enum
+from typing import Annotated, get_args
+
+import typer
+
+from huggingface_hub.errors import CLIError, HfHubHTTPError
+from huggingface_hub.hf_api import DailyPapersSort_T
+
+from ._cli_utils import (
+    LimitOpt,
+    TokenOpt,
+    get_hf_api,
+    typer_factory,
+)
+from ._output import _dataclass_to_dict, out
+
+
+_SORT_OPTIONS = get_args(DailyPapersSort_T)
+PaperSortEnum = enum.Enum("PaperSortEnum", {s: s for s in _SORT_OPTIONS}, type=str)  # type: ignore[misc]
+
+
+def _parse_date(value: str | None) -> str | None:
+    """Parse date option, converting 'today' to current date."""
+    if value is None:
+        return None
+    if value.lower() == "today":
+        return datetime.date.today().isoformat()
+    return value
+
+
+papers_cli = typer_factory(help="Interact with papers on the Hub.")
+
+
+@papers_cli.command(
+    "list | ls",
+    examples=[
+        "hf papers ls",
+        "hf papers ls --sort trending",
+        "hf papers ls --date 2025-01-23",
+        "hf papers ls --week 2025-W09",
+        "hf papers ls --submitter akhaliq",
+        "hf papers ls --format json",
+    ],
+)
+def papers_ls(
+    date: Annotated[
+        str | None,
+        typer.Option(
+            help="Date in ISO format (YYYY-MM-DD) or 'today'.",
+            callback=_parse_date,
+        ),
+    ] = None,
+    week: Annotated[
+        str | None,
+        typer.Option(help="ISO week to filter by, e.g. '2025-W09'."),
+    ] = None,
+    month: Annotated[
+        str | None,
+        typer.Option(help="Month to filter by in ISO format (YYYY-MM), e.g. '2025-02'."),
+    ] = None,
+    submitter: Annotated[
+        str | None,
+        typer.Option(help="Filter by username of the submitter."),
+    ] = None,
+    sort: Annotated[
+        PaperSortEnum | None,
+        typer.Option(help="Sort results."),
+    ] = None,
+    limit: LimitOpt = 50,
+    token: TokenOpt = None,
+) -> None:
+    """List daily papers on the Hub."""
+    api = get_hf_api(token=token)
+    sort_key = sort.value if sort else None
+    results = []
+    for paper_info in api.list_daily_papers(
+        date=date,
+        week=week,
+        month=month,
+        submitter=submitter,
+        sort=sort_key,
+        limit=limit,
+    ):
+        item = _dataclass_to_dict(paper_info)
+        submitted_by = item.get("submitted_by") or {}
+        item["submitted_by_name"] = submitted_by.get("fullname") or submitted_by.get("username") or ""
+        results.append(item)
+    out.table(
+        results,
+        headers=["id", "title", "upvotes", "comments", "published_at", "submitted_by_name"],
+    )
+
+
+@papers_cli.command(
+    "search",
+    examples=[
+        'hf papers search "vision language"',
+        'hf papers search "attention mechanism" --limit 10',
+        'hf papers search "diffusion" --format json',
+    ],
+)
+def papers_search(
+    query: Annotated[str, typer.Argument(help="Search query string.")],
+    limit: LimitOpt = 20,
+    token: TokenOpt = None,
+) -> None:
+    """Search papers on the Hub."""
+    api = get_hf_api(token=token)
+    results = [_dataclass_to_dict(paper_info) for paper_info in api.list_papers(query=query, limit=limit)]
+    out.table(results, headers=["id", "title", "summary", "upvotes", "published_at"])
+
+
+@papers_cli.command(
+    "info",
+    examples=[
+        "hf papers info 2601.15621",
+    ],
+)
+def papers_info(
+    paper_id: Annotated[str, typer.Argument(help="The arXiv paper ID (e.g. '2502.08025').")],
+    token: TokenOpt = None,
+) -> None:
+    """Get info about a paper on the Hub."""
+    api = get_hf_api(token=token)
+    try:
+        info = api.paper_info(id=paper_id)
+    except HfHubHTTPError as e:
+        if e.response.status_code == 404:
+            raise CLIError(f"Paper '{paper_id}' not found on the Hub.") from e
+        raise
+    out.dict(info)
+
+
+@papers_cli.command(
+    "read",
+    examples=[
+        "hf papers read 2601.15621",
+    ],
+)
+def papers_read(
+    paper_id: Annotated[str, typer.Argument(help="The arXiv paper ID (e.g. '2502.08025').")],
+    token: TokenOpt = None,
+) -> None:
+    """Read a paper as markdown."""
+    api = get_hf_api(token=token)
+    try:
+        content = api.read_paper(id=paper_id)
+    except HfHubHTTPError as e:
+        if e.response.status_code == 404:
+            raise CLIError(f"Paper '{paper_id}' not found on the Hub.") from e
+        raise
+    out.text(content)

venv/Lib/site-packages/huggingface_hub/cli/repo_files.py

@@ -0,0 +1,84 @@
+# Copyright 2023-present, the HuggingFace Inc. team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Legacy `hf repo-files` command.
+
+Kept for backward compatibility. Users are nudged to use `hf repos delete-files` instead.
+"""
+
+from typing import Annotated
+
+import typer
+
+from ._cli_utils import (
+    RepoIdArg,
+    RepoType,
+    RepoTypeOpt,
+    RevisionOpt,
+    TokenOpt,
+    get_hf_api,
+    typer_factory,
+)
+from ._output import out
+
+
+repo_files_cli = typer_factory(
+    help="(Deprecated) Manage files in a repo on the Hub. Use `hf repos delete-files` instead."
+)
+
+
+@repo_files_cli.command(
+    "delete",
+)
+def repo_files_delete(
+    repo_id: RepoIdArg,
+    patterns: Annotated[
+        list[str],
+        typer.Argument(
+            help="Glob patterns to match files to delete. Based on fnmatch, '*' matches files recursively.",
+        ),
+    ],
+    repo_type: RepoTypeOpt = RepoType.model,
+    revision: RevisionOpt = None,
+    commit_message: Annotated[
+        str | None,
+        typer.Option(
+            help="The summary / title / first line of the generated commit.",
+        ),
+    ] = None,
+    commit_description: Annotated[
+        str | None,
+        typer.Option(
+            help="The description of the generated commit.",
+        ),
+    ] = None,
+    create_pr: Annotated[
+        bool,
+        typer.Option(
+            help="Whether to create a new Pull Request for these changes.",
+        ),
+    ] = False,
+    token: TokenOpt = None,
+) -> None:
+    out.warning("`hf repo-files delete` is deprecated. Use `hf repos delete-files` instead.")
+    api = get_hf_api(token=token)
+    url = api.delete_files(
+        delete_patterns=patterns,
+        repo_id=repo_id,
+        repo_type=repo_type.value,
+        revision=revision,
+        commit_message=commit_message,
+        commit_description=commit_description,
+        create_pr=create_pr,
+    )
+    out.result("Files deleted", repo_id=repo_id, commit_url=url)