# wan-cli

English | [简体中文](https://unpkg.com/@l-design/wan-cli@latest/README.zh-CN.md)

Create images and videos on [Wan](https://wan.video) from your terminal or coding agent.

`wan-cli` supports text-to-image, image-to-image, image sequences, text-to-video,
image-to-video, reference-to-video, video editing, and Wan 3.0 Omni workflows.
Commands can return structured JSON for scripts and agents.

## Requirements

- Node.js 22 or later
- A Wan AccessKey

## Install

```bash
npm install --global @l-design/wan-cli
```

Confirm the installation:

```bash
wan --version
wan --help
```

## Sign in

Run the interactive login, select a Wan site, and paste your AccessKey when prompted:

```bash
wan auth login
```

The AccessKey input is hidden. You can manage more than one account and switch the
active account later:

```bash
wan auth status
wan auth list
wan auth list --use 2
wan logout
```

Wan AccessKeys and ModelScope API Keys are different credentials and cannot be used
interchangeably.

## Quick start

Create an image:

```bash
wan text2image \
  --prompt "A white cat napping beside a window, cinematic soft light" \
  --ratio 1:1
```

Create an image from a reference:

```bash
wan image2image \
  --image ./portrait.png \
  --prompt "Transform this into a cinematic studio portrait" \
  --generation-mode reference
```

Create a video:

```bash
wan text2video \
  --prompt "A paper boat sailing through a neon city at night" \
  --ratio 16:9 \
  --duration 5
```

Animate a local image:

```bash
wan image2video \
  --image ./cat.png \
  --prompt "The cat looks up at the camera" \
  --duration 5
```

Use reference assets:

```bash
wan reference2video \
  --assets ./character.png,./motion.mp4 \
  --start 0 \
  --end 5 \
  --prompt "The character runs through a city street"
```

Create with Wan 3.0 Omni:

```bash
wan omni2video \
  --images ./look.png \
  --videos ./shot.mp4 \
  --video-ranges 1:6 \
  --prompt "Continue @Video1 naturally while keeping the style of @Image1"
```

Local media is uploaded automatically when a command needs it.

## Check and download results

Generation commands return a task ID. Wait for the task and save its output:

```bash
wan task wait <task-id> --save --save-dir ./wan-results
```

You can also inspect a task or list recent tasks:

```bash
wan result get <task-id>
wan task list --page-size 10
```

Add `--output json` to get machine-readable output:

```bash
wan task wait <task-id> --output json
```

## Main commands

| Command | Purpose |
| --- | --- |
| `wan text2image` | Generate an image from text |
| `wan image2image` | Transform one or more images |
| `wan sequential_image` | Generate a related image sequence |
| `wan text2video` | Generate a video from text |
| `wan image2video` | Animate an image or create a first/last-frame video |
| `wan reference2video` | Generate from image, video, or Wan character references |
| `wan videoedit` | Edit an existing video |
| `wan omni2video` | Create with mixed image, video, audio, document, or URL inputs |
| `wan task wait` | Wait for a task and optionally download results |
| `wan task list` | List recent tasks |
| `wan credits` | Show the account credit balance |

Run `wan <command> --help` to see the options supported by a command.

## Coding agents and Skills

Installing or updating the package automatically syncs the bundled `wan-cli` Skill
to supported coding agents detected on your device. The Skill teaches an agent to
use local files, structured output, task polling, and the appropriate Wan workflow.

You can also discover and install Skills published by Wan:

```bash
wan skills list --skill-name <name> --output json
wan skills install '<https-zip-url>' --output json
```

Only install the original HTTPS URL returned by `wan skills list`.

## Language

The CLI uses Chinese when the system language is Chinese and English otherwise.
Override it for one command with `--lang`, or with `WAN_LANG`:

```bash
wan --lang zh --help
WAN_LANG=en wan auth login
```

## Update

```bash
wan update --check
wan update
```

Install a specific version with `wan update --target <version>`.

## Configuration and security

Account configuration is stored in `~/.wan/config.json`. Never commit this file or
share your full AccessKey in chat, logs, or screenshots. If a key may have been
exposed, revoke it from the Wan account page and create a new one.

Use the current directory's `.env` file or environment variables when a project
needs an explicit override:

```bash
WAN_SITE=intl
WAN_ACCESS_KEY="wan-sk.<key-id>.<secret>"
```

Command-line flags take precedence over environment variables, which take
precedence over `.env` and the user configuration.