---
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
   ```bash
   export HF_TOKEN="hf_your_token_here"
   ```

2. **Command-line Parameter**: Pass `--token` to the script
   ```bash
   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:**
```bash
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:**
```bash
python3 scripts/space_operations.py info <space_id>
```

**Example:**
```bash
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:**
```bash
python3 scripts/space_operations.py restart <space_id>
```

**Example:**
```bash
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:**
```bash
python3 scripts/space_operations.py pause <space_id>
```

**Example:**
```bash
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:**
```bash
python3 scripts/space_operations.py runtime <space_id>
```

**Example:**
```bash
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:**
```bash
python3 scripts/space_operations.py user <username>
```

**Example:**
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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:

```bash
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