↑↓ Navigate enter Open esc Close
Dashboard

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.

brew install --cask runware/tap/runware
scoop bucket add runware https://github.com/Runware/scoop-bucket.git
scoop install runware
curl -fsSL https://cli.runware.ai/install.sh | sh
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:

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. model examples prints a ready-to-run runware run command for each example, so you can copy one, tweak the prompt, and run it. Add --format json for the full request and response payloads.

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 upload sends a local file, URL, or data URI and returns an imageUUID you can feed into other tasks:

runware upload ./photo.jpg

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

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

Configuration lives at ~/.runware/config.yaml. Set defaults with runware config set:

runware config set output_dir ~/runware-outputs
runware config set format json
runware config set transport http

The editable keys are output_dir, format, and transport. 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

Ask AI
Send feedback