curl -fsSL https://raw.githubusercontent.com/zb-ss/hftool/master/install.sh | bash

pip install hftool

hftool setup

# Text-to-Image (Z-Image, SDXL, FLUX)
pip install "hftool[with_t2i]"

# Text-to-Video (HunyuanVideo, CogVideoX, Wan2.2)
pip install "hftool[with_t2v]"

# Text-to-Speech (Bark, MMS-TTS)
pip install "hftool[with_tts]"

# Speech-to-Text (Whisper)
pip install "hftool[with_stt]"

# All features
pip install "hftool[all]"

# Interactive file picker and JSON builder
pip install InquirerPy

# Or for pipx:
pipx runpip hftool install InquirerPy

git clone https://github.com/zb-ss/hftool
cd hftool

# Install PyTorch first (see Quick Install above for your platform)
pip install torch torchvision torchaudio  # or with ROCm/CPU index

# Then install hftool in dev mode
pip install -e ".[dev]"  # Includes pytest

# Install hftool
pipx install hftool[all]

# AMD ROCm - uninstall CUDA version and install ROCm version:
pipx runpip hftool uninstall torch torchvision torchaudio -y
pipx runpip hftool install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.2

# NVIDIA (already installed by default, but to reinstall):
pipx runpip hftool install torch torchvision torchaudio

# CPU only:
pipx runpip hftool uninstall torch torchvision torchaudio -y
pipx runpip hftool install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

curl -fsSL https://raw.githubusercontent.com/zb-ss/hftool/master/install.sh | bash

# With options:
curl -fsSL ... | bash -s -- --platform rocm      # Force platform
curl -fsSL ... | bash -s -- --install-dir /usr/local/bin  # Custom dir

# Install hftool (thin CLI wrapper)
pip install hftool

# Run the setup wizard
hftool docker setup

# Check Docker status
hftool docker status

# Build the image manually
hftool docker build

# Run commands in Docker
hftool docker run -- -t t2i -i "A cat" -o cat.png

# GPU selection (AMD ROCm - uses device passthrough for reliable isolation)
hftool docker run --gpu 1 -- -t t2v -i "A cat" -o cat.mp4      # Use specific GPU
hftool docker run --gpu auto -- -t t2i -i "A cat" -o cat.png   # Auto-select non-display GPU
hftool docker run --gpu 0,1 -- -t t2v -m ltx2 -i "A cat" -o cat.mp4  # Multi-GPU

# Output files auto-open on host after generation completes
# Use --no-open to disable
hftool docker run -- -t t2i -i "A cat" -o cat.png --no-open

# Interactive GPU selection (shown when multiple GPUs detected)
hftool docker run -- -t t2i -i "A cat" -o cat.png
#   Available GPUs:
#     [0] AMD Radeon RX 7900 XTX, 24.0GB (display)
#     [1] AMD Radeon RX 7900 XTX, 24.0GB
#   GPU> 1

# Explicit selection
hftool docker run --gpu 1 -- -t t2v -i "A cat" -o cat.mp4

# Full interactive wizard - guided experience for beginners
hftool -I

# Or specify everything on command line
hftool -t t2i -i "A cat in space" -o cat.png

# Interactive file selection
hftool -t asr -i @ -o transcript.txt

# Preview before running
hftool -t t2i -i "A cat" --dry-run

# Reproducible generation with seed
hftool -t t2i -i "A cat" -o cat.png --seed 42

# Re-run previous command
hftool history --rerun 5

# Install shell completions for tab completion
hftool completion --install

# Create default config with helpful comments
hftool config init

# Or manually create ~/.hftool/config.toml

# View current configuration
hftool config show

# Create default config file
hftool config init

# Edit config in your $EDITOR
hftool config edit

# With config file setting device=cuda and model=z-image-turbo
hftool -t t2i -i "A cat in space" -o cat.png
# Uses cuda device and z-image-turbo from config

# Override config with CLI args
hftool -t t2i -i "A cat" -o cat.png --device cpu -m sdxl
# Uses cpu device and sdxl model (CLI overrides config)

