---
title: hf-save
emoji: 💾
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
---

# hf-save

An ultra-fast, zero-overhead developer tool to save work artifacts from ephemeral GPU instances (RunPod, Vast.ai, Lambda Labs) and restore them later. 

Uses a **Hugging Face Docker Space** with a **Dataset Storage Mount** at `/data` as the backend and a **Single-binary Go CLI** on the client side.


---

## Deploying the Backend Space

1. Create a new Space on [Hugging Face](https://huggingface.co/spaces).
2. Set the SDK to **Docker** (Blank template).
3. **Set up Persistent Storage / Dataset Mount**:
   * Mount a dataset repository at `/data` inside your Space configuration settings.
4. **Set environment variable**:
   * In your Space's settings, add a new Secret variable: `HF_SAVE_API_KEY` (e.g. `my-super-secret-key-123`). This will authenticate client-side uploads.
5. Clone your space repository locally, copy the repository files (`main.go`, `cli/`, `Dockerfile`, `go.mod`), commit and push to the Space repo. Hugging Face will automatically compile the server and build the CLI binaries for Linux, macOS, and Windows.

---

## Client Installation

To install the client binary on any GPU instance or development machine, run the appropriate command. Replace `your-space-name.hf.space` with your actual Hugging Face Space hostname.

### Linux:
```bash
curl -fsSL "https://your-space-name.hf.space/init?platform=linux&token=YOUR_API_KEY" | bash
```

### Windows (PowerShell):
```powershell
irm "https://your-space-name.hf.space/init?platform=windows&token=YOUR_API_KEY" | iex
```

### macOS:
```bash
curl -fsSL "https://your-space-name.hf.space/init?platform=mac&token=YOUR_API_KEY" | bash
```

*Note: If you omit the `&token=YOUR_API_KEY` parameter from the URL, the installer will interactively prompt you to enter the API Key during setup.*

---

## CLI Usage Guide

Once installed, use the CLI commands to backup and restore files.

### 1. Saving Directories
To backup folders at the end of a session:
```bash
# Save a single directory
hf-save outputs

# Save multiple directories
hf-save outputs logs checkpoints
```
This scans files, filters out binary/bloat directories (like `.git`, `__pycache__`, `venv`), and streams them directly to `/data/{YYYY-MM-DD}/{HH-MM-SS}_{name}` on your backend.

### 2. Listing Backups
List all backup dates:
```bash
hf-list
```

List individual snapshots for a specific date:
```bash
hf-list 2026-06-15
```

### 3. Restoring Backups
To restore the **latest** backup of a specific folder name automatically:
```bash
hf-mount outputs
```

To restore a **specific** timestamped backup run:
```bash
hf-mount 2026-06-15 16-35-20_outputs
```
This downloads the files and reconstructs the folders inside your current working directory.