runninghub-cli 0.1.0__tar.gz

runninghub_cli-0.1.0/HANDOFF.md

@@ -0,0 +1,290 @@
+# RunningHub CLI (`rh`) — AI Handoff Document
+
+> **For:** Next AI agent or developer taking over this project  
+> **Written by:** Claude (claude-opus-4-5) after completing initial implementation + live API validation  
+> **Date:** 2026-04-12  
+> **Status:** v0.1.0 — fully working, all smoke tests passed
+
+---
+
+## 1. What Was Built and Why
+
+`rh` is an agent-native CLI for [RunningHub](https://www.runninghub.cn) — a cloud ComfyUI platform.
+
+**Origin:** Two existing projects existed but were not usable by AI agents:
+- `OpenClaw_RH_Skills/` — Python scripts covering 209 standard model endpoints, written as a conversational persona tool (OpenClaw), not a CLI
+- `RunningHub-AI-Client/` — React/TypeScript/Tauri desktop GUI with clean `services/api.ts` layer
+
+This CLI distils both into a single `rh` command following CLI-Anything methodology: every command prints JSON to stdout, errors go to stderr with exit code 1.
+
+---
+
+## 2. Critical Architecture: Two Completely Separate API Systems
+
+> **This is the most important thing to understand.** The two API systems have different auth, different upload endpoints, different response shapes, and different polling protocols. They cannot be mixed.
+
+### System A — Standard Model API
+
+| Property | Value |
+|----------|-------|
+| Purpose | 209 pre-built model endpoints (image/video/audio/3D) |
+| Base URL | `https://www.runninghub.cn/openapi/v2` |
+| Auth | `Authorization: Bearer <apiKey>` header |
+| Run endpoint | `POST /openapi/v2/{model}/{task}` |
+| Poll endpoint | `POST /openapi/v2/query` with body `{"taskId":"..."}` |
+| Poll response | `{"taskId":"..","status":"SUCCESS|FAILED|QUEUED|RUNNING","results":[...],"errorCode":"","errorMessage":""}` |
+| Upload endpoint | `POST /openapi/v2/media/upload/binary` (multipart, Bearer auth) |
+| Upload returns | `{"code":0,"data":{"download_url":"https://cdn..."}}` |
+| Key type required | **SHARED / enterprise key only** (NORMAL keys return code=1014) |
+| Key field in poll | Bearer header |
+
+**IMPORTANT:** Standard model run response is NOT a `{"code":0,"data":{}}` envelope. It directly returns `{"taskId":"..","errorCode":"..","errorMessage":"..","results":null}`. The `errorCode` field signals errors (non-empty and non-"0" = error).
+
+### System B — AI Apps API
+
+| Property | Value |
+|----------|-------|
+| Purpose | Custom ComfyUI workflow apps (user-created) |
+| Auth | `apiKey` field **inside the JSON body** (no Authorization header) |
+| Run endpoint | `POST /task/openapi/ai-app/run` with `{"webappId":"..","apiKey":"..","nodeInfoList":[...]}` |
+| Poll endpoint | `POST /task/openapi/outputs` with body `{"apiKey":"..","taskId":"..."}` |
+| Poll response | `{"code":804,...}` = running; `{"code":0,"data":[{fileUrl,fileType},...]}` = done |
+| Upload endpoint | `POST /task/openapi/upload` (multipart, `apiKey` + `fileType` in form fields) |
+| Upload returns | `{"code":0,"data":{"fileName":"abc.png"}}` — use `fileName` as fieldValue |
+| Key type required | Works with NORMAL key |
+| App list | `POST /api/webapp/list` (no auth, public catalog) |
+| App info | `GET /api/webapp/apiCallDemo?apiKey=...&webappId=...` |
+
+**IMPORTANT:** AI Apps poll `data` is a **list** directly, not `{"outputs":[...]}`. `code=804` means still running; loop until `code=0`.
+
+---
+
+## 3. Project Structure
+
+```
+runninghub-cli/
+├── rh/
+│   ├── __init__.py          # version = "0.1.0"
+│   ├── cli.py               # Click entry point, registers 4 command groups
+│   ├── client.py            # ALL HTTP logic — the most critical file
+│   ├── catalog.py           # Loads data/capabilities.json; unwraps {"endpoints":[...]} wrapper
+│   ├── output.py            # JSON stdout + stderr progress dots
+│   └── commands/
+│       ├── account.py       # rh account status
+│       ├── model.py         # rh model list/info/run/auto
+│       ├── app.py           # rh app list/info/run/batch
+│       └── task.py          # rh task status/outputs
+├── data/
+│   └── capabilities.json    # 209 endpoints, shape: {"endpoints":[...],"total":209,"version":"..."}
+├── tests/
+│   ├── test_catalog.py      # 8 tests
+│   └── test_cli.py          # 9 tests — 17 total, all passing
+├── setup.py                 # entry_points: rh=rh.cli:main
+├── SKILL.md                 # Agent discovery — command reference and JSON schemas
+└── HANDOFF.md               # ← this file
+```
+
+---
+
+## 4. Key Implementation Details in `client.py`
+
+### API Key Resolution (priority order)
+```python
+def _resolve_api_key(api_key=None):
+    1. explicit --api-key argument
+    2. RH_API_KEY environment variable       ← recommended
+    3. ~/.rh/config.json → {"apiKey": "..."}
+    → raises RunningHubError("auth_missing", ...) if none found
+```
+
+### File Upload Logic
+Two separate upload functions — **never mix them**:
+- `_upload_file_for_model(api_key, path)` → Standard API → returns CDN `download_url` (https://...)
+- `_upload_file_for_app(api_key, path)` → AI Apps API → returns `fileName` (short string)
+
+For standard model, small images can be base64-encoded inline (`data:image/png;base64,...`).
+Videos and files ≥5 MB are always uploaded to CDN first (threshold: `FILE_UPLOAD_THRESHOLD_MB = 5`).
+
+### `_resolve_key()` — The `--image` → `imageUrls` Problem
+CLI accepts `--image`, `--video`, `--audio` as convenience flags, but the actual endpoint schema parameter key may be `imageUrls`, `imageUrl`, `videoInput`, etc.
+
+The function in `run_model()` builds a `media_type_to_key` map from the catalog schema and remaps CLI names to actual keys:
+```python
+# Example: endpoint uses {"key":"imageUrls","type":"IMAGE","multiple":true}
+# CLI: --image photo.jpg  → resolves to {"imageUrls": ["https://cdn.../photo.jpg"]}
+```
+Also handles `multiple: true` params by wrapping single values in a list.
+
+### Polling Timeouts
+- `MAX_POLL_SECONDS = 1200` (20 minutes)
+- `POLL_INTERVAL = 5` seconds
+- Both pollers tolerate up to 5 consecutive HTTP errors before giving up
+
+---
+
+## 5. `capabilities.json` — Catalog Format
+
+```json
+{
+  "endpoints": [
+    {
+      "endpoint": "rhart-image-n-pro/text-to-image",
+      "name_cn": "...",
+      "name_en": "...",
+      "task": "text-to-image",
+      "output_type": "image",
+      "popularity": 1,
+      "tags": ["official"],
+      "params": [
+        {"key": "prompt", "type": "STRING", "required": true},
+        {"key": "imageUrls", "type": "IMAGE", "required": false, "multiple": true, "maxSizeMB": 10},
+        {"key": "aspectRatio", "type": "LIST", "required": false, "options": ["1:1","16:9"], "default": "1:1"}
+      ]
+    }
+  ],
+  "total": 209,
+  "version": "..."
+}
+```
+
+`catalog.py` must unwrap the `{"endpoints":[...]}` wrapper — do NOT pass the raw dict to list functions.
+
+---
+
+## 6. Known Catalog Validity Issues
+
+**Not all 209 catalog entries are live.** Some return `code=1001 "Invalid URL"` from the API.
+
+Confirmed WORKING endpoints (tested 2026-04-12):
+- `rhart-image-n-pro/text-to-image` ✅
+- `rhart-video-v3.1-fast/text-to-video` ✅ (103s, SHARED key)
+- `rhart-video-v3.1-fast/image-to-video` ✅ (129s, SHARED key)
+- `rhart-video-v3.1-fast-official/video-extend` ✅ (119s, SHARED key, "video-to-video")
+- AI Apps (any `webappId` from `rh app list`) ✅ (NORMAL key works)
+
+Confirmed BROKEN endpoints:
+- `rhart-video-s/text-to-video` → code=1001 "Invalid URL"
+
+When an endpoint returns 1001, try the next endpoint for the same task type (`rh model list --task <X>` and pick one with low popularity number).
+
+---
+
+## 7. Live Test Results Summary
+
+| Test | Mode | Key Type | Result | Time |
+|------|------|----------|--------|------|
+| `rh account status` | Standard | NORMAL | ✅ coins balance | <1s |
+| `rh app list` | AI Apps | — | ✅ 20 apps | <1s |
+| `rh app run` (全能图片2.0) | AI Apps | NORMAL | ✅ `test_robot_cat.png` | ~30s |
+| `rh model run rhart-video-v3.1-fast/text-to-video` | Standard | SHARED | ✅ `test_t2v.mp4` | 103s |
+| `rh model run rhart-video-v3.1-fast/image-to-video` | Standard | SHARED | ✅ `test_i2v.mp4` | 129s |
+| `rh model run rhart-video-v3.1-fast-official/video-extend` | Standard | SHARED | ✅ `test_v2v.mp4` | 119s |
+| `pytest tests/` | — | — | ✅ 17/17 | 0.03s |
+
+---
+
+## 8. API Response Field Mapping Gotchas
+
+These field names differ from what you might assume — all were discovered by live testing:
+
+| Context | Expected | Actual |
+|---------|----------|--------|
+| App list record ID | `webappId` | `id` |
+| App list record name | `webappName` | `name` |
+| App list description | `description` | `intro` |
+| App info node list | `nodeList` or `nodes` | `nodeInfoList` |
+| App info English desc | `description` | `descriptionEn` |
+| Standard model error | `code`, `message` | `errorCode`, `errorMessage` |
+| Standard model results | `data.outputs` | `results` (top-level array) |
+| AI Apps outputs | `data.outputs` | `data` is the list itself |
+| Standard upload URL | `/task/openapi/upload` | `/openapi/v2/media/upload/binary` |
+
+---
+
+## 9. Security
+
+- **Zero API keys hardcoded** anywhere in `rh/` source code
+- Keys only come from: env var `RH_API_KEY`, `--api-key` flag, or `~/.rh/config.json`
+- `.claude/settings.local.json` was cleaned after testing — now uses wildcard rules only
+
+**For new environments:**
+```bash
+# Option A — env var (recommended)
+export RH_API_KEY=your_key_here
+
+# Option B — config file
+mkdir -p ~/.rh && echo '{"apiKey":"your_key_here"}' > ~/.rh/config.json
+```
+
+---
+
+## 10. Installation
+
+```bash
+cd runninghub-cli
+pip install -e .        # dev install, editable
+# OR
+pip install .           # production install
+
+rh --help               # verify
+```
+
+Requires Python ≥ 3.8. Only external dependency: `click>=8.0`.
+
+---
+
+## 11. Running Tests
+
+```bash
+cd runninghub-cli
+python -m pytest tests/ -q
+# Expected: 17 passed in ~0.03s (no network calls, all mocked/unit)
+```
+
+---
+
+## 12. Suggested Next Steps
+
+### High Priority
+1. **`rh model auto` endpoint validation** — `auto` picks by popularity rank, but some top-ranked endpoints return 1001. Add live probe/fallback: try the endpoint, if 1001 try next one in ranked list.
+2. **`~/.rh/config.json` init command** — `rh config set-key YOUR_KEY` to avoid users manually writing JSON.
+3. **`rh model list` live filter** — currently filters only from catalog (static). Add `--live` flag that probes each endpoint with a dry run.
+
+### Medium Priority
+4. **Streaming progress** — currently just prints dots to stderr. A `--progress` flag with JSON-lines progress events would help agents track long video jobs.
+5. **Batch mode for `rh model`** — `rh model batch` analogous to `rh app batch`, for running the same model on many inputs from CSV.
+6. **Update capabilities.json** — the catalog is a static snapshot. A `rh catalog update` command could fetch the live list from RunningHub and regenerate it.
+
+### Low Priority
+7. **Windows path handling** — tested on Windows; `Path()` objects work, but `~/.rh/` resolves to `C:\Users\<user>\.rh\`. Works correctly.
+8. **Async polling** — currently blocking. For batch use, `asyncio` would allow concurrent polls.
+9. **`rh app batch` CSV encoding** — currently assumes UTF-8. Add `--encoding` flag.
+
+---
+
+## 13. Important URLs
+
+| Resource | URL |
+|----------|-----|
+| RunningHub platform | https://www.runninghub.cn |
+| API key page | https://www.runninghub.cn/enterprise-api/sharedApi |
+| Official API docs | https://www.runninghub.cn/runninghub-api-doc-cn/ |
+| Pricing | https://www.runninghub.cn/third-party-fees |
+| Membership tiers | https://www.runninghub.cn/vip-rights/2 |
+| API Reference (agent-readable) | `../RUNNINGHUB_API_REFERENCE.md` (in parent dir) |
+
+---
+
+## 14. Key Type Reference
+
+| API | NORMAL key | SHARED/enterprise key |
+|-----|-----------|----------------------|
+| AI Apps (`rh app *`) | ✅ works | ✅ works |
+| Standard Models (`rh model *`) | ❌ code=1014 | ✅ required |
+| Account status (`rh account *`) | ✅ works | ✅ works |
+
+To get a SHARED key: RunningHub enterprise plan → https://www.runninghub.cn/enterprise-api/sharedApi
+
+---
+
+*End of handoff. The codebase is clean, tested, and ready for Git push.*

runninghub_cli-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include SKILL.md
+include HANDOFF.md
+include data/capabilities.json

runninghub_cli-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+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

runninghub_cli-0.1.0/SKILL.md

@@ -0,0 +1,184 @@
+# 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