runware-cli

Runware CLI

A command-line tool for interacting with the Runware API. Built in Go, distributed as a single static binary.

Run image generation, video generation, audio generation, 3D, upscaling, background removal, captioning, search models, deploy serverless applications, and more.

Install

Homebrew (macOS)

brew install --cask runware/tap/runware

Scoop (Windows)

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

Quick start

# Authenticate
runware auth login

# Check connectivity
runware ping

# Generate an image
runware run runware:400@1 positivePrompt="a chess match in the park" width=1024 height=1024

# Deploy a serverless application
runware serverless deploy ./app.py --id my-app --gpu-type h100 --wait

# Check your account details
runware account details

Commands

Full command reference is available in the docs directory.

runware run — inference

The primary command for all inference tasks. The model is identified by its AIR (AI Resource) identifier; parameters are passed as key=value pairs. The model's JSON Schema is fetched automatically to validate inputs and choose the right task type.

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

Flags:

Image generation

# Text-to-image
runware run runware:400@1 positivePrompt="A serene mountain landscape" width=1024 height=1024

# Save to a specific directory
runware run runware:400@1 positivePrompt="Abstract art" --output-dir ./my-images width=1024 height=1024

# Get the URL without downloading
runware run runware:400@1 positivePrompt="Abstract art" --format json --no-download

# Community model — specify task type explicitly
runware run civitai:305149@392545 --task-type imageInference positivePrompt="A portrait" width=1024 height=1024

Video generation

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

Audio generation

# Music generation
runware run minimax:music@2.6 positivePrompt="Upbeat electronic dance music with driving bass and synth leads" settings.instrumental=true

# Text-to-speech (the voice is designed from the prompt)
runware run alibaba:qwen@3-tts-1.7b-voicedesign positivePrompt="A calm, friendly young woman with a soft tone" speech.text="Hello, this is a text-to-speech example." speech.voice=design

Text inference (LLM)

# Single message
runware run google:gemma@4-31b messages.0.role=user messages.0.content="Explain quantum computing"

# Multi-turn conversation
runware run google:gemma@4-31b \
  messages.0.role=user    messages.0.content="What is Go?" \
  messages.1.role=assistant messages.1.content="A compiled language." \
  messages.2.role=user    messages.2.content="How do I install it?"

3D inference

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

# Image to 3D
runware run tencent:hunyuan-3d@3.1-pro inputs.images.0="https://example.com/product.jpg"

runware serverless — applications

Deploy, invoke, and manage Runware serverless applications. Full command reference is in docs/runware_serverless.md.

# List GPU types and per-second pricing
runware serverless gpus

# Create from a Python entry file (the working directory, or --src-dir, is zipped and uploaded)
runware serverless deploy ./app.py --id my-app --gpu-type h100 --wait

# Create from a container source (Dockerfile + container.yaml at the directory root)
runware serverless deploy --id my-app --gpu-type h100 --container ./wrapper --wait

# Later deploys with the same --id upload a new source and roll version N+1
runware serverless deploy ./app.py --id my-app --wait

# Inspect
runware serverless apps list
runware serverless apps show my-app
runware serverless apps endpoints my-app
runware serverless apps workers my-app --state live

# Invoke an endpoint (path is a bare segment, e.g. infer)
runware serverless apps invoke my-app infer -f payload.json --wait

# Logs, events, and usage
runware serverless apps logs my-app --follow
runware serverless apps events my-app
runware serverless apps errors my-app --window 1h --status-class 5xx
runware serverless usage --for this-month --group-by app,day
runware serverless usage events --app my-app --from 2026-09-01 --to 2026-09-02
runware serverless apps usage my-app --for this-month

# Environment, secrets, scale, and rename
runware serverless apps env set my-app MY_KEY --value-file ./value.txt
runware serverless secrets set FOO --value-file ./foo.txt
runware serverless secrets attach my-app FOO
runware serverless apps scale my-app --max-workers 2
runware serverless apps rename my-app "Image generator"

# Lifecycle
runware serverless apps stop my-app
runware serverless apps resume my-app
runware serverless open my-app

--volume, --env, --env-file, and --name apply on create only. Change --gpu-type and other worker settings with apps scale, environment with apps env, and the display name with apps rename. An environment change or a secret attach, detach, or rotation records a new version (or rolls live workers) — you do not need to redeploy source to apply them.

.env files are never packed into the source archive. Prefer --env-file and secrets set --value-file so values stay out of the process list.

Authentication

runware auth login              # Authenticate with API key (interactive)
runware auth login --key <key>  # Non-interactive login
runware auth logout             # Clear stored credentials
runware auth status             # Show current auth state

Account

runware account details         # Show account details, team, API keys, and usage stats

Models

runware model search -q "flux"                          # Search available models
runware model search -q "portrait" --category checkpoint --architecture sdxl
runware model search -q "anime" --wide                  # Include tags and default size columns
runware model show civitai:305149@392545                # Full details for a model
runware model schema google:3@2                         # Show request parameters for a model
runware model schema google:3@2 --response              # Show response schema instead
runware model pricing google:gemini@3.1-pro             # Pricing breakdown for a model
runware model examples google:gemini@3.1-pro            # Example requests for a model

