---
title: CLI | Runware Docs
url: https://runware.ai/docs/platform/cli
description: 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.
relatedDocuments:
  - https://runware.ai/docs/platform/typescript
  - https://runware.ai/docs/platform/python
  - https://runware.ai/docs/platform/introduction
---
## 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 ⇥

positivePrompt=Text prompt describing the output

width=Width of the generated media in pixels

height=Height of the generated media in pixels

steps=Number of denoising steps

CFGScale=How closely the result follows the prompt

$ 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](https://runware.ai/docs/assets/result.BjNDIjKx_1wEBqd.webp)

## Installation

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

**Homebrew**:

```bash
brew install --cask runware/tap/runware
```

**Scoop**:

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

**Linux**:

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

**From source**:

```bash
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:

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

> [!NOTE]
> 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:

```bash
# 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:

```bash
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:

```bash
# 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

```bash
# 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`:

```bash
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`:

```bash
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

```json
{
  "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:

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

The bad width is caught before the task is submitted:

Output

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

## Models

`runware model` searches and inspects the catalog:

```bash
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:

```bash
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:

```bash
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:

```bash
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`:

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

## Configuration

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

```bash
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:

```bash
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:

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

Output

```text
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](https://github.com/runware/runware-cli) has per-shell install steps.

## Source

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

Repository: [github.com/runware/runware-cli](https://github.com/runware/runware-cli)