How to Publish a Model to Hugging Face Using MTPLX Forge

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 and 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 (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.

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

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

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:

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:

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.
• 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 inside the model directory for provenance tracking and 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). 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}