Support multiple tokens locally (#2549)

* Add multi token support

* Set git credentials when setting the active profile

* Add git credential flag as argument for auth switch method

* Fix logout helper function

* Refactor auth utils + fixes

* Remove unnecessary file creation

* Add tests and some fixes

* Make get profiles helper function public

* Add multiselect menu for auth switch command

* Move auth fixture

* Refactor logout helper function

* Update package reference and quick start documentation

* Update cli documentation

* Expose new auth methods in huggingface_hub module

* Multiple small fixes

* post-review fixes

* Fix table of contents

* Use server provided token names instead of profiles

* Add stored tokens path in the environment info

* Multiple fixes post-review

docs/source/en/_redirects.yml

@@ -9,9 +9,9 @@ how-to-upstream: guides/upload
 search-the-hub: guides/search
 guides/manage_spaces: guides/manage-spaces
 package_reference/inference_api: package_reference/inference_client
-
+package_reference/login: package_reference/authentication
 # Alias for hf-transfer description
 hf_transfer: package_reference/environment_variables#hfhubenablehftransfer
 
 # Rename webhooks_server to webhooks
-guides/webhooks_server: guides/webhooks
+guides/webhooks_server: guides/webhooks

docs/source/en/_toctree.yml

@@ -1,12 +1,12 @@
-- title: "Get started"
+- title: 'Get started'
   sections:
     - local: index
       title: Home
     - local: quick-start
       title: Quickstart
     - local: installation
       title: Installation
-- title: "How-to guides"
+- title: 'How-to guides'
   sections:
     - local: guides/overview
       title: Overview
@@ -40,16 +40,16 @@
       title: Integrate a library
     - local: guides/webhooks
       title: Webhooks
-- title: "Conceptual guides"
+- title: 'Conceptual guides'
   sections:
     - local: concepts/git_vs_http
       title: Git vs HTTP paradigm
-- title: "Reference"
+- title: 'Reference'
   sections:
     - local: package_reference/overview
       title: Overview
-    - local: package_reference/login
-      title: Login and logout
+    - local: package_reference/authentication
+      title: Authentication
     - local: package_reference/environment_variables
       title: Environment variables
     - local: package_reference/repository

docs/source/en/guides/cli.md

@@ -92,7 +92,7 @@ Once you have your token, run the following command in your terminal:
 >>> huggingface-cli login
 ```
 
-This command will prompt you for a token. Copy-paste yours and press *Enter*. Then you'll be asked if the token should also be saved as a git credential. Press *Enter* again (default to yes) if you plan to use `git` locally. Finally, it will call the Hub to check that your token is valid and save it locally.
+This command will prompt you for a token. Copy-paste yours and press *Enter*. Then, you'll be asked if the token should also be saved as a git credential. Press *Enter* again (default to yes) if you plan to use `git` locally. Finally, it will call the Hub to check that your token is valid and save it locally.
 
 ```
 _|    _|  _|    _|    _|_|_|    _|_|_|  _|_|_|  _|      _|    _|_|_|      _|_|_|_|    _|_|      _|_|_|  _|_|_|_|
@@ -102,7 +102,7 @@ _|    _|  _|    _|  _|    _|  _|    _|    _|    _|    _|_|  _|    _|      _|
 _|    _|    _|_|      _|_|_|    _|_|_|  _|_|_|  _|      _|    _|_|_|      _|        _|    _|    _|_|_|  _|_|_|_|
 
 To log in, `huggingface_hub` requires a token generated from https://huggingface.co/settings/tokens .
-Token:
+Enter your token (input will not be visible):
 Add token as git credential? (Y/n)
 Token is valid (permission: write).
 Your token has been saved in your configured git credential helpers (store).
@@ -114,11 +114,13 @@ Alternatively, if you want to log-in without being prompted, you can pass the to
 
 ```bash
 # Or using an environment variable
->>> huggingface-cli login --token $HUGGINGFACE_TOKEN --add-to-git-credential
+>>> huggingface-cli login --token $HF_TOKEN --add-to-git-credential
 Token is valid (permission: write).
+The token `token_name` has been saved to /home/wauplin/.cache/huggingface/stored_tokens
 Your token has been saved in your configured git credential helpers (store).
 Your token has been saved to /home/wauplin/.cache/huggingface/token
 Login successful
+The current active token is: `token_name`
 ```
 
 For more details about authentication, check out [this section](../quick-start#authentication).
@@ -137,7 +139,7 @@ If you are not logged in, an error message will be printed.
 
 ## huggingface-cli logout
 
-This commands logs you out. In practice, it will delete the token saved on your machine.
+This commands logs you out. In practice, it will delete all tokens stored on your machine. If you want to remove a specific token, you can specify the token name as an argument.
 
 This command will not log you out if you are logged in using the `HF_TOKEN` environment variable (see [reference](../package_reference/environment_variables#hftoken)). If that is the case, you must unset the environment variable in your machine configuration.
 
@@ -431,25 +433,25 @@ https://huggingface.co/Wauplin/my-cool-model/tree/main
 
 ## huggingface-cli repo-files
 
-If you want to delete files from a Hugging Face repository, use the `huggingface-cli repo-files` command. 
+If you want to delete files from a Hugging Face repository, use the `huggingface-cli repo-files` command.
 
 ### Delete files
 
 The `huggingface-cli repo-files <repo_id> delete` sub-command allows you to delete files from a repository. Here are some usage examples.
 
 Delete a folder :
 ```bash
->>> huggingface-cli repo-files Wauplin/my-cool-model delete folder/  
+>>> huggingface-cli repo-files Wauplin/my-cool-model delete folder/
 Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...
 ```
 
-Delete multiple files: 
+Delete multiple files:
 ```bash
 >>> huggingface-cli repo-files Wauplin/my-cool-model delete file.txt folder/pytorch_model.bin
 Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...
 ```
 
-Use Unix-style wildcards to delete sets of files: 
+Use Unix-style wildcards to delete sets of files:
 ```bash
 >>> huggingface-cli repo-files Wauplin/my-cool-model delete "*.txt" "folder/*.bin"
 Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...
@@ -460,7 +462,7 @@ Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-coo
 To delete files from a repo you must be authenticated and authorized. By default, the token saved locally (using `huggingface-cli login`) will be used. If you want to authenticate explicitly, use the `--token` option:
 
 ```bash
->>> huggingface-cli repo-files --token=hf_**** Wauplin/my-cool-model delete file.txt 
+>>> huggingface-cli repo-files --token=hf_**** Wauplin/my-cool-model delete file.txt
 ```
 
 ## huggingface-cli scan-cache

docs/source/en/package_reference/login.md → docs/source/en/package_reference/authentication.md

@@ -2,9 +2,9 @@
 rendered properly in your Markdown viewer.
 -->
 
-# Login and logout
+# Authentication
 
-The `huggingface_hub` library allows users to programmatically login and logout the machine to the Hub.
+The `huggingface_hub` library allows users to programmatically manage authentication to the Hub. This includes logging in, logging out, switching between tokens, and listing available tokens.
 
 For more details about authentication, check out [this section](../quick-start#authentication).
 
@@ -23,3 +23,11 @@ For more details about authentication, check out [this section](../quick-start#a
 ## logout
 
 [[autodoc]] logout
+
+## auth_switch
+
+[[autodoc]] auth_switch
+
+## auth_list
+
+[[autodoc]] auth_list

docs/source/en/quick-start.md

@@ -93,6 +93,19 @@ Once logged in, all requests to the Hub - even methods that don't necessarily re
 
 </Tip>
 
+### Manage multiple tokens locally
+
+You can save multiple tokens on your machine by simply logging in with the [`login`] command with each token. If you need to switch between these tokens locally, you can use the [`auth switch`] command:
+
+```bash
+huggingface-cli auth switch
+```
+
+This command will prompt you to select a token by its name from a list of saved tokens. Once selected, the chosen token becomes the _active_ token, and it will be used for all interactions with the Hub.
+
+
+You can list all available access tokens on your machine with `huggingface-cli auth list`.
+
 ### Environment variable
 
 The environment variable `HF_TOKEN` can also be used to authenticate yourself. This is especially useful in a Space where you can set `HF_TOKEN` as a [Space secret](https://huggingface.co/docs/hub/spaces-overview#managing-secrets).

src/huggingface_hub/__init__.py

@@ -63,6 +63,8 @@
         "InferenceEndpointType",
     ],
     "_login": [
+        "auth_list",
+        "auth_switch",
         "interpreter_login",
         "login",
         "logout",
@@ -582,6 +584,8 @@ def __dir__():
         InferenceEndpointType,  # noqa: F401
     )
     from ._login import (
+        auth_list,  # noqa: F401
+        auth_switch,  # noqa: F401
         interpreter_login,  # noqa: F401
         login,  # noqa: F401
         logout,  # noqa: F401