> ## 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.

# Scripting with JSON output

> Drive the CLI from shell scripts, CI, and AI agents

Every command supports `--json`. The schema is small and stable, which makes
the CLI a comfortable building block for shell pipelines, automation, and
LLM-driven tools.

## Output schemas

### `mulerouter list --json`

```json theme={null}
{
  "models": [
    {
      "model_id": "alibaba/wan2.6-t2v",
      "action": "generation",
      "provider": "alibaba",
      "model_name": "wan2.6-t2v",
      "description": "...",
      "input_types": ["text"],
      "output_type": "video",
      "api_path": "/vendors/alibaba/v1/wan2.6-t2v/generation",
      "available_on": ["mulerouter", "mulerun"],
      "result_key": "videos",
      "tags": ["SOTA"]
    }
  ],
  "site": null
}
```

With `--providers`:

```json theme={null}
{ "providers": ["alibaba", "bytedance", "google", "klingai", "midjourney", "minimax", "openai"] }
```

### `mulerouter params --json`

```json theme={null}
{
  "model_id": "alibaba/wan2.6-t2v",
  "action": "generation",
  "description": "...",
  "api_path": "/vendors/alibaba/v1/wan2.6-t2v/generation",
  "output_type": "video",
  "result_key": "videos",
  "available_on": ["mulerouter", "mulerun"],
  "parameters": [
    {
      "name": "prompt",
      "type": "string",
      "description": "Text prompt describing the video to generate",
      "required": true
    }
  ]
}
```

### `mulerouter run --json`

When waiting for completion:

```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 endpoint's
`result_key`. With `--no-wait`, the response includes `task_id`, `api_path`,
and the full task info payload as returned by the upstream API.

### `mulerouter status --json`

```json theme={null}
{
  "task_id": "9d2b8c1a-...",
  "status": "running"
}
```

When the task succeeds, a `results` array appears. When it fails, an `error`
string explains why.

## Recipes

**Pick a random SOTA model**

```bash theme={null}
mulerouter list --tag SOTA --json \
  | jq -r '.models[].model_id + "/" + .models[].action' \
  | shuf -n 1
```

**Extract the first result URL**

```bash theme={null}
URL=$(mulerouter run openai/gpt-image-2/generation --prompt "A sunset" --json --quiet \
  | jq -r '.images[0]')
echo "$URL"
```

**Download every generated asset**

```bash theme={null}
mulerouter run alibaba/wan2.6-t2v --prompt "Ocean waves" --json --quiet \
  | jq -r '.videos[]' \
  | xargs -n1 curl -sSLO
```

**Validate a prompt without spending credits** (dry-run)

There is no built-in dry-run, but `mulerouter params <endpoint> --json` plus
[`ajv`](https://ajv.js.org/) on the parameter list lets you validate locally
before submitting.

**Pin a model from `package.json`**

```json theme={null}
{
  "scripts": {
    "thumb": "mulerouter run google/nano-banana-2 --prompt $npm_config_prompt --resolution 2K --quiet --json | jq -r '.images[0]'"
  }
}
```

```bash theme={null}
npm run thumb --prompt="A vector logo of a fox"
```

## Stdout vs stderr

* **stdout** is reserved for the JSON or text result. Safe to pipe.
* **stderr** carries progress lines (`[12s] status: queued`), warnings, and
  errors. Use `--quiet` to suppress progress lines while keeping real errors.

```bash theme={null}
mulerouter run alibaba/wan2.6-t2v --prompt "..." --json --quiet 2>errors.log
```

## Exit codes

| Code | Meaning                                                      |
| ---- | ------------------------------------------------------------ |
| `0`  | Success                                                      |
| `1`  | Validation, configuration, network, or terminal task failure |

Check `$?` before parsing JSON — a failed call may still emit JSON, but the
shape will contain an `error` field instead of results.

## Using the CLI from an AI agent

The CLI's combination of `--json` output, stable subcommand surface, and
deterministic exit codes makes it a clean tool to expose to an LLM agent. A
minimal tool spec:

```json theme={null}
{
  "name": "mulerouter_run",
  "description": "Generate an image, video, or audio asset with MuleRouter.",
  "input_schema": {
    "type": "object",
    "properties": {
      "endpoint": { "type": "string", "description": "provider/model[/action]" },
      "args":     { "type": "array",  "items": { "type": "string" } }
    },
    "required": ["endpoint", "args"]
  }
}
```

The agent shells out `mulerouter run <endpoint> <args...> --json --quiet`
and reads the resulting JSON. Pair with `mulerouter list --json` and
`mulerouter params <endpoint> --json` so the model can discover available
options without hardcoding them.