CLI Companion

  • Hugging Face CLI
    • login
    • whoami
    • repo create
    • upload
    • download
    • lfs-enable-largefiles
    • scan-cache
    • delete-cache
  • Hapi CLI
    • new
    • start
    • build
    • test
    • plugin create
    • route add
  • Cloudflared
    • tunnel
    • tunnel run
    • tunnel list
    • tunnel delete
    • access
    • access tcp
    • update

    The `huggingface-cli login` command is used to authenticate your local machine with the Hugging Face Hub. This allows you to download private models and datasets, and to upload models, datasets, and spaces to your Hugging Face account.

    Syntax

    bash
    huggingface-cli login

    Explanation

    When you run `huggingface-cli login`, it will prompt you to enter your Hugging Face authentication token. This token acts as your password for interacting with the Hugging Face Hub programmatically.

    **How to get a Hugging Face Token:**

    1. Go to the Hugging Face website: [huggingface.co](https://huggingface.co)

    2. Log in to your account.

    3. Navigate to your profile settings: `Settings` -> `Access Tokens`.

    4. You can create a new token or copy an existing one. Ensure the token has the necessary permissions (e.g., `write` if you intend to upload resources).

    Usage Examples

    #### 1. Interactive Login

    This is the most common way to use `huggingface-cli login`. The command will prompt you to paste your token.

    bash
    huggingface-cli login

    **Expected Output (interactive prompt):**

    Token: 
Add token to git credential helper? (Y/n)
Y
Token is valid (gallery a new token if it's not) 
Your token has been saved to /Users/yourusername/.cache/huggingface/token
Login successful

    **Explanation:**

    - `Token:`: Paste your Hugging Face token here and press Enter.

    - `Add token to git credential helper? (Y/n)`: If you type `Y` (recommended), your token will be stored securely using Git's credential helper, which makes it easier to interact with private Git repositories on Hugging Face (e.g., cloning a private model repo). If you type `n`, the token will still be saved for `huggingface_hub` operations but won't be integrated with Git's helper.

    - `Your token has been saved to ...`: The token is securely stored in a local file (typically `~/.cache/huggingface/token` on Linux/macOS or a similar path on Windows).

    #### 2. Non-Interactive Login (using environment variable)

    For automation scripts or CI/CD pipelines, you can provide the token via the `HF_TOKEN` environment variable, avoiding the interactive prompt.

    bash
    export HF_TOKEN="hf_YOUR_ACTUAL_TOKEN_HERE"
huggingface-cli login

    **Explanation:**

    - Setting `HF_TOKEN` before running `huggingface-cli login` will automatically use that token for authentication without prompting. The token will still be saved to the local cache file for future use by the `huggingface_hub` library and other commands.

    #### 3. Non-Interactive Login (piping token)

    You can also pipe the token to the command, though using `HF_TOKEN` is generally preferred for security reasons to avoid the token appearing in shell history.

    bash
    echo "hf_YOUR_ACTUAL_TOKEN_HERE" | huggingface-cli login

    **Explanation:**

    - This sends your token directly to the standard input of the `login` command, simulating interactive input.

    Post-Login

    Once logged in, `huggingface_hub` (the Python library that `huggingface-cli` uses) will automatically pick up this token for subsequent operations. You can then download private models, push changes to your repositories, and interact with the Hugging Face Hub without needing to re-authenticate until the token is revoked or deleted locally.