Model commands

Run inference from the terminal, search models, use presets, upload inputs and resume a task.

Introduction

These are the commands for Runware's own models. Installing the binary and signing in are on the overview, and the serverless half is in Serverless commands.

Running inference

runware run is the entry point for every model. You give it an AIR identifier and parameters as key=value pairs:

runware run <model> [key=value ...] [flags]

The CLI fetches the model's JSON Schema to coerce each value to the right type and detect the task type. Parameter names are the API's own field names, so positivePrompt, width, and steps are exactly what you'd find in the model's reference.

Nested and array parameters

Object and array fields use dot notation. Index into arrays with a number, and the CLI builds the nested structure for you:

# Chat messages (array of objects)
runware run google:gemma@4-31b \
  messages.0.role=user messages.0.content="Explain quantum computing"

# Speech settings (nested object)
runware run alibaba:qwen@3-tts-1.7b-voicedesign \
  positivePrompt="A calm, friendly young woman with a soft tone" \
  speech.text="Hello there" speech.voice=design

# Image inputs (array of strings)
runware run tencent:hunyuan-3d@3.1-pro inputs.images.0="https://example.com/product.jpg"

More examples

# Video
runware run google:3@3 positivePrompt="Ocean waves at sunset" width=1280 height=720 duration=8

# Music
runware run minimax:music@2.6 positivePrompt="Upbeat synthwave with driving bass" settings.instrumental=true

# Text to 3D
runware run tencent:hunyuan-3d@3.1-pro positivePrompt="A red vintage sports car"

Community and custom models

When the CLI can't resolve a task type from the schema (community uploads, custom fine-tunes), name it explicitly with --task-type:

runware run civitai:305149@392545 --task-type imageInference \
  positivePrompt="A portrait" width=1024 height=1024

Flags

Flag	Description
`--task-type`	Override the detected task type (e.g. `imageInference`, `videoInference`, `3dInference`)
`--output-dir`	Directory for downloaded files (default `./outputs`)
`--no-download`	Print result URLs without downloading them
`--delivery-method`	`sync` or `async` (default `async`)
`--poll-interval`	How often to poll async tasks (default `2s`)
`--preset`	Load parameters from a saved preset
`--validate`	Check parameters against the schema before sending

Delivery and downloads

By default the CLI submits with async delivery, polls until the task finishes, and downloads any media to the output directory. Use --no-download to print the URLs instead, which pairs well with --format json:

runware run runware:400@1 positivePrompt="Abstract art" width=1024 height=1024 \
  --format json --no-download

Each result prints to stdout as a JSON object, ready to pipe into jq:

Output

{
  "imageURL": "https://im.runware.ai/image/os/w01d10/ws/3/ii/1d0c0c3a-3d58-4efc-9ddd-112f23dd4113.jpg",
  "imageUUID": "1d0c0c3a-3d58-4efc-9ddd-112f23dd4113",
  "seed": 1951942294,
  "status": "success",
  "taskType": "imageInference",
  "taskUUID": "60cb0ed5-3fdc-4b6f-ba78-2f724441520b"
}

For tasks that finish quickly, --delivery-method sync skips polling and returns the result in a single round trip.

Validation

Client-side validation is off by default, since the API validates every request. Turn it on with --validate to check parameters against the model's schema before the request leaves your machine. Missing required fields and out-of-range values both fail locally, with no round trip:

runware run runware:400@1 positivePrompt="A landscape" width=-1 height=1024 --validate

The bad width is caught before the task is submitted:

Output

ERRO invalid value for "width": -1 is below the minimum of 512

Models

runware model searches and inspects the catalog. Each subcommand takes a model's AIR (or its catalog id):

search finds models by keyword, creator, architecture, or capability, for when you don't yet know a model's AIR.
show prints a model's full details: name, AIR, category, architecture, base model, and visibility.
schema lists the request parameters with their type, whether they're required, defaults, and descriptions, indenting nested objects. Add --response for the response shape, or --format json for the raw schema envelope.
pricing breaks the model's cost down as a configuration and price table.
examples prints a ready-to-run runware run command for each curated example, so you can copy one, tweak the prompt, and run it.

runware model search -q "flux" --architecture sdxl   # search
runware model show civitai:305149@392545             # full details
runware model schema google:3@2                      # request parameters
runware model schema google:3@2 --response           # response shape
runware model pricing google:gemini@3.1-pro          # pricing breakdown
runware model examples google:gemini@3.1-pro         # example requests

model pricing and model examples read from the public catalog and accept either an AIR or the model id. Add --format json to any model command for the full payload.

Upload a custom model with runware model upload (WebSocket transport only). Run runware model upload --help for the full flag set:

runware model upload \
  --air "myorg:my-model@1.0" --name "My Model" \
  --category checkpoint --architecture sdxl \
  --download-url "https://example.com/model.safetensors"

Presets

A preset stores a model and a set of parameters under a name. Pass --preset to run and override individual values on the command line:

runware preset save quick-flux runware:100@1 width=512 height=512 steps=4
runware preset list
runware run --preset quick-flux positivePrompt="A neon city street"

Uploading inputs

runware media upload sends a local file, URL, or data URI and returns a mediaUUID you can feed into other tasks. runware media delete <mediaUUID> removes stored media when you no longer need it:

runware media upload ./photo.jpg

# Use the result as a seed image
runware run runware:400@1 positivePrompt="Same scene at night" \
  inputs.seedImage=$(runware media upload ./photo.jpg -F json | jq -r '.mediaUUID')

Resuming a task

Long-running tasks print a taskUUID when they're submitted. If run is interrupted, resume waiting with runware result:

runware result 7fbf4fc9-5b61-461c-84a4-1e496da4debb