hf auth login uses browser OAuth and JSON events
Introduced 2026-06-18 · score 0.94
HOW TO USE IT
When authenticating from an agent, run the JSON login flow and relay the device URL and code; wait for the terminal success or error event. Use `get_token()` to retrieve and transparently refresh a stored OAuth token, and `hf auth list` to inspect stored tokens.
hf auth login --format jsonfrom huggingface_hub import login
login()from huggingface_hub import get_token
token = get_token()WHY THIS HELPS
Authenticate the CLI or Python client from an interactive terminal or coding agent and keep an OAuth token usable for long-running work.
BEFORE THIS CHANGE
For CLI login, copy-paste a token; in Python, use the prior `login()` behavior.
REQUIREMENTS AND LIMITATIONS
- Version: v1.20.0
- --format json: Select JSON output for agent login events; `device_code` contains the verification URL and user code, followed by an authentication terminal event.
- login(token=None): Omitting `token` uses browser OAuth; in a terminal, the user can choose browser login or paste a token.
- login(add_to_git_credential=False): Save the supplied token as a Git credential; ignored for browser login.
- login(skip_if_logged_in=True): Skip prompting if already logged in; set false to force re-login.
- Prerequisite: Install `huggingface_hub` to use its `hf` CLI and Python login API.
- Prerequisite: Browser login requires completing authorization at the displayed URL with the displayed code.
- OAuth tokens expire after 30 days.
- Token refresh occurs when less than a day of validity remains.
- The interactive terminal offers the arrow-key choice menu; agent execution does not prompt and instead streams structured events.
- Docs conflict: The later v1.20.1 CLI guide says `hf auth login` does not support `--format json` or `--format quiet` and shows `--format agent` instead. This differs from the v1.20.0 release note; do not apply the later syntax to v1.20.0. https://huggingface.co/docs/huggingface_hub/v1.20.1/en/guides/cli
FIRST-PARTY EVIDENCE
- https://github.com/huggingface/huggingface_hub/releases/tag/v1.20.0
- https://github.com/huggingface/huggingface_hub/blob/v1.20.0/src/huggingface_hub/cli/auth.py
- https://github.com/huggingface/huggingface_hub/blob/v1.20.0/src/huggingface_hub/_login.py
- https://github.com/huggingface/huggingface_hub/blob/v1.20.0/src/huggingface_hub/utils/_auth.py
- https://huggingface.co/docs/huggingface_hub/package_reference/authentication
Check the installed version and the source before using it. Entry JSON