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

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

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

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

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

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

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