Metadata-Version: 2.4
Name: hfm
Version: 0.1.0
Summary: Multi-account Hugging Face Hub manager with OAuth and MCP support for agents
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12
Requires-Dist: requests>=2.31
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# 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)

```sh
pipx install hfm
```

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

### Option 2: pip

```sh
pip install hfm
```

### Option 3: from source

```sh
git clone <repo-url> && 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:

```sh
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:

```sh
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:

```sh
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):

```json
{
  "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.
