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 Hugging Face CLI with your Hugging Face account. This allows you to interact with the Hugging Face Hub, including downloading private models/datasets, uploading models/datasets, and managing your repositories.

    Syntax

    bash
    huggingface-cli login

    Explanation

    When you run `huggingface-cli login`, the command will prompt you to enter your Hugging Face authentication token. This token grants the CLI access to your account on the Hugging Face Hub.

    There are two main ways to obtain your token:

    1. **Hugging Face Website**: Go to [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) in your web browser. You can find existing tokens or generate a new one. For general CLI usage, an existing "User Access Token" or a newly generated "New token" with "write" access is recommended if you plan to upload content.

    2. **Environment Variable**: You can also set the token as an environment variable `HF_TOKEN` before running any `huggingface-cli` command. If `HF_TOKEN` is set, `huggingface-cli login` will detect it and confirm the login without prompting.

    Once logged in, your token is securely stored in a configuration file (typically `~/.cache/huggingface/token`) so you don't have to re-enter it for subsequent commands.

    Usage Examples

    #### 1. Interactive Login

    This is the most common way to log in. The CLI will prompt you for your token.

    bash
    huggingface-cli login

    Upon running this, you will see output similar to:

    _|    _|  _|    _|    _|_|_|    _|_|_|  _|_|_|  _|    _|    _|_|_|_| 
    _|    _|  _|    _|  _|        _|        _|    _|  _|    _|  _|       
    _|_|_|_|  _|    _|  _|  _|_|  _|  _|_|  _|_|_|  _|    _|  _|_|_|   
    _|    _|  _|    _|  _|    _|  _|    _|  _|    _|  _|    _|  _|       
    _|    _|    _|_|      _|_|_|    _|_|_|  _|    _|    _|_|    _|_|_|_| 
    
                                           
    Token: 
    Add token as git credential? (Y/n) y
    Token is valid (permission: write). 
    Your token has been saved to /Users/yourusername/.cache/huggingface/token
    Login successful

    You would paste your token at the `Token:` prompt. The `Add token as git credential?` prompt allows you to configure Git to use this token for repository operations, which is often convenient.

    #### 2. Login using an environment variable

    If you have your token stored as an environment variable `HF_TOKEN`, you can log in non-interactively.

    bash
    export HF_TOKEN="hf_YOUR_ACTUAL_TOKEN_HERE"
    huggingface-cli login

    Output:

    Token is valid (permission: write). 
    Your token has been saved to /Users/yourusername/.cache/huggingface/token
    Login successful

    This method is particularly useful in CI/CD pipelines or automated scripts where interactive prompts are not feasible.

    #### 3. Login with a token passed directly (not recommended for security reasons in interactive shells)

    While not explicitly documented as a standard `login` argument, the `HF_TOKEN` environment variable is the intended way to provide a token non-interactively. Passing it directly as an argument to `login` is not a standard feature. However, you can achieve a similar effect by piping the token, though setting the `HF_TOKEN` environment variable is generally preferred.

    bash
    # Not a standard feature of 'huggingface-cli login' to accept token as argument
    # Use environment variable as shown above for non-interactive login.
    # For example, to use it with other commands without storing:
    # HF_TOKEN="hf_YOUR_ACTUAL_TOKEN_HERE" huggingface-cli repo create my-repo

    **Important Security Note**: Avoid hardcoding your token directly in scripts or public files. Use environment variables, secret management tools, or secure configuration files. Always ensure your token has the minimum necessary permissions (e.g., 'read' if you only intend to download models, 'write' if you plan to upload).