---
id: hf-gradio
version: "0.4.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# hf-gradio — An extension of the Hugging Face CLI for interacting with Gradio Spaces and Apps.

License: permissive · Maintenance: active · Downloads: 3.9M/mo

## What it is and what it does

hf-gradio is a command-line interface for interacting with Gradio applications running on Hugging Face Spaces. It provides two main commands: `info` returns a JSON schema describing all available endpoints, their parameters (with types, defaults, and requirements), and return values; `predict` sends JSON payloads to those endpoints and returns results. The tool handles file uploads by requiring a specific metadata structure and supports authentication via HF tokens for private spaces. It's designed to be agent-friendly, with schemas structured so that AI coding agents can discover APIs and construct valid payloads programmatically.

The package depends on gradio-client for API communication and typer for CLI argument parsing. It requires Python 3.10 or later. The tool works both as a standalone CLI command and integrates with the Gradio package when installed, exposing `gradio info` and `gradio predict` subcommands.

Use it for:

- Discover available endpoints and parameter schemas for a Gradio Space before writing client code.
- Send predictions to image generation or data processing Gradio apps from shell scripts or CI/CD pipelines.
- Enable AI agents to autonomously discover and call Gradio APIs by parsing the JSON schema output.
- Upload files to Gradio endpoints that accept file inputs, with automatic metadata formatting.
- Access private Gradio Spaces using HF authentication tokens from the command line.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A CLI tool for discovering endpoints and sending predictions to Gradio apps hosted on Hugging Face Spaces, with built-in support for file uploads and private spaces.

Yes, if you need to interact with Gradio Spaces from the command line or want to integrate them into scripts and agent workflows. The tool is actively maintained, has low install friction, and carries no security vulnerabilities. The MIT license poses no restrictions. However, the project is very new (first release in March 2026) with minimal community adoption (3 GitHub stars), so expect possible API changes and limited third-party documentation.

## Install

pip install hf-gradio
uv add hf-gradio
poetry add hf-gradio

## Installing hf-gradio

Before you install: Low friction install with only two runtime dependencies (gradio-client and typer). Active maintenance as of 2026-04-21 with recent releases, though the project is young (first release 2026-03-19) and has minimal GitHub presence (3 stars).

License in practice: MIT license permits unrestricted use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart:

pip install hf-gradio

# Discover endpoints
hf-gradio info gradio/calculator

# Send a prediction
hf-gradio predict gradio/calculator /predict '{"num1": 5, "operation": "multiply", "num2": 3}'

Requires Python 3.10 or later. The target Gradio Space must be publicly accessible or you must provide a valid HF token via --token for private spaces.

Verify before relying:

- Whether the tool works reliably with all Gradio app types or has known limitations with certain component types.
- Performance characteristics when calling endpoints with large file uploads or long-running predictions.
- Whether error handling and retry logic are documented for network failures or rate limiting.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 3.9M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

gradio cli predict, hugging face spaces api client, gradio endpoint discovery, send predictions to gradio apps, gradio space command line, ai agent gradio integration, gradio api schema discovery, gradio-integration, cli-tool, ai-agent-friendly

[View on SkillFed](https://skillfed.io/packages/hf-gradio) · [View on PyPI](https://pypi.org/project/hf-gradio/)