# Ai Render Helper CLI integration prompt

Give this file to a coding AI when building a local Windows interface for Ai Render Helper.

## Your role

Build a local interface that invokes the documented Ai Render Helper command-line interface and displays its JSON result. The user may choose PowerShell, Python, Electron, .NET, or another Windows-compatible local UI. Do not build a cloud service, modify Ai Render Helper files, invent commands, or assume unsupported headless media features.

## Windows execution

Run commands from the installed or source `ARH resources` folder:

```powershell
Set-Location -LiteralPath "C:\Path\To\Ai Render Helper\ARH resources"
$env:PYTHONPATH = ".\src"
python -m ai_render_helper commands schema
```

General command shape:

```text
python -m ai_render_helper <section> <action> --parameter value
```

- Use Windows-safe quoted paths when a path contains spaces.
- Command flags use kebab case, for example `--input-path`; the app receives them as `input_path`.
- A flag without a value is interpreted as boolean `true`.
- The process writes one JSON `CommandResult` object to standard output and exits `0` on success or `2` on a command failure.
- Show `message`, `warnings`, `missing_required_parameters`, `next_required_action`, and `output_files` to the user.
- Before using a command, call `commands schema` and treat its output as the live source of truth.

## Required interface behavior

1. Validate every required input before launching a process.
2. Do not expose or request API keys, FTP credentials, or website secrets.
3. Do not make up hidden CLI flags or claim GUI-only functions are headless.
4. Keep paths local to the Windows computer.
5. Render process errors clearly and preserve the returned JSON for troubleshooting.
6. Use `commands schema` to detect future schema changes.

## Supported commands

### Discover the live schema

```text
python -m ai_render_helper commands schema
```

Parameters: none.

Use this at setup time and when diagnosing a command mismatch.

### Settings

```text
python -m ai_render_helper settings get --key <section.key>
python -m ai_render_helper settings set --key <section.key> --value <value>
```

| Parameter | `get` | `set` | Meaning |
| --- | --- | --- | --- |
| `key` | required | required | Setting key, optionally in `section.key` form. |
| `value` | not used | required | New value to store. |

Examples:

```text
python -m ai_render_helper settings get --key settings.comfyui_api_url
python -m ai_render_helper settings set --key encode_merge.source_folder --value "D:\Renders\Clips"
```

### ComfyUI

```text
python -m ai_render_helper comfyui status
python -m ai_render_helper comfyui start
python -m ai_render_helper comfyui scan_resources [--checksum]
```

`status` and `start` use the local ComfyUI API URL and optional launcher configured in Ai Render Helper Settings. `scan_resources` validates the currently selected WAN 2.2 model profile and records the local model/dependency inventory. Use `--checksum` when a full hash scan is required.

### Image Effect

```text
python -m ai_render_helper image_effect apply --input-path <image> --output-path <image> [options]
```

| Parameter | Required | Meaning |
| --- | --- | --- |
| `input_path` | yes | Existing source image file. |
| `output_path` | yes | Output image file path. |
| `saturation` | no | Number; defaults to `0`. |
| `noise` | no | Number; defaults to `0`. |
| `contrast` | no | Number; defaults to `0`. |
| `brightness` | no | Number; defaults to `0`. |
| `bloom` | no | Number; defaults to `0`. |
| `red` | no | Number; defaults to `0`. |
| `green` | no | Number; defaults to `0`. |
| `blue` | no | Number; defaults to `0`. |

Example:

```text
python -m ai_render_helper image_effect apply --input-path "D:\Images\input.png" --output-path "D:\Images\output.png" --saturation 18 --contrast 2 --bloom 8
```

### Cropper

```text
python -m ai_render_helper cropper crop --input-path <image> --output-path <image> --x <pixels> --y <pixels> --width <pixels> --height <pixels>
```

All parameters are required. `x` and `y` are the top-left pixel coordinates. `width` and `height` are pixel dimensions.

Example:

```text
python -m ai_render_helper cropper crop --input-path "D:\Images\source.png" --output-path "D:\Images\crop.png" --x 120 --y 40 --width 800 --height 800
```

### Encode Merge preparation

```text
python -m ai_render_helper encode_merge prepare --source-folder <folder>
```

| Parameter | Required | Meaning |
| --- | --- | --- |
| `source_folder` | yes | Existing folder of source clips. |

This stores the folder for the desktop Encode Merge tab. Do not claim it runs a full headless merge: full merge processing is currently GUI-only.

### Scenario commands

These commands support configured ComfyUI workflows. They are not required for normal public desktop use.

```text
python -m ai_render_helper scenarios load --path <scenario.json>
python -m ai_render_helper scenarios save [--path <scenario.json>] [--name <name>]
python -m ai_render_helper scenarios run --path <scenario.json> [--dry-run]
python -m ai_render_helper scenarios checkpoint --path <checkpoint.json>
```

| Command | Required parameters | Optional parameters |
| --- | --- | --- |
| `scenarios load` | `path` | none |
| `scenarios save` | none | `path`, `name` |
| `scenarios run` | `path` | `dry_run` |
| `scenarios checkpoint` | `path` | none |

Use `--dry-run` without a value to send `true`.
Scenario Maker checkpoints are written after each completed scene and can be read with `scenarios checkpoint`.

## GUI-only capabilities

Do not create fake CLI controls for these functions. Direct users to the Ai Render Helper desktop app:

- Full Encode Merge processing, audio, crossfades, brand intro, and wiggle.
- Duplicate Speed Up, including generated series and Revert.
- Interpolate video processing.
- Trim Clip frame navigation, trimming, and frame export.
- Image Effect folder navigation, previews, presets, and batch buttons.
- Cropper folder navigation and interactive crop selection.
- Encode Brand video processing.
- 3D OpenPose editor, pose management, and map generation.
- Pro license validation and brand-kit creation.

## Result format

Each command returns JSON in this shape:

```json
{
  "success": true,
  "section": "image_effect",
  "action": "apply",
  "message": "Image effect output: D:\\Images\\output.png",
  "missing_required_parameters": [],
  "warnings": [],
  "output_files": ["D:\\Images\\output.png"],
  "updated_settings": {},
  "next_required_action": "",
  "data": {}
}
```

On failure, use `missing_required_parameters` and `next_required_action` to guide the user instead of guessing.

## Build request template

When the user asks for an interface, first ask which supported command they want to expose. Then build a local Windows form that:

1. collects only that command’s documented parameters;
2. validates required paths and numeric fields;
3. invokes the exact command shown in this file;
4. captures stdout and parses the JSON response;
5. displays progress/state honestly without fabricating process progress;
6. shows output paths as clickable local-file actions where the host UI supports them.