# Pick a WAV file interactively
hftool -t asr -i @ -o transcript.txt

# Select from all files with fuzzy search
hftool -t t2i -i @? -o output.png

# Pick from a specific directory
hftool -t asr -i @/home/user/recordings/ -o transcript.txt

# Use glob pattern to filter
hftool -t asr -i @*.wav -o transcript.txt

# Recent files from history
hftool -t t2i -i @@ -o output.png

pip install InquirerPy
# Or for pipx:
pipx runpip hftool install InquirerPy

# Interactive mode for image-to-image
hftool -t i2i --interactive -o output.png

# Or trigger with @?
hftool -t i2i -i @? -o output.png

# Show recent commands
hftool history

# Show last 20 commands
hftool history -n 20

# Output as JSON
hftool history --json

# Re-run command #5
hftool history --rerun 5

# With confirmation prompt
hftool history --rerun 5
# Shows: Re-running command #5 from 2024-01-15 14:32:15:
#   hftool -t text-to-image -i "A cat in space" -o cat.png --seed 42
# Continue? [Y/n]:

# Clear all history
hftool history --clear

export HFTOOL_HISTORY_FILE=~/custom/path/history.json

# Preview text-to-image generation
hftool -t t2i -i "A cat in space" -o cat.png --dry-run

# Auto-detect shell and install
hftool completion --install

# Show completion script for bash
hftool completion bash

# Install for specific shell
hftool completion zsh --install

# Run all diagnostic checks
hftool doctor

# Output as JSON
hftool doctor --json

# List all models
hftool models

# List models for a specific task
hftool models -t text-to-image
hftool models -t t2i  # (using alias)

# Show only downloaded models
hftool models --downloaded

# Output as JSON
hftool models --json

# Download default model for a task
hftool download -t text-to-image
hftool download -t t2i  # (using alias)

# Download specific model by short name
hftool download -t t2i -m sdxl

# Download by HuggingFace repo_id
hftool download -m openai/whisper-large-v3

# Download all default models for all tasks
hftool download --all

# Re-download (force)
hftool download -t t2i -f

# Resume interrupted download (default)
hftool download -t t2i
# Disable resume
hftool download -t t2i --no-resume

# Show downloaded models and disk usage
hftool status

# Interactive selection (default) - shows numbered list to choose from
hftool clean

# Delete specific model by name
hftool clean -m whisper-large-v3

# Delete multiple models at once
hftool clean -m whisper-large-v3 -m z-image-turbo

# Delete all downloaded models
hftool clean --all

# Skip confirmation prompts
hftool clean --all -y

# Set custom location via environment variable
export HFTOOL_MODELS_DIR=/path/to/models

# Or use one-time
HFTOOL_MODELS_DIR=/mnt/storage hftool -t t2i -i "A cat" -o cat.png

# .env
HFTOOL_MODELS_DIR=/data/models
HFTOOL_AUTO_DOWNLOAD=1
HFTOOL_AUTO_OPEN=0
HFTOOL_DEBUG=0          # Set to 1 to show all warnings

# Option 1: Login with huggingface-cli (recommended)
pip install huggingface_hub
huggingface-cli login
# Follow prompts to enter your token

# Option 2: Set environment variable
export HF_TOKEN=your_token_here

# Option 3: Add to .env file
echo "HF_TOKEN=your_token_here" >> ~/.hftool/.env

# Via environment variable
HFTOOL_DEBUG=1 hftool -t i2i -i '{"image": "photo.jpg", "prompt": "..."}'

# Or in .env file
HFTOOL_DEBUG=1

# Via environment variable
HFTOOL_LOG_FILE=~/.hftool/hftool.log hftool -t i2i ...

# Or in .env file (recommended)
HFTOOL_LOG_FILE=~/.hftool/hftool.log

export HFTOOL_AUTO_DOWNLOAD=1

# Always open (even text files)
hftool -t t2i -i "A cat" -o cat.png --open

