# Publish to HuggingFace Hub

Once you have a [merged model](https://tinker-docs.thinkingmachines.ai/cookbook/deployment/export-hf/index.md) or [PEFT adapter](https://tinker-docs.thinkingmachines.ai/cookbook/deployment/lora-adapter/index.md) on disk, `publish_to_hf_hub` uploads it to a Hub repository, optionally with a generated model card.

You need a HuggingFace token with write access. `publish_to_hf_hub` reads `HF_TOKEN` or the cached login from `hf auth login`; pass `token=` to override.

## Publish

```python
from tinker_cookbook import weights

url = weights.publish_to_hf_hub(
    model_path="./merged_model",
    repo_id="my-org/my-finetuned-qwen3",
)
# -> https://huggingface.co/my-org/my-finetuned-qwen3
```

Repositories are created **private** by default. Pass `private=False` to make one public.

The same call works for an adapter directory. When `model_path` contains `adapter_config.json`, the generated model card detects the PEFT format automatically (`library_name: peft`, `peft` and `lora` tags, and a `PeftModel` usage snippet).

## Add a model card

`ModelCardConfig` holds standard HuggingFace metadata. Pass it as `model_card=` and a `README.md` is generated and included in the upload. If the directory already has a `README.md`, the existing file is kept and a warning is logged.

```python
from tinker_cookbook.weights import ModelCardConfig

card = ModelCardConfig(
    base_model="Qwen/Qwen3.5-4B",
    datasets=["my-org/my-sft-dataset"],
    tags=["sft", "chat"],
    license="apache-2.0",
    language=["en"],
)

url = weights.publish_to_hf_hub(
    model_path="./peft_adapter",
    repo_id="my-org/my-qwen3-lora",
    model_card=card,
    private=False,
)
```

The generated card carries the metadata as YAML front matter (`tinker` and `tinker-cookbook` tags are always added, plus `peft` and `lora` for adapters), a usage snippet for the detected format, and the framework versions used.

To preview a card without uploading anything:

```python
from tinker_cookbook.weights import generate_model_card

print(generate_model_card(config=card, repo_id="my-org/my-qwen3-lora"))
```

See [`publish_to_hf_hub`](https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/weights/publish_to_hf_hub/index.md) for the full parameter list.

## Push straight from Tinker with the CLI

If you only need the adapter on the Hub, you can skip the local build entirely. [`tinker checkpoint push-hf`](https://tinker-docs.thinkingmachines.ai/tinker/cli/checkpoint/#checkpoint-push-hf) takes a Tinker checkpoint path and uploads it as a PEFT adapter, creating a model card unless you pass `--no-model-card`:

```bash
tinker checkpoint push-hf tinker://<run_id>/sampler_weights/final \
    --repo my-org/my-qwen3-lora

# Public repo, opened as a pull request instead of a push to main
tinker checkpoint push-hf tinker://<run_id>/sampler_weights/final \
    --repo my-org/my-qwen3-lora --public --create-pr
```

## Next steps

- [Merge into a HuggingFace Model](https://tinker-docs.thinkingmachines.ai/cookbook/deployment/export-hf/index.md)
- [Build a PEFT LoRA Adapter](https://tinker-docs.thinkingmachines.ai/cookbook/deployment/lora-adapter/index.md)