Metadata-Version: 2.4
Name: runninghub-cli
Version: 0.1.0
Summary: Agent-native CLI for RunningHub AI platform (image/video/audio/3D generation)
Home-page: https://cnb.cool/101ya/runninghub-cli
Author: 101ya
License: MIT
Keywords: runninghub ai image video generation comfyui cli agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# RunningHub CLI (`rh`) — Agent Skill

## What This Tool Does

`rh` is a command-line interface for the [RunningHub AI platform](https://www.runninghub.cn) — a cloud ComfyUI service with 209+ built-in AI model endpoints and support for custom ComfyUI workflow apps.

Use `rh` to:
- Generate images, videos, audio, and 3D models from text/image prompts
- Browse and run custom ComfyUI AI App workflows
- Check task status and download outputs
- Monitor account balance

## Setup

```bash
export RH_API_KEY=your_runninghub_api_key
```

Or pass `--api-key KEY` to any command.

Get a key at: https://www.runninghub.cn/enterprise-api/sharedApi

## Command Reference

### Account

```bash
rh account status
# → {"remainCoins": "150.0", "currentTaskCounts": "0", "apiType": "coins"}
```

### Built-in Models (`rh model`)

For quick AI generation using RunningHub's 209 pre-built models.

```bash
# List available models
rh model list --type image
rh model list --task text-to-image --top 5
rh model list --type video

# Get parameter schema for an endpoint
rh model info rhart-image-n-pro/text-to-image

# Auto-select best model for a task (recommended for agents)
rh model auto --task text-to-image --prompt "a sunset over mountains" --output out.png
rh model auto --task image-to-video --image input.jpg --output out.mp4
rh model auto --task text-to-speech --prompt "Hello world" --output out.mp3
rh model auto --task text-to-3d --prompt "a ceramic teapot" --output model.glb

# Run a specific endpoint
rh model run rhart-image-n-pro/text-to-image --prompt "anime cat" --output cat.png
rh model run kling-video-o3-pro/image-to-video --image photo.jpg --output video.mp4
```

**Available task types:**
- `text-to-image`, `image-to-image`, `image-upscale`
- `text-to-video`, `image-to-video`, `reference-to-video`, `start-end-to-video`
- `text-to-speech`, `music-generation`, `voice-clone`
- `text-to-3d`, `image-to-3d`, `multi-image-to-3d`

### Custom AI Apps (`rh app`)

For custom ComfyUI workflows. Each app has a `webappId` and modifiable input nodes.

```bash
# Browse public apps
rh app list --search "anime portrait" --sort RECOMMEND
rh app list --sort HOTTEST --size 10

# Inspect an app's input schema before running
rh app info 1234567890
# → {"webappId": "...", "name": "...", "nodes": [{"nodeId": "6", "fieldName": "prompt", "fieldType": "STRING", ...}]}

# Run an app
rh app run 1234567890 \
  --node "6:prompt=a samurai cat warrior" \
  --output result.mp4

# Run with a file input
rh app run 1234567890 \
  --node "6:prompt=enhance this portrait" \
  --file "10:image=/path/to/photo.jpg" \
  --output enhanced.png

# Batch run from CSV
rh app batch 1234567890 --input params.csv --concurrency 3 --output-dir ./results/
```

**Batch CSV format:**
```csv
6:prompt,10:image
"a ninja dog",/path/to/dog.jpg
"a robot cat",/path/to/cat.jpg
```

### Task Management

```bash
# Check status of a task
rh task status abc123

# Get outputs for a completed task
rh task outputs abc123 --output result.png
```

## JSON Output Schema

All commands output JSON. Agents should parse stdout directly.

**`rh model auto` / `rh model run` success:**
```json
{
  "taskId": "abc123",
  "status": "SUCCESS",
  "outputs": [{"fileUrl": "https://cdn.runninghub.cn/...", "fileType": "image/png"}],
  "cost": {"duration_s": 8},
  "savedTo": "/path/to/out.png",
  "selectedEndpoint": "rhart-image-n-pro/text-to-image"
}
```

**`rh app run` success:**
```json
{
  "taskId": "xyz789",
  "status": "SUCCESS",
  "outputs": [{"fileUrl": "https://...", "fileType": "video/mp4"}],
  "savedTo": "/path/to/result.mp4"
}
```

**Errors (exit code 1):**
```json
{"error": "auth_failed", "message": "Invalid API key or unauthorized"}
{"error": "insufficient_balance", "message": "Account balance is 0"}
{"error": "task_failed", "message": "Task failed: ..."}
{"error": "timeout", "message": "Task exceeded 20 minute timeout"}
```

## Typical Agent Workflows

### 1. Generate an image

```bash
rh model auto --task text-to-image --prompt "a photorealistic sunset over the ocean" --output sunset.png
```

### 2. Generate a video from an image

```bash
rh model auto --task image-to-video --image portrait.jpg --output animation.mp4
```

### 3. Discover and run a custom ComfyUI app

```bash
# Step 1: find apps
rh app list --search "anime portrait" --size 5

# Step 2: check the app's inputs
rh app info <webappId>

# Step 3: run it
rh app run <webappId> --node "6:prompt=anime warrior" --file "10:image=photo.jpg" --output result.png
```

### 4. Check balance before running

```bash
rh account status | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['remainCoins'])"
```

## Error Handling

- All errors produce JSON with an `error` key and exit code 1
- Progress is written to **stderr** (polling dots); final JSON is on **stdout**
- Separate stderr from stdout: `rh model auto ... 2>/dev/null`

## Notes

- Tasks may take 5 seconds to 20 minutes depending on the model
- Video generation is slower than image generation
- The `--instance plus` flag (for `rh app run`) uses premium compute
