CLI Companion

The `huggingface-cli upload` command is used to upload files or directories to a repository on the Hugging Face Hub. This is a powerful command for managing your models, datasets, and Spaces directly from your terminal. It supports uploading single files, multiple files using glob patterns, or entire directories.

Prerequisites

Before using this command, ensure you are logged in to the Hugging Face Hub. You can do this by running:

bash

huggingface-cli login

Alternatively, you can provide a token directly using the `--token` argument.

Basic Syntax

bash

huggingface-cli upload <repo_id> <path_or_glob> [path_in_repo] [OPTIONS]

Arguments

* `<repo_id>`: (Required) The ID of the repository on the Hugging Face Hub. This can be in the format `username/repo_name` or `organization/repo_name`.

* `<path_or_glob>`: (Required) The path to the local file or directory you want to upload. You can also use glob patterns (e.g., `*.json`) to upload multiple files.

* `[path_in_repo]`: (Optional) The target path within the repository where the file(s) or directory should be uploaded. If omitted for a single file, the file will be uploaded to the root of the repository. If omitted for a directory, the directory's contents will be uploaded to the root. If uploading multiple files with a glob, this must be a directory path.

Options

* `--repo-type <type>`: (Optional) Specify the type of the repository. Can be `model` (default), `dataset`, or `space`.

* `--revision <branch_name>`: (Optional) The name of the branch to upload to. Defaults to `main`.

* `--commit-message <message>`: (Optional) A custom commit message for the upload. Defaults to "Upload files with huggingface-cli".

* `--token <token>`: (Optional) Your Hugging Face API token. Overrides the token stored locally after `huggingface-cli login`.

* `--force`: (Optional) Overwrite existing files on the Hub without confirmation.

* `--private`: (Optional) Set the repository to private. This option is only effective when creating a new repository with this command (e.g., when the `repo_id` does not yet exist and `--create-repo` is implicitly or explicitly used).

Usage Examples

#### 1. Upload a single file to the root of a model repository

bash

huggingface-cli upload my-username/my-awesome-model ./local-model.bin

This command uploads `local-model.bin` from your current directory to the root of `my-username/my-awesome-model`.

#### 2. Upload a single file to a specific path within a dataset repository

bash

huggingface-cli upload my-username/my-dataset ./data.json data/raw/data.json --repo-type dataset

This uploads `data.json` to the `data/raw/` directory within the `my-username/my-dataset` dataset repository.

#### 3. Upload an entire directory to a Space repository

bash

huggingface-cli upload my-username/my-cool-space ./my-app/ --repo-type space --commit-message "Add initial Streamlit app"

This uploads the entire `my-app` directory and its contents to the root of the `my-username/my-cool-space` Space, with a custom commit message.

#### 4. Upload multiple files using a glob pattern

Suppose you have `image1.jpg`, `image2.jpg`, and `image3.png` in a `my_images` folder locally, and you want to upload all `*.jpg` files to `images/` in your dataset.

bash

huggingface-cli upload my-username/my-image-dataset "./my_images/*.jpg" images/ --repo-type dataset

This uploads `image1.jpg` and `image2.jpg` from `my_images` to the `images/` directory in the specified dataset.

#### 5. Upload to a specific branch

bash

huggingface-cli upload my-username/my-model ./new_config.json --revision dev --commit-message "Update config for dev branch"

This uploads `new_config.json` to the `dev` branch of `my-username/my-model`.

#### 6. Overwrite an existing file

bash

huggingface-cli upload my-username/my-model ./updated_model.bin --force

This uploads `updated_model.bin` and overwrites `model.bin` in the repository if `updated_model.bin` is intended to replace `model.bin` (or if it has the same name and no `path_in_repo` is specified, it will overwrite the root file with the same name). If the `path_in_repo` is different, it will simply upload to that new path.

Important Notes

* **Authentication**: Always ensure you are authenticated. If not, the command will fail or prompt you to log in.

* **Existing Files**: By default, if you try to upload a file that already exists at the target path, it will be overwritten. Use `--force` to suppress interactive prompts if any are introduced in future versions, but generally, the CLI handles overwrites gracefully.

* **Directory Uploads**: When uploading a directory, the command effectively mirrors the local directory structure within the specified `path_in_repo` on the Hub.

Prerequisites

Before using this command, ensure you are logged in to the Hugging Face Hub. You can do this by running:

bash

huggingface-cli login

Alternatively, you can provide a token directly using the `--token` argument.

Basic Syntax

bash

huggingface-cli upload <repo_id> <path_or_glob> [path_in_repo] [OPTIONS]

Arguments

* `<repo_id>`: (Required) The ID of the repository on the Hugging Face Hub. This can be in the format `username/repo_name` or `organization/repo_name`.

* `<path_or_glob>`: (Required) The path to the local file or directory you want to upload. You can also use glob patterns (e.g., `*.json`) to upload multiple files.

Options

* `--repo-type <type>`: (Optional) Specify the type of the repository. Can be `model` (default), `dataset`, or `space`.

* `--revision <branch_name>`: (Optional) The name of the branch to upload to. Defaults to `main`.

* `--commit-message <message>`: (Optional) A custom commit message for the upload. Defaults to "Upload files with huggingface-cli".

* `--token <token>`: (Optional) Your Hugging Face API token. Overrides the token stored locally after `huggingface-cli login`.

* `--force`: (Optional) Overwrite existing files on the Hub without confirmation.

Usage Examples

#### 1. Upload a single file to the root of a model repository

bash

huggingface-cli upload my-username/my-awesome-model ./local-model.bin

This command uploads `local-model.bin` from your current directory to the root of `my-username/my-awesome-model`.

#### 2. Upload a single file to a specific path within a dataset repository

bash

huggingface-cli upload my-username/my-dataset ./data.json data/raw/data.json --repo-type dataset

This uploads `data.json` to the `data/raw/` directory within the `my-username/my-dataset` dataset repository.

#### 3. Upload an entire directory to a Space repository

bash

huggingface-cli upload my-username/my-cool-space ./my-app/ --repo-type space --commit-message "Add initial Streamlit app"

This uploads the entire `my-app` directory and its contents to the root of the `my-username/my-cool-space` Space, with a custom commit message.

#### 4. Upload multiple files using a glob pattern

Suppose you have `image1.jpg`, `image2.jpg`, and `image3.png` in a `my_images` folder locally, and you want to upload all `*.jpg` files to `images/` in your dataset.

bash

huggingface-cli upload my-username/my-image-dataset "./my_images/*.jpg" images/ --repo-type dataset

This uploads `image1.jpg` and `image2.jpg` from `my_images` to the `images/` directory in the specified dataset.

#### 5. Upload to a specific branch

bash

huggingface-cli upload my-username/my-model ./new_config.json --revision dev --commit-message "Update config for dev branch"

This uploads `new_config.json` to the `dev` branch of `my-username/my-model`.

#### 6. Overwrite an existing file

bash

huggingface-cli upload my-username/my-model ./updated_model.bin --force

Important Notes

* **Authentication**: Always ensure you are authenticated. If not, the command will fail or prompt you to log in.

* **Directory Uploads**: When uploading a directory, the command effectively mirrors the local directory structure within the specified `path_in_repo` on the Hub.