# Never open
hftool -t t2i -i "A cat" -o cat.png --no-open

# Or set via environment variable
export HFTOOL_AUTO_OPEN=1    # Always open
export HFTOOL_AUTO_OPEN=0    # Never open

hftool -t <task> -i <input> [-m <model>] [-o <output>] [-- extra_args]

hftool --list-tasks

# Basic usage (uses default model)
hftool -t t2i -i "A cat wearing a space helmet" -o cat_space.png

# With specific model
hftool -t t2i -m Tongyi-MAI/Z-Image-Turbo \
       -i "A photorealistic sunset over mountains" \
       -o sunset.png

# With custom parameters (Z-Image-Turbo uses 9 steps, guidance_scale=0)
hftool -t t2i -m Tongyi-MAI/Z-Image-Turbo \
       -i "A renaissance painting of a robot" \
       -o robot.png \
       -- --num_inference_steps 9 --guidance_scale 0.0 --height 1024 --width 1024

# Basic image editing with Qwen Image Edit (default)
hftool -t i2i \
       -i '{"image": "photo.jpg", "prompt": "turn this into a watercolor painting"}' \
       -o watercolor.png

# Multi-image editing - combine multiple images (Qwen feature)
hftool -t i2i \
       -i '{"image": ["person1.jpg", "person2.jpg"], "prompt": "Both people standing together in a park"}' \
       -o combined.png

# With custom parameters
hftool -t i2i \
       -i '{"image": "portrait.jpg", "prompt": "as a Renaissance painting"}' \
       -o renaissance.png \
       -- --seed 42 --true_cfg_scale 4.0 --num_inference_steps 50

# FLUX.2 Klein - fast multi-reference editing (sub-second generation)
hftool -t i2i -m flux2-klein \
       -i '{"image": "person.jpg", "prompt": "the person from image 1 as an astronaut on Mars"}' \
       -o astronaut.png

# FLUX.2 Klein with multiple reference images
hftool -t i2i -m flux2-klein \
       -i '{"image": ["cat.jpg", "dog.jpg"], "prompt": "the cat from image 1 and dog from image 2 playing together"}' \
       -o pets.png \
       -- --seed 42

# Style transfer with SDXL Refiner (smaller model, faster)
hftool -t i2i -m sdxl-refiner \
       -i '{"image": "landscape.jpg", "prompt": "professional photography, enhanced colors"}' \
       -o enhanced.png \
       -- --strength 0.3

# Use multi-GPU (distributes across available GPUs)
hftool -t i2i -i '{"image": "photo.jpg", "prompt": "..."}' -o out.png --gpu all

# Use CPU offload (slower but works on 16-24GB GPUs)
HFTOOL_CPU_OFFLOAD=1 hftool -t i2i -i '{"image": "photo.jpg", "prompt": "..."}' -o out.png

# Use sequential CPU offload (most memory efficient, slowest)
HFTOOL_CPU_OFFLOAD=2 hftool -t i2i -i '{"image": "photo.jpg", "prompt": "..."}' -o out.png

pip install --upgrade diffusers>=0.36.0
# Or for pipx:
pipx runpip hftool install --upgrade diffusers>=0.36.0

# LTX-2 (fast, high quality - requires diffusers main branch)
hftool -t t2v -m ltx2 -i "A cat playing with a ball in slow motion" -o cat.mp4

# LTX-2 Image-to-Video (animate an image)
hftool -t i2v -m ltx2-i2v \
       -i '{"image": "photo.jpg", "prompt": "The person waves hello"}' \
       -o animated.mp4

# HunyuanVideo-1.5 (480p, ~2.5 second video)
hftool -t t2v -i "A person walking on a beach at sunset" -o beach.mp4

# With specific model and parameters
hftool -t t2v -m hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v \
       -i "A timelapse of clouds moving over a city" \
       -o clouds.mp4 \
       -- --num_frames 61 --num_inference_steps 30

# HunyuanVideo Image-to-Video
hftool -t i2v -m hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_i2v \
       -i '{"image": "photo.jpg", "prompt": "The person waves hello"}' \
       -o animated.mp4

