> ## Documentation Index
> Fetch the complete documentation index at: https://starforge.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# HuggingFace Integration

> Account linking, gated resource preflight, export push to the Hub

With the HF integration enabled (server-side `FORGE_HF_OAUTH_*` configuration), the platform works with **per-user** HF identities — no more sharing a single team token.

## What it enables

| Capability               | Description                                                                                                                                 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Account linking**      | Link your personal HF account via OAuth on the console **HuggingFace** page                                                                 |
| **Submission preflight** | Model / dataset permissions are verified at submission: unauthorized gated repos (like the Llama family) fail early instead of mid-training |
| **Export push to Hub**   | `sf export --push-repo user/name` has the server inject the **current user's** HF token                                                     |

## Link your account

<Steps>
  <Step title="Open the HuggingFace page">
    Console sidebar → **HuggingFace** (`/integrations/hf`). The entry is hidden when the integration is not enabled.
  </Step>

  <Step title="OAuth authorization">
    Read-only scopes by default (`read-repos`, `gated-repos`). Once the platform enables write access (`FORGE_HF_OAUTH_WRITE_ENABLED=true`), re-authorize to obtain the push scope.
  </Step>
</Steps>

## On the CLI side

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf export my-exp \
  --checkpoint <ckpt> --checkpoint-format nemo-dcp \
  --push-repo myorg/my-model
```

<Note>
  The `--push-repo` repo name is strictly validated (`org/name` form, preventing option injection); a failed push does not affect the local export artifact.
</Note>