model pricing and model examples read from the public model catalog and accept either the 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 to your account (WebSocket transport only):

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

Run runware model upload --help for the full flag set (LoRA trigger words, default scheduler and steps, visibility, and more). Your AIR source is shown by runware account details.

Presets

Save frequently used configurations:

runware preset save quick-flux runware:100@1 width=512 height=512 steps=4
runware preset list
runware preset show quick-flux
runware preset delete quick-flux

Configuration

runware config show             # Print current config
runware config set <key> <val>  # Set a config value
runware config reset            # Reset to defaults
runware config path             # Print config file path

Config is stored at ~/.runware/config.yaml.

Media

runware media upload <file|url>   # Upload media; prints mediaUUID (and mediaURL) for use in run params
runware media delete <mediaUUID>  # Permanently delete stored media by its UUID

Accepts a local file path, public URL, or data URI for upload. The returned mediaUUID can be passed to parameters like inputs.seedImage=<mediaUUID> on the run command. The taskUUID can be used with runware result.

The older runware upload command is deprecated; use runware media upload instead.

Result

runware result <taskUUID>       # Resume waiting for an async task by UUID

Use when runware run was interrupted before a task completed. The taskUUID is printed when the task is first submitted.

Other

runware ping                    # API connectivity check
runware version                 # Print version info
runware completion              # Generate shell completions (bash/zsh/fish/powershell, auto-detected)

Global flags

All commands support --format json for piping into jq or scripts.

Configuration

Environment variables

Config file

api_key: your-api-key

defaults:
    output_dir: ./outputs
    format: table
    transport: ws
presets:
    quick:
        model: runware:100@1
        params:
            height: "512"
            steps: "10"
            width: "512"

Development

make build          # Build binary for current platform → ./bin/runware
make build-all      # Build all platforms → ./bin/
make install        # go install for current platform
make run ARGS="..." # Run without building (e.g. make run ARGS="ping")
make test           # Run all tests
make fix            # Apply go fix modernizations
make check-go-fix   # Fail when go fix would change Go source
make lint           # Check go fix, then run golangci-lint
make docs           # Regenerate ./docs/ command reference
make snapshot       # GoReleaser snapshot build
make clean          # Remove ./bin and ./dist
make go-tidy        # go mod tidy && go mod verify

Shell completions

runware completion generates a completion script for your shell. Once installed, press Tab to complete commands, flags, model AIR identifiers, and — for runware run — schema-driven parameter names like positivePrompt=, width=, or messages.0.role=.

When your shell sets a standard version variable (FISH_VERSION, ZSH_VERSION, BASH_VERSION, PSModulePath), running runware completion without arguments auto-detects your shell. Pass an explicit name to override.

Bash

Linux — system-wide:

runware completion bash | sudo tee /etc/bash_completion.d/runware > /dev/null

macOS — Homebrew bash-completion@2:

runware completion bash > $(brew --prefix)/etc/bash_completion.d/runware

Per-user (any platform):

runware completion bash >> ~/.bash_completion
source ~/.bash_completion

Zsh

Add ~/.zfunc to your fpath before the compinit call in ~/.zshrc:

fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinit

Then generate the completion file and reload:

mkdir -p ~/.zfunc
runware completion zsh > ~/.zfunc/_runware
exec zsh

Oh My Zsh:

runware completion zsh > "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/completions/_runware"
exec zsh

Fish

runware completion fish > ~/.config/fish/completions/runware.fish

Fish picks up completions automatically — no shell restart needed.

PowerShell

Inline (recommended) — add to $PROFILE:

Invoke-Expression (& runware completion powershell | Out-String)

Or generate a file and dot-source it:

runware completion powershell | Out-File -Encoding utf8 "$HOME\runware.ps1"
# Add this line to $PROFILE:
. "$HOME\runware.ps1"

Demo

Once installed, Tab works at every level:

# Complete subcommands
$ runware <Tab>
auth        account     completion  config      media
model       ping        preset      result      run
serverless  upload      version

# Complete model AIR identifiers for `run`
$ runware run <Tab>
runware:400@1       -- FLUX.2 [dev] image generation
google:gemma@4-31b  -- Gemma text model
google:3@3          -- Veo 3.1 video generation
...

# Complete parameter names (schema-driven, per model)
$ runware run runware:400@1 <Tab>
positivePrompt=  -- Text prompt describing the image
width=           -- Output width in pixels
height=          -- Output height in pixels
steps=           -- Number of diffusion steps
...

# Array fields use dot-notation with auto-advancing indices
$ runware run google:gemma@4-31b <Tab>
messages.0.role=     -- Role of the message sender
messages.0.content=  -- Content of the message

# After messages.0.* are filled, next Tab suggests index 1
$ runware run google:gemma@4-31b messages.0.role=user messages.0.content="What is Go?" <Tab>
messages.1.role=     -- Role of the message sender
messages.1.content=  -- Content of the message