{
  "slug": "hf-upload-and-hf-download-accept-hf-uris-2f7865e5a6b8",
  "title": "hf upload and hf download accept hf:// URIs",
  "tools": [
    "hf"
  ],
  "tags": [
    "agent"
  ],
  "introduced_at": "2026-06-11T10:07:51.000Z",
  "announced_at": "2026-06-11T10:07:51.000Z",
  "effective_at": null,
  "date_basis": "source-publication",
  "status": "unknown",
  "how": {
    "incantation": "When uploading or downloading a repository file by URI, pass `hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]` as the repository destination/source. Keep the URI as the source of repo type, revision, and path; omit `--repo-type` and `--revision`, and omit `path_in_repo` for upload or positional filenames for download when the URI contains a path.",
    "examples": [
      "hf download hf://datasets/HuggingFaceM4/FineVision@refs/pr/1/data/train.parquet",
      "hf upload hf://datasets/Wauplin/my-cool-dataset@my-branch/data/train.csv ./train.csv"
    ],
    "gotchas": [
      "Version: v1.19.0",
      "URI `<TYPE>`: Optional repository type, such as `datasets`; when omitted, the URI defaults to a model repository.",
      "URI `<ID>` (required): Repository ID.",
      "URI `<REVISION>`: Revision such as a branch, tag, or commit; URI encodes it, so do not also set `--revision`.",
      "URI `<PATH>`: File or subfolder path in the repository; when present, do not also pass positional filenames to download or `path_in_repo` to upload.",
      "`local_path` (required): Upload source file or folder on the local machine.",
      "`--repo-type`: Normally selects repository type; cannot be set when using an `hf://` URI.",
      "`--revision`: Normally selects revision; cannot be set when using an `hf://` URI.",
      "Prerequisite: Install the `hf` CLI; the v1.19.0 guide documents the standalone installer, pip, and Homebrew options.",
      "Prerequisite: Uploading requires a token; the CLI uses the locally saved token from `hf auth login` by default.",
      "Prerequisite: Accessing private or gated repositories for download requires a token; a locally saved token is used by default.",
      "A URI with a path cannot be combined with positional filenames for download or `path_in_repo` for upload."
    ]
  },
  "why_it_matters": "Upload or download a repository file using a single URI that specifies its repository type, revision, and path.",
  "before": "Pass repository ID, repo type and revision separately; supply the file path as a download positional filename or upload `path_in_repo`.",
  "sources": [
    "https://github.com/huggingface/huggingface_hub/releases/tag/v1.19.0",
    "https://huggingface.co/docs/huggingface_hub/v1.19.0/en/guides/cli"
  ],
  "rank": 0.98042,
  "judge": {
    "publish": true,
    "judge_model": "codex-cli/gpt-6-luna+typesafe/jev-1.13.0",
    "prompt_version": "extract-v7+enrich-v2+judge-v2x3+jev-publish-v1"
  },
  "review_state": "approved",
  "provenance": {
    "run_id": "wave2b-20261017",
    "verdict_id": "wave2b-20261017:wave2b-20261017-c5141ca5a50fea07-1:gate",
    "evidence_hash": "bf16c0b37b4b30a03a0aa7a94f75ba481fea0afdc9c555610e8c55ae5a4bb937"
  },
  "review": {
    "draft_hash": "825a93777da7adebb69bac14c0828f154d109b36100c331d7399ce516619f4e4",
    "reviewer": "publication-gate",
    "reviewed_at": "2026-10-07T00:00:00.000Z",
    "decision": "wave2b-20261017:gate",
    "reason": "3 of 3 judge runs approved with p_yes >= 0.9 (mean 0.98 >= 0.9; 2 needed) and Jev gave 0.79 (>= 0.6 needed)."
  }
}