# Basic usage (uses bark-small by default)
hftool -t tts -i "Hello, this is a test of the text to speech system." -o hello.wav

# With full Bark model (higher quality, larger)
hftool -t tts -m suno/bark \
       -i "Welcome to hftool, your command-line AI assistant." \
       -o welcome.wav

# Output as MP3 (requires ffmpeg)
hftool -t tts -i "This will be saved as MP3." -o output.mp3

# Clone the repository
git clone https://github.com/zai-org/GLM-TTS.git
cd GLM-TTS && pip install -r requirements.txt

# Set environment variable
export GLMTTS_PATH=/path/to/GLM-TTS

# Run
hftool -t tts -m zai-org/GLM-TTS -i "你好世界" -o hello_chinese.wav

# Basic transcription
hftool -t asr -i recording.wav -o transcript.txt

# With specific model
hftool -t asr -m openai/whisper-large-v3 -i podcast.mp3 -o transcript.txt

# With timestamps (outputs JSON)
hftool -t asr -i interview.wav -o transcript.json \
       -- --return_timestamps true

# Generate SRT subtitles
hftool -t asr -i video_audio.wav -o subtitles.srt \
       -- --return_timestamps true --format srt

# Basic generation
hftool -t llm -m meta-llama/Llama-3.2-1B-Instruct \
       -i "Explain quantum computing in simple terms:" \
       -o response.txt \
       -- --max_new_tokens 200

# Image Classification
hftool -t image-classification -m google/vit-base-patch16-224 \
       -i photo.jpg -o result.json

# Object Detection
hftool -t object-detection -m facebook/detr-resnet-50 \
       -i street.jpg -o detections.json

# Summarization
hftool -t summarization -m facebook/bart-large-cnn \
       -i article.txt -o summary.txt

# Translation
hftool -t translation -m Helsinki-NLP/opus-mt-en-de \
       -i "Hello, how are you?" -o translation.txt

hftool -t t2i -i "A cat" -o cat.png \
       -- --num_inference_steps 20 --guidance_scale 7.5 --seed 42

# If using pipx:
pipx runpip hftool uninstall torch torchvision torchaudio -y
pipx runpip hftool install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.2

# If using pip:
pip uninstall torch torchvision torchaudio -y
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.2

# Use Ollama's bundled ROCm libraries
HFTOOL_ROCM_PATH=/usr/local/lib/ollama/rocm

# Set your GPU architecture (required for AMD GPUs)
# RDNA3: gfx1100 (RX 7900 XTX/XT), gfx1101 (RX 7800/7700), gfx1102 (RX 7600)
# RDNA2: gfx1030 (RX 6900/6800), gfx1031 (RX 6700), gfx1032 (RX 6600)
HSA_OVERRIDE_GFX_VERSION=11.0.0

hftool -t t2i -i "test" -o test.png -v
# Should show "Using device: cuda" or similar

hftool doctor
# Shows:
#   GPU 0: AMD Radeon RX 7900 XTX [DISPLAY]
#   GPU 1: AMD Radeon RX 7900 XTX <- recommended

# Auto-select compute GPU (avoids display GPU)
hftool -t t2v -i "A cat running" -o cat.mp4 --gpu auto

# Use specific GPU
hftool -t t2v -i "A cat running" -o cat.mp4 --gpu 1

# Use all GPUs for large models like LTX-2 or HunyuanVideo
hftool -t t2v -m ltx2 -i "A cat running" -o cat.mp4 --gpu all

# Docker with specific GPU
hftool docker run --gpu 1 -- -t t2v -i "A cat" -o cat.mp4

# Environment variable (useful in .env file)
HFTOOL_GPU=1 hftool -t t2v -i "A cat" -o cat.mp4

# Force multi-GPU mode via environment variable
HFTOOL_MULTI_GPU=1 hftool -t t2v -m ltx2 -i "A cat" -o cat.mp4

pip install -e ".[dev]"
pytest tests/ -v