Python SDK / CLI

foundry-hub is the official Python client library for the Foundry platform. It lets you programmatically manage ML models, datasets, and spaces, and interact with Foundry from the command line via the CLI. It supports the same workflows as the HuggingFace Hub, so you can reuse existing code with minimal changes.

Installation

pip install foundry-hub

With CLI support:

pip install foundry-hub[cli]

Quick Start

Downloading a Model

from foundry_hub import foundry_hub_download

# Download an entire model
model_path = foundry_hub_download("username/my-model")
print(f"Model downloaded to: {model_path}")

# Download a specific file
config_path = foundry_hub_download(
    "username/my-model",
    filename="config.json"
)

# Download a specific version
model_path = foundry_hub_download(
    "username/my-model",
    revision="v1.0.0"
)

Using the API Client

from foundry_hub import FoundryApi

# Initialize the client
api = FoundryApi(token="your_access_token")

# Or use the FOUNDRY_ACCESS_TOKEN environment variable
api = FoundryApi()

# List models
models = api.list_models(author="username")
for model in models:
    print(f"{model.id}: {model.description}")

# Get model info
model = api.model_info("username/my-model")
print(f"Downloads: {model.downloads}")
print(f"Likes: {model.likes}")

# List repository files
files = api.list_files("username/my-model")
for file in files:
    print(f"{file.path} ({file.size} bytes)")

# Create a new repository
api.create_repo(
    repo_id="username/new-model",
    repo_type="model",
    private=False
)

# Upload a file (large files are automatically handled as multipart)
from foundry_hub import upload_file, upload_folder

upload_file(
    repo_id="username/new-model",
    path_or_fileobj="/local/path/model.safetensors",
    path_in_repo="model.safetensors",
)

# Upload an entire folder
upload_folder(repo_id="username/new-model", folder_path="./my-model-files")

Authentication

Set your Foundry access token:

from foundry_hub import login

# Interactive login (prompts for token input)
login()

# Provide a token directly
login(token="your_access_token")

# Use an environment variable
# export FOUNDRY_ACCESS_TOKEN=your_access_token

Secure Token Storage

By default, tokens are stored securely in the OS keychain:

macOS: Keychain
Linux: Secret Service (libsecret)
Windows: Credential Manager

This feature requires the keyring package, which is included with pip install foundry-hub[cli].

If keyring is unavailable, the token is stored in ~/.cache/foundry/hub/token with restricted permissions (0600) and a warning is displayed.

To explicitly use file-based storage (not recommended):

foundry-hub auth login --insecure

Token lookup priority:

FOUNDRY_ACCESS_TOKEN environment variable (highest priority)
OS keychain
Token file (fallback)

CLI Usage

# Log in
foundry-hub auth login

# Download a model
foundry-hub download username/my-model

# Download a specific file
foundry-hub download username/my-model --filename config.json

# Upload files
foundry-hub upload username/my-model ./local-files/

# Create a new repository
foundry-hub repo create username/new-model --type model

Configuration

Default library paths:

Cache directory: ~/.cache/foundry/hub/
Token storage: OS keychain (default) or ~/.cache/foundry/hub/token (fallback)

You can override settings using environment variables:

export FOUNDRY_HUB_CACHE=~/my-cache/foundry
export FOUNDRY_ACCESS_TOKEN=your_access_token
export FOUNDRY_ENDPOINT=https://your-foundry-instance.example.com

License

Apache License 2.0

Command Palette