CLI

Run Runware inference from the terminal. A single static binary for image, video, audio, text, and 3D generation, plus model search, presets, uploads, and account management.

Introduction

The Runware CLI is a single static binary that drives the inference API from your terminal: image, video, audio, text, and 3D generation, plus model search, presets, uploads, and account management. It's written in Go and ships for macOS, Linux, and Windows with no runtime to install.

Inference runs through one command. runware run <model> takes a model's AIR identifier and key=value parameters, fetches the model's schema to detect the task type and coerce each value, then downloads the result. Output is a table by default, or JSON for piping into jq and scripts.

runware · zsh

$ runware run runware:400@1 ⇥

$ runware run runware:400@1 positivePrompt="A lighthouse on a rocky cliff at dusk" width=1344 height=768

INFO Task submitted taskUUID=85eb8a3e-7a14-4043-b42f-c335780a515c

INFO saved path=outputs/3ceeb9cf-c3bf-4266-af69-d97f5d978c62.jpg

A lighthouse on a rocky cliff at dusk with storm clouds and crashing waves

Installation

Install with your platform's package manager, or build from source.

Homebrew

brew install --cask runware/tap/runware

Scoop

scoop bucket add runware https://github.com/Runware/scoop-bucket.git
scoop install runware

Linux

curl -fsSL https://cli.runware.ai/install.sh | sh

From source

git clone https://github.com/runware/runware-cli.git
cd runware-cli
make build

Authentication

runware auth login prompts for your API key and stores it at ~/.runware/config.yaml. Pass --key to skip the prompt in scripts:

runware auth login              # interactive prompt
runware auth login --key <key>  # non-interactive
runware auth status             # check the stored key

The RUNWARE_API_KEY environment variable overrides the stored key, which is the right fit for CI and ephemeral shells.

Quick start

From an authenticated shell, generate an image in one command. The result downloads to ./outputs by default:

# Check connectivity
runware ping

# Generate an image
runware run runware:400@1 positivePrompt="A serene mountain landscape" width=1024 height=1024

# Inspect your account
runware account details

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

Configuration

The CLI keeps its settings in ~/.runware/config.yaml. The runware config subcommands read and edit it:

runware config show                                # print current settings
runware config set output_dir ~/runware-outputs    # set a default
runware config set format json
runware config set transport http
runware config path                                # print the config file path
runware config reset                               # restore defaults

The editable keys are output_dir, format, and transport. config reset restores those defaults while keeping your stored API key and saved presets, and config path prints the file location. The RUNWARE_API_KEY environment variable always overrides the stored key.

Transports

The CLI talks to the API over WebSocket (ws) by default, or REST (http). WebSocket streams progress for long-running tasks over one connection. REST sends a stateless request per invocation. Switch per command with --transport, or set a default in config:

runware run runware:400@1 positivePrompt="A landscape" --transport http

Global flags

Flag	Description
`-F, --format`	`table` (default), `json`, or `yaml`
`--transport`	`ws` (default) or `http`
`-v, --verbose`	Show request and response details
`--debug`	Full debug output

Output and scripting

Every command prints a table by default. Switch to JSON or YAML for machine-readable output. Progress spinners and logs are written to stderr, so --format json keeps stdout clean for piping:

runware account details --format json | jq '.balance'

Output

48.2034

Shell completions

runware completion generates completion scripts for bash, zsh, fish, and powershell. Completions are schema-driven: after a model's AIR, pressing Tab suggests that model's parameter names (positivePrompt=, width=, messages.0.role=). The repository has per-shell install steps.

Source

The CLI is open source. Issues and pull requests are welcome.

Repository: github.com/runware/runware-cli