hfm — multi-account Hugging Face manager

Manage multiple Hugging Face accounts, their repos and Spaces from one CLI, and expose the same operations to AI agents over MCP. Auth uses HF's native OAuth device flow (no tokens pasted into dotfiles), tokens are stored locally with 0600 permissions and auto-refreshed.

Install

Option 1: pipx (recommended — standalone, no venv needed)

pipx install hfm

That's it. hfm is now on your PATH, running in its own isolated environment.

Option 2: pip

pip install hfm

Option 3: from source

git clone https://github.com/wraithen0/hfm.git && cd hfm
pipx install .

Setup

1. Create a public OAuth app (no client secret) at https://huggingface.co/settings/applications/new. It needs the device-code flow; no redirect URI is required for device flow. Copy the Client ID.

2. Register it and link an account:

hfm account register-oauth <client-id>
hfm account add personal                 # opens browser, shows a device code
hfm account add work --default

Scopes default to openid profile email read-repos write-repos manage-repos read-memberships. Pass --scopes to request fewer (e.g. read-repos only). For agent-only credentials, prefer contribute-repos (agent can only touch repos it created).

3. Use it:

hfm account list
hfm repos list -a work -t dataset
hfm repos create myorg/my-model -a work
hfm repos upload ./checkpoints myorg/my-model -a work
hfm repos download myorg/my-model -t dataset --local-dir ./ds
hfm repos secret myorg/my-space MY_KEY        # prompts for value
hfm repos move old-id new-id                  # rename / transfer

Agents (MCP)

Run the MCP server over stdio:

hfm mcp                    # full mode
hfm mcp --read-only        # only read tools exposed

Add to an MCP client (e.g. Claude Desktop / any stdio-capable client):

{
  "mcpServers": {
    "hfm": {
      "command": "hfm",
      "args": ["mcp", "--read-only"]
    }
  }
}

Tools exposed

list_accounts, whoami, list_repos, repo_info; in write mode also create_repo, upload_file, upload_folder, download_repo, set_space_secret.

Safety rails

• --read-only / HFM_READ_ONLY=1 — write tools are not registered at all.
• delete_repo is only exposed when HFM_ALLOW_DESTRUCTIVE=1 (or allow_destructive: true in the config file). The CLI's hfm repos delete requires the same.
• Every agent-triggered call is appended to ~/.config/hfm/audit.log as a JSON line (tool, account, args, timestamp).

Config lives in ~/.config/hfm/ (override with HFM_CONFIG_DIR): config.json (default account, OAuth client id), tokens.json (0600), audit.log.

Notes

• OAuth access tokens are short-lived (~8 h); hfm refreshes them automatically using the stored refresh token.
• Deleting an account locally (hfm account remove) removes the local tokens; revoke the app authorization in your HF settings to kill server-side access.
• Only 2 dependencies: typer and requests. No heavy SDKs.