> ## Documentation Index
> Fetch the complete documentation index at: https://mulerouter.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# mulerouter run

> Invoke a model endpoint and wait for the result

`run` is the workhorse command. It submits a generation task to the configured
site and — by default — polls until the task completes, then prints the result
URLs.

## Synopsis

```bash theme={null}
mulerouter run <endpoint> [--param value ...] [options]
```

## Endpoint identifier

Same as [`mulerouter params`](/docs/cli/commands/params):

| Form                          | Behavior                                              |
| ----------------------------- | ----------------------------------------------------- |
| `<provider>/<model>`          | Auto-resolves the action if the model has exactly one |
| `<provider>/<model>/<action>` | Explicit action (`generation`, `edit`, ...)           |

## Model parameters

Pass model parameters as flags using kebab-case versions of the parameter
names. Both `--key value` and `--key=value` syntax are accepted.

```bash theme={null}
mulerouter run alibaba/wan2.6-t2v \
  --prompt "A cat walking through a garden" \
  --duration 10 \
  --size "1280*720"
```

The CLI validates and coerces values based on the parameter's type:

| Type      | Accepted CLI value                                                           |
| --------- | ---------------------------------------------------------------------------- |
| `string`  | Any value                                                                    |
| `integer` | Parsed with `Number.parseInt`. Invalid values throw.                         |
| `number`  | Parsed with `Number.parseFloat`. Invalid values throw.                       |
| `boolean` | `true` or `false`, or the bare flag itself (e.g. `--audio` ≡ `--audio true`) |
| `array`   | Must be a valid JSON array string, e.g. `--images '["https://..."]'`         |

If a parameter declares an `enum`, the supplied value must match (use
`mulerouter params <endpoint>` to see allowed values).

Missing required parameters and empty strings for required string parameters
produce a friendly error before any HTTP call is made.

## Common options

| Option                | Default | Description                                                        |
| --------------------- | ------- | ------------------------------------------------------------------ |
| `--api-key <key>`     | env     | Override API key                                                   |
| `--base-url <url>`    | env     | Override base URL                                                  |
| `--site <site>`       | env     | Override site filter for the request                               |
| `--no-wait`           | —       | Submit the task and exit immediately (don't poll)                  |
| `--poll-interval <s>` | `20`    | Polling interval in seconds                                        |
| `--max-wait <s>`      | `900`   | Maximum wait time in seconds (15 min)                              |
| `--quiet`             | —       | Suppress progress lines on stderr                                  |
| `--json`              | —       | Machine-readable output on stdout                                  |
| `--extra <KEY=VALUE>` | —       | Inject an extra parameter not declared in the catalog. Repeatable. |

`--extra` values are parsed as JSON when possible — `--extra count=3` sets the
number `3`, while `--extra label=draft` sets the string `"draft"`. You can also
pass undeclared parameters directly as `--anything value`; the CLI forwards
unknown flags in the request body.

## Local image inputs

Any parameter whose name implies an image (`image`, `images`, `first_frame`,
`last_frame`, `mask`, ...) accepts:

* An **HTTPS URL** — passed through unchanged.
* A **`data:` URI** — passed through unchanged.
* A **local file path** — read, validated, and converted to a base64 data URI
  before being sent.

```bash theme={null}
mulerouter run alibaba/wan2.6-i2v \
  --image ./photo.png \
  --prompt "Slow zoom in" \
  --duration 5
```

Supported formats: `.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.webp`, `.tiff`,
`.tif`, `.svg`, `.ico`, `.heic`, `.heif`, `.avif`. Files are capped at **20 MB**;
paths inside sensitive directories (`/etc`, `~/.ssh`, `~/.aws`, ...) are
blocked.

If you point at a local path that doesn't exist, the CLI prints a yellow warning
and still attempts the request (treating the string as a URL) so that typos
fail loudly rather than silently.

## Synchronous vs async

**Synchronous (default).** The CLI calls `POST` then loops with `GET` requests
every `--poll-interval` seconds, logging status changes to stderr. When the task
reaches a terminal state, the result is printed to stdout. The process exits
non-zero if the task failed.

**Async (`--no-wait`).** The CLI submits the task and prints the resulting
`task_id` and `api_path` so you can resume later with
[`mulerouter status`](/docs/cli/commands/status). Use this when generation may take
longer than `--max-wait`, or when running inside a short-lived CI step.

```bash theme={null}
mulerouter run alibaba/wan2.6-t2v --prompt "Long cinematic shot" --no-wait
# Task ID:  9d2b8c1a-...
# API Path: /vendors/alibaba/v1/wan2.6-t2v/generation
# Status:   created (not waiting for completion)
#
# Check status: mulerouter status /vendors/alibaba/v1/wan2.6-t2v/generation 9d2b8c1a-...
# Wait:         mulerouter status /vendors/alibaba/v1/wan2.6-t2v/generation 9d2b8c1a-... --wait
```

## Output formats

### Text (default)

```
Task ID: 9d2b8c1a-...
Status:  succeeded

Results:
  https://cdn.mulerouter.ai/.../video-0.mp4
```

### JSON (`--json`)

```json theme={null}
{
  "task_id": "9d2b8c1a-...",
  "status": "succeeded",
  "videos": [
    "https://cdn.mulerouter.ai/.../video-0.mp4"
  ],
  "data": { ... }
}
```

The result key (`videos`, `images`, `audios`) matches the `result_key` field
shown by [`mulerouter params`](/docs/cli/commands/params).

## Examples

```bash theme={null}
# Text-to-image
mulerouter run google/nano-banana-2/generation \
  --prompt "A serene mountain lake" \
  --resolution 2K

# Text-to-video with audio
mulerouter run alibaba/wan2.6-t2v \
  --prompt "Rain falling on a glass roof" \
  --duration 15 \
  --audio

# Image-to-video from a local file
mulerouter run alibaba/wan2.6-i2v \
  --image ./hero.jpg \
  --prompt "Gentle parallax with drifting clouds"

# Text-to-speech (MiniMax)
mulerouter run minimax/speech-2.8-turbo \
  --prompt "Welcome to MuleRouter." \
  --voice-id "Charming_Lady"

# Async submission + polling
mulerouter run alibaba/wan2.6-t2v --prompt "..." --no-wait --json \
  | tee task.json
```

## Exit codes

| Code | Meaning                                                                                                 |
| ---- | ------------------------------------------------------------------------------------------------------- |
| `0`  | Task completed successfully                                                                             |
| `1`  | Validation error, configuration error, transport error, or non-success terminal status (`failed`, etc.) |

## See also

* [`mulerouter status`](/docs/cli/commands/status) — poll an existing task
* [Async workflows](/docs/cli/workflows/async-tasks)
* [Scripting with JSON](/docs/cli/workflows/json-output)