name: hfskill description: Comprehensive toolkit for interacting with Hugging Face Spaces. Use this skill when working with Hugging Face Spaces - listing spaces, retrieving space information, managing space runtime (restart/pause), checking space status, or any other Space-related operations. Requires Hugging Face access token stored in HF_TOKEN or HUGGINGFACE_TOKEN environment variable for write operations.

Hugging Face Spaces Skill

Overview

This skill provides comprehensive operations for managing and interacting with Hugging Face Spaces. It enables listing, querying, and controlling Spaces through a Python-based interface that wraps the Hugging Face Hub API.

When to Use This Skill

Use this skill whenever working with Hugging Face Spaces, including:

• Listing or searching for Spaces by author or keyword
• Retrieving detailed information about a specific Space
• Managing Space runtime (restart, pause)
• Checking Space status and hardware configuration
• Listing all Spaces owned by a user

Authentication Setup

Most Space operations require a Hugging Face access token. Configure authentication by:

1. Environment Variable (Recommended): Set HF_TOKEN or HUGGINGFACE_TOKEN in the environment

   export HF_TOKEN="hf_your_token_here"
   

2. Command-line Parameter: Pass --token to the script

   python3 scripts/space_operations.py --token "hf_your_token_here" <command>
   

Token Requirements:

• Read operations (list, info, runtime): Token optional for public Spaces
• Write operations (restart, pause): Token required with write permissions

Core Operations

1. List Spaces

List and search for Hugging Face Spaces with optional filtering.

Usage:

python3 scripts/space_operations.py list [--author USERNAME] [--search TERM] [--limit N]

Examples:

• List recent Spaces: python3 scripts/space_operations.py list --limit 10
• List Spaces by author: python3 scripts/space_operations.py list --author stabilityai
• Search Spaces: python3 scripts/space_operations.py list --search "chatbot"

Output: JSON array of Space objects with id, author, SDK, likes, and runtime information.

2. Get Space Information

Retrieve detailed information about a specific Space.

Usage:

python3 scripts/space_operations.py info <space_id>

Example:

python3 scripts/space_operations.py info stabilityai/stable-diffusion

Output: JSON object with Space metadata including:

• Space ID and author
• SDK type and version
• Runtime state and hardware
• Privacy status and likes
• Last modified timestamp

3. Restart Space

Restart a Space to apply changes or recover from errors.

Usage:

python3 scripts/space_operations.py restart <space_id>

Example:

python3 scripts/space_operations.py restart myusername/my-space

Requirements:

• Valid access token with write permissions
• Ownership or write access to the Space

4. Pause Space

Pause a Space to conserve compute resources when not in use.

Usage:

python3 scripts/space_operations.py pause <space_id>

Example:

python3 scripts/space_operations.py pause myusername/my-space

Requirements:

• Valid access token with write permissions
• Ownership or write access to the Space

5. Get Space Runtime

Retrieve real-time runtime information about a Space's current state.

Usage:

python3 scripts/space_operations.py runtime <space_id>

Example:

python3 scripts/space_operations.py runtime stabilityai/stable-diffusion

Output: JSON object with runtime details including stage, hardware, and sleep configuration.

6. List User Spaces

List all Spaces owned by a specific user.

Usage:

python3 scripts/space_operations.py user <username>

Example:

python3 scripts/space_operations.py user stabilityai

Output: JSON array of all Spaces for the specified user.

Space ID Format

All Spaces are identified using the format: username/space-name

Examples:

• stabilityai/stable-diffusion
• openai/whisper
• meta-llama/llama-2-chat

Always use the full Space ID when referencing a specific Space.

Common Workflow Examples

Example 1: Find and Restart a Space

# List user's Spaces
python3 scripts/space_operations.py user myusername

# Check Space status
python3 scripts/space_operations.py runtime myusername/my-space

# Restart if needed
python3 scripts/space_operations.py restart myusername/my-space

Example 2: Search for Popular Spaces

# Search for chatbot Spaces
python3 scripts/space_operations.py list --search "chatbot" --limit 20

# Get detailed info about interesting Space
python3 scripts/space_operations.py info username/interesting-space

Example 3: Monitor Space Status

# Get current runtime information
python3 scripts/space_operations.py runtime myusername/my-space

# Get full Space details
python3 scripts/space_operations.py info myusername/my-space

Error Handling

Common errors and solutions:

• "No HF_TOKEN found": Set the environment variable or pass --token
• 401 Unauthorized: Invalid token or token expired
• 403 Forbidden: Token lacks write permissions or you don't own the Space
• 404 Not Found: Space doesn't exist or is private without proper access
• 429 Too Many Requests: Rate limit exceeded, wait before retrying

Dependencies

This skill requires the huggingface_hub Python package:

pip install huggingface_hub

Verify installation before using the skill. If the package is missing, install it automatically or guide the user to install it.

Reference Documentation

For detailed information about Space states, hardware options, and API specifics, refer to references/spaces_reference.md.

Resources

scripts/

• space_operations.py: Main executable script for all Space operations

references/

• spaces_reference.md: Comprehensive reference documentation for Hugging Face Spaces API, runtime states, hardware options, and best practices