# How to Publish a Model to Hugging Face Using MTPLX Forge

> Learn how to publish a model to Hugging Face with MTPLX Forge. This secure CLI command simplifies uploads, tracks provenance, and creates repositories automatically. Upload your models effortlessly today.

- Repository: [Youssof Altoukhi/MTPLX](https://github.com/youssofal/MTPLX)
- Tags: how-to-guide
- Published: 2026-09-02

---

**MTPLX Forge provides a secure CLI command that uploads your local models to the Hugging Face Hub by accepting access tokens exclusively via STDIN, automatically creating repositories, streaming model files, and generating persistent metadata in [`mtplx_runtime.json`](https://github.com/youssofal/MTPLX/blob/main/mtplx_runtime.json) and [`publish.json`](https://github.com/youssofal/MTPLX/blob/main/publish.json) for complete provenance tracking.**

The youssofal/MTPLX repository includes a specialized command-line interface called Forge that streamlines the process to publish a model to Hugging Face using MTPLX Forge. This tool eliminates manual upload steps by integrating directly with the Hugging Face Hub API while enforcing security best practices that prevent token leakage in process lists or shell history.

## Secure Authentication via STDIN

The command strictly requires that the `--token` argument be set to the literal string `stdin`. According to the source code in [`mtplx/commands/forge.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/commands/forge.py) (lines 3604-3620), the implementation validates this flag before reading the actual token from `sys.stdin` rather than the command line. This design guarantees that sensitive credentials never appear in shell history, process listings, or system logs where other users might intercept them.

## The Complete Publishing Workflow

### Step 1 – Generate and Secure Your Hugging Face Token

Before invoking the command, create a Hugging Face access token with write permissions. Store this secret in a file with restrictive permissions to prevent unauthorized access.

```bash
chmod 600 ~/.hf_token
echo "hf_..." > ~/.hf_token

```

### Step 2 – Execute the forge publish Command

The primary interface is the `mtplx forge publish` sub-command. As implemented in `mtplx/commands/forge.py#L3604-L3680`, this function orchestrates repository creation, file upload, and metadata generation through the `huggingface_hub` library.

Required parameters:

- `--repo`: Target repository identifier in `username/model-name` format
- `--path`: Local filesystem path to your prepared MTPLX model directory
- `--visibility`: Repository visibility, either `public` or `private`
- `--license`: SPDX license identifier (e.g., `MIT`, `Apache-2.0`)
- `--token`: Must be the literal string `stdin`

Optional parameters:

- `--readme-path`: Path to a custom [`README.md`](https://github.com/youssofal/MTPLX/blob/main/README.md) file for documentation
- `--out`: Base directory for run artifacts and statistics
- `--run-id`: Unique identifier for this specific publish operation

Execute the command by piping your token file:

```bash
cat ~/.hf_token | mtplx forge publish \
    --repo myorg/my-model-mtplx \
    --path ~/.mtplx/models/my-model \
    --visibility public \
    --license Apache-2.0 \
    --token stdin

```

### Step 3 – Verify Repository Creation and File Upload

The implementation at `mtplx/commands/forge.py#L3619-L3639` handles repository initialization using `huggingface_hub.HfApi.create_repo`, respecting your specified visibility settings. If the target repository already exists, the command seamlessly transitions to update mode without failing.

File streaming occurs in `mtplx/commands/forge.py#L3640-L3670`, where the code first calculates the total directory size using `directory_size_bytes` (lines 14-18), then invokes `api.upload_folder` to stream the entire model directory. If a `--readme-path` is provided, `api.upload_file` uploads the documentation separately. After upload completion, the command queries the repository for its latest revision SHA to ensure exact version tracking (lines 57-62).

## Metadata and Runtime Tracking

Upon successful completion, the command generates two critical files that establish complete audit trails:

1. **[`mtplx_runtime.json`](https://github.com/youssofal/MTPLX/blob/main/mtplx_runtime.json)**: Written inside your model directory by `_update_published_runtime` (lines 63-68), this file records the repository URL, Git revision SHA, visibility status, and license information for runtime loading and verification.

2. **[`publish.json`](https://github.com/youssofal/MTPLX/blob/main/publish.json)**: Located in the run-output directory (lines 3671-3680), this file contains operational metrics including total bytes transferred, upload speed, elapsed time, and final revision identifiers for pipeline monitoring.

## Advanced Publishing Patterns

### Publishing Private Models

Change the visibility parameter to create restricted-access repositories:

```bash
cat ~/.hf_token | mtplx forge publish \
    --repo alice/private-model \
    --path ~/my-model \
    --visibility private \
    --license Apache-2.0 \
    --token stdin

```

### Including Custom Documentation

Pass a `--readme-path` to automatically upload project documentation alongside your model weights:

```bash
cat ~/.hf_token | mtplx forge publish \
    --repo alice/my-model-mtplx \
    --path ~/my-model \
    --readme-path ./README.md \
    --visibility public \
    --license MIT \
    --token stdin

```

### Automated Pipeline Integration

For CI/CD workflows, specify explicit output directories and run IDs to capture structured results for downstream processing:

```bash
RUN_ID=$(uuidgen)
cat ~/.hf_token | mtplx forge publish \
    --repo alice/auto-model \
    --path ~/my-model \
    --out ./publish-runs \
    --run-id $RUN_ID \
    --visibility public \
    --license MIT \
    --token stdin

# Inspect upload metrics

cat ./publish-runs/$RUN_ID/publish.json

```

## Summary

- **STDIN-only token handling**: The `--token stdin` requirement enforces security by ensuring secrets never leak into process lists or shell history, as strictly validated in lines 3604-3620 of [`mtplx/commands/forge.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/commands/forge.py).
- **Automatic repository management**: The command creates new repositories or intelligently updates existing ones via `huggingface_hub.HfApi` methods defined in lines 3619-3639.
- **Comprehensive metadata**: Every upload generates [`mtplx_runtime.json`](https://github.com/youssofal/MTPLX/blob/main/mtplx_runtime.json) inside the model directory for provenance tracking and [`publish.json`](https://github.com/youssofal/MTPLX/blob/main/publish.json) in the run directory for operational metrics.
- **Flexible visibility controls**: Native support for both public and private repositories with configurable SPDX license identifiers.

## Frequently Asked Questions

### Why does MTPLX Forge require the token via STDIN instead of a command-line argument?

The implementation explicitly validates that `--token` equals `stdin` before reading from `sys.stdin` (lines 3604-3620 in [`mtplx/commands/forge.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/commands/forge.py)). This security architecture prevents the token from appearing in shell history files, process listings accessible via `ps`, or system audit logs where it could be extracted by malicious actors or exposed in shared compute environments.

### Can I publish to an existing Hugging Face repository, or will it only create new ones?

The command handles both scenarios seamlessly. When targeting an existing repository, the `api.create_repo` call (lines 20-28) recognizes the repository conflict and the execution flow continues to upload new files and update revision metadata without overwriting existing repository configurations or unrelated files.

### What information does the publish.json file contain after a successful upload?

The [`publish.json`](https://github.com/youssofal/MTPLX/blob/main/publish.json) file, written to the run-output directory specified by `--out` and `--run-id` (lines 3671-3680), contains precise upload metrics including total bytes transferred, average upload speed, elapsed time duration, the final Git revision SHA, and ISO timestamps for auditing and downstream pipeline verification.

### How do I include a README.md or other documentation with my model upload?

Use the `--readme-path` parameter to specify a local markdown file path. The publishing logic then calls `api.upload_file` (lines 38-56) separately for the README after uploading the model directory contents, ensuring your documentation appears alongside the weights in the Hugging Face Hub web interface and model cards.