CLI Tool - QwenCloud

A QwenCloud CLI for management and model invocation. Use it to manage the model catalog, accounts, usage, billing, subscriptions, and support tickets, and to invoke text, image, video, and speech models.

Version 1.4.0

QwenCloud CLI is open source -- browse the code, file issues, or contribute: GitHub

Quick start

Requires Node.js 18 or later. The npm package name and installable versions are subject to the actual release page.

Install and verify:

npm install -g @qwencloud/qwencloud-cli
qwencloud version

Update to the latest version if the CLI is already installed:

npm users can update directly by running:

npm install -g @qwencloud/qwencloud-cli@latest

You can also check for a new version with:

qwencloud version --check
qwencloud update

update only checks and prints upgrade guidance; it does not install automatically. Run the command it prints. If you just completed step 1, you already have the latest version and can skip this step.

qwencloud auth login

Run your first query:

qwencloud models list

Make your first model invocation:

qwencloud chat create "Reply with one short sentence: hello from QwenCloud"

In an interactive terminal, this command streams text by default. For parameter, file-input, and automation-output rules, see Model invocation. Run qwencloud without arguments to enter interactive mode; with a command it executes once and exits. Management commands require no additional environment variables; the login flow saves management credentials. Model invocation still requires a valid management login and uses the inference key, environment variable, or OAuth credential available to the command. A successful models list response confirms installation, network, and login are all working. Agents can run qwencloud config set output.format json to lock JSON output; run qwencloud doctor --format json if verification fails.

Models and docs

Filter available models, check model details, or find onboarding docs? Start here.

models list

List available models, filtered by input/output modality.

qwencloud models list [--input <text|image|video|audio|vector>] [--output <text|image|video|audio|vector>] [--page <integer>] [--per-page <integer>] [--all] [--verbose] [--format <auto|table|json|text>]

qwencloud models list --input image --output text
qwencloud models list --all --verbose --format json

Flag	Type	Required	Default	Description
`--input <modality>`	enum	No	unset	Input modality: text, image, video, audio, vector
`--output <modality>`	enum	No	unset	Output modality: text, image, video, audio, vector
`--page <integer>`	integer	No	1	Page number; values below 1 are normalized to 1
`--per-page <integer>`	integer	No	20	Models per page; values below 1 are normalized to 1
`--all`	boolean	No	false	Return all models and disable pagination; forces JSON
`--verbose`	boolean	No	false	Include detail fields; forces JSON

JSON output structure example (sample values for field illustration only):

{
  "models": [
    {
      "id": "qwen3.6-plus",
      "modality": {
        "input": ["text", "image"],
        "output": ["text"]
      },
      "can_try": true,
      "free_tier": {
        "mode": "standard",
        "quota": {
          "remaining": 850000,
          "total": 1000000,
          "unit": "tokens",
          "used_pct": 15,
          "status": "valid",
          "resetDate": "2026-08-01T00:00:00.000Z"
        }
      },
      "pricing": {
        "tiers": [
          {
            "label": "Text input",
            "input": 1.25,
            "output": 3.75,
            "cache_creation": 1.5625,
            "cache_read": 0.125,
            "unit": "USD/1M tokens"
          }
        ],
        "summary": {
          "cheapest_input": 1.25,
          "cheapest_output": 3.75,
          "unit": "USD/1M tokens",
          "billing_type": "token"
        }
      },
      "features": ["function-calling"],
      "context": {
        "context_window": 131072,
        "max_input": 122880,
        "max_output": 8192
      }
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

After finding candidate models, run qwencloud models info <id> to view full pricing, context, and rate-limit details.

models info

View full details for a single model; provide either the positional argument or --model.

qwencloud models info [id] [--model [id]] [--format <auto|table|json|text>]

qwencloud models info qwen3.6-plus
qwencloud models info --model qwen3.6-plus --format json

Flag / Arg	Type	Required	Default	Description
`[id]`	string	conditional	none	Model ID
`--model [id]`	string	conditional	none	Model ID; alternative to the positional argument

This command returns model-catalog metadata such as modality, features, context, pricing, and rate limits; it does not provide the complete request parameter schema. For model parameters and accepted values, use the official API parameter page that matches both the model ID and interface type. qwencloud docs search <model-id> can help locate that page, but you must verify its model ID and interface type. To continue comparing candidate models, run qwencloud models search <query> to narrow results.

models search

Search models by keyword or modality.

qwencloud models search <query> [--page <integer>] [--per-page <integer>] [--all] [--format <auto|table|json|text>]

qwencloud models search "function calling"
qwencloud models search image --all --format json

Flag / Arg	Type	Required	Default	Description
`<query>`	string	Yes	none	Search term
`--page <integer>`	integer	No	1	Page number
`--per-page <integer>`	integer	No	20	Models per page
`--all`	boolean	No	false	Return all matches; forces JSON

docs search

Search official documentation; optionally view the Nth result inline.

qwencloud docs search <query> [--limit <integer>] [--page <integer>] [--language <en|zh>] [--view <integer>] [--format <auto|table|json|text>]

qwencloud docs search "chat completions" --language en --limit 10
qwencloud docs search "API Key" --view 1

Flag / Arg	Type	Required	Default	Description
`<query>`	string	Yes	none	Search term
`--limit <integer>`	integer	No	20	JSON/text: 1-100 per page; table mode: max 5
`--page <integer>`	integer	No	1	Page number
`--language <en\|zh>`	string (en/zh)	No	en	Document language; other values silently fall back to en
`--view <integer>`	integer	No	unset	View the 1-based index from the current results

After finding a target entry, run qwencloud docs view <path-or-url> to read the full content.

docs view

View page content by document path or URL.

qwencloud docs view <path-or-url> [--format <auto|table|json|text>]

qwencloud docs view api-reference/preparation/cli

Arg	Type	Required	Default	Description
`<path-or-url>`	string	Yes	none	Document path or URL

Authentication, account, and workspace

Log in, check credential validity, or see which workspaces your account can access? Use these commands.

qwencloud auth login [--init-only] [--complete] [--timeout <seconds>] [--format <auto|table|json|text>]

qwencloud auth login
qwencloud auth login --init-only --format json
qwencloud auth login --complete --timeout 180

Flag	Type	Required	Default	Description
`--init-only`	boolean	No	false	Output authorization info and exit immediately
`--complete`	boolean	No	false	Continue and complete a pending login session
`--timeout <seconds>`	integer	No	120	Polling timeout in seconds for `--complete`

In non-TTY environments without --init-only/--complete, the command automatically returns in init-only mode. Credentials are preferentially stored in the system keychain, falling back to an encrypted file. You can also run qwencloud login directly. After successful login, run qwencloud auth status --format json to check credentials, then qwencloud models list to verify query permissions.

auth status

Check local credentials and server-side verification status.

qwencloud auth status [--format <auto|table|json|text>]

qwencloud auth status --format json

Full JSON structure example:

{
  "authenticated": true,
  "server_verified": true,
  "auth_mode": "device_flow",
  "source": "keychain",
  "user": {
    "aliyunId": "example-user"
  },
  "token": {
    "expires_at": "2026-08-01T00:00:00.000Z",
    "scopes": ["inference:read", "usage:read", "config:write"]
  }
}

When the server is unreachable but local credentials are still valid, server_verified is false and may include a warning; exit code is 2 when not logged in or credentials have expired. If authenticated is false, re-run qwencloud auth login.

auth logout

Log out and delete local credentials. You can also run qwencloud logout directly.

qwencloud auth logout [--format <auto|table|json|text>]

qwencloud auth logout

workspace list

List workspaces accessible to the current account.

qwencloud workspace list [--format <auto|table|json|text>]

qwencloud workspace list --format json

After listing workspaces, run qwencloud workspace limit to check whether the account can create more.

workspace limit

View used workspace count and account hard limit.

qwencloud workspace limit [--format <auto|table|json|text>]

qwencloud workspace limit

Model invocation also requires a valid management login; explicitly passing --api-key does not bypass this check. For the documented inference-credential sources and precedence, see Model invocation.

Model invocation

Start chats, generate or edit images, generate videos, transcribe speech, synthesize speech, or query asynchronous tasks from the terminal.

Goal	Command	Primary execution mode and result
Text or multimedia chat	`qwencloud chat create`	Streams by default in an interactive terminal; non-interactive output is non-streaming by default
Generate or edit images	`qwencloud image generate`	Selects synchronous or asynchronous execution by model ID; successful images are written locally by default
Generate video from text or images	`qwencloud video generate`	Always asynchronous and waits by default; downloads the result only when `--out` is provided
Transcribe an audio recording	`qwencloud audio transcribe`	Qwen models run synchronously; other models run asynchronously
Synthesize speech from text	`qwencloud audio speech`	Runs synchronously and writes audio locally by default
Query an asynchronous task	`qwencloud task get`	Queries once without continuous polling

All six commands check for a management login first. Even when --api-key is passed explicitly, qwencloud auth login cannot be skipped. Inference credentials are selected in this documented order: --api-key → QWENCLOUD_API_KEY → QWEN_API_KEY → DASHSCOPE_API_KEY → OAuth. Supported parameters and values vary by model. CLI acceptance of a parameter, transmission of a field, an HTTP 2xx response, exit code 0, or receipt of a task ID does not mean the model supports or used that parameter. This page documents CLI entry points only. For model parameters, use the API parameter page linked at the end of each command section that matches the model family, model ID, protocol, and execution branch. qwencloud models info <id> returns model metadata only. qwencloud docs search <model-id> is only a keyword-search aid; verify the model ID and interface type in every result. --request accepts inline JSON, @file, or - to read from stdin, and the root must be an object. An explicit --model overrides model in the request. When a convenience flag and its synonymous request field are both present, the command generally reports PARAM_LAYER_CONFLICT and exits with code 4. Successful parsing does not mean the request is sent unchanged; TTS WebSocket requests, in particular, are reconstructed.

Explicit file input	Pay-as-you-go (`sk-ws-` or legacy `sk-...`)	Token Plan (`sk-sp-`)	Key boundary
Chat `--image` / `--video`	Local file or URL	Only an HTTP/HTTPS or `oss://` URL accessible to the target model	The CLI uploads a local file and rewrites it to a temporary `oss://` URL
Image `--image`	Local file or URL	Only an HTTP/HTTPS or `oss://` URL accessible to the target model	Only supported editing models process this input
Video `--image`	Local file or URL	Only an HTTP/HTTPS or `oss://` URL accessible to the target model	This flag switches the invocation to I2V
ASR `[file-or-url]`	Local file or URL	Only an HTTP/HTTPS or `oss://` URL accessible to the target model	The positional argument is the only explicit file input

For pay-as-you-go calls, when any explicit input above receives a local file, the CLI uploads it first and rewrites the input to a temporary oss:// URL. HTTP/HTTPS and oss:// inputs are sent as URLs, but the model service is not guaranteed to be able to access them. A local path in --request is only a JSON string; the CLI does not recursively discover or upload it. Using a local file with Token Plan reports LOCAL_UPLOAD_UNSUPPORTED and exits with code 4. Remediation guidance appears in message; there is no separate hint. The CLI does not check for an existing file before writing a result and may overwrite it directly. Image and TTS write to the current directory by default. Video writes only when the current invocation waits successfully and supplies --out. task get automatically writes to the current directory only for successful image, video, or audio tasks whose media type can be identified from the URL extension. Before querying the same successful task again, move any same-named file that you need to keep.

chat create

Start one text or multimedia chat. The current default model is qwen3.8-max.

qwencloud chat create [prompt] [--model <id>] [--temperature <n>] [--max-tokens <n>] [--stream] [--thinking|--no-thinking] [--image <path-or-url>] [--video <path-or-url>] [--request <json|@file|->] [--api-key <key>] [--format <auto|table|json|text>]

qwencloud chat create "Explain serverless computing in one sentence"
qwencloud chat create "Describe this image" --image https://example.com/image.png
qwencloud chat create "List three ideas" --stream --format json

Flag / Arg	Type	Required	Default	Description
`[prompt]`	string	conditional	none	Text prompt; provide this or `--request`
`--model <id>`	string	No	`qwen3.8-max`	Model ID; an explicit value overrides `model` in the request
`--temperature <n>`	number	No	unset	Sampling temperature; the CLI only verifies that it is a finite number
`--max-tokens <n>`	integer	No	unset	Total output token budget; must be a positive integer
`--stream`	boolean	No	TTY: true; non-TTY: false	Force streaming output; there is currently no `--no-stream`
`--thinking` / `--no-thinking`	boolean	No	unset	Send `enable_thinking`; control whether human-readable output and streaming events show reasoning content
`--image <path-or-url>`	string	No	none	Attach one image to the positional prompt; can be used with `--video`
`--video <path-or-url>`	string	No	none	Attach one video to the positional prompt; can be used with `--image`
`--request <json\|@file\|->`	string	conditional	none	Native request body; provide this or a prompt
`--api-key <key>`	string	No	documented credential order	Use only for this inference call; does not bypass management login
`--format <fmt>`	enum	No	`auto`	`auto`, `table`, `json`, or `text`

A prompt cannot coexist with request.messages. --image and --video require a positional prompt; media flags in a request-only invocation are not written into the request. If --temperature, --max-tokens, --stream, --thinking, or a media flag coexists with the corresponding request field, the command reports PARAM_LAYER_CONFLICT and exits with code 4. The CLI enters streaming mode only because of an explicit --stream or because stdout is a TTY; request.stream cannot switch the CLI output branch. In a TTY, a request-supplied stream conflicts with the implicit streaming setting and exits with code 4. Non-streaming --format json returns {meta,data} and preserves upstream reasoning_content. --thinking controls only whether human-readable output and streaming events show reasoning content. Streaming --format json returns NDJSON, not one JSON document. Each content event contains an incremental delta that must be concatenated in order. With --thinking, reasoning-delta lines contain reasoning: true. Only after successful completion is the last line {"meta":{...}}, which can contain request_id, model, finish_reason, and normalized token usage. A streaming-event failure is written to stderr and exits with code 1; a connection network error is written to stderr and exits with code 3. stdout may already contain partial delta output before a failure, with no final meta line. --image and --video follow the domain-level file rules. Passing a local file with Token Plan reports LOCAL_UPLOAD_UNSUPPORTED and exits with code 4; use a URL accessible to the target model instead. The default qwen3.8-max branch uses the OpenAI-compatible Chat API. See OpenAI-compatible Chat API for its parameters. Text generation models can supplement model selection, but it is not a substitute for the matching API parameter page. Command success does not mean every supplied parameter was used by the model.

image generate

Generate an image, or process one reference image with a model that supports editing. The current default model is qwen-image-3.0-pro.

qwencloud image generate [prompt] [--model <id>] [--size <width*height>] [--n <count>] [--image <path-or-url>] [--out <path>] [--response-format <fmt>] [--request <json|@file|->] [--no-wait] [--timeout <seconds>] [--api-key <key>] [--format <auto|table|json|text>]

qwencloud image generate "A paper-cut illustration of a cloud city"
qwencloud image generate "Replace the sky with sunset" --model qwen-image-edit-plus --image ./photo.png
qwencloud image generate "A watercolor fox" --model wanx2.1-t2i-turbo --no-wait --format json

Flag / Arg	Type	Required	Default	Description
`[prompt]`	string	conditional	none	Generation or editing prompt; provide this or `--request`
`--model <id>`	string	No	`qwen-image-3.0-pro`	Model ID
`--size <width*height>`	string	No	unset	Output dimensions; the CLI only validates the `number*number` form
`--n <count>`	integer	No	unset	Number of images; must be a positive integer and is subject to the CLI's model-ID-based limit of 1 or 6 images
`--image <path-or-url>`	string	No	none	Provide the source image for editing with the positional prompt; requires an explicitly selected supported editing model
`--out <path>`	string	No	current directory	Image file or directory written after this invocation waits successfully
`--response-format <fmt>`	string	No	unset	Only the exact value `b64` has an effect; use `--format json` to read base64
`--request <json\|@file\|->`	string	conditional	none	Native request body; provide this or a prompt
`--no-wait`	boolean	No	false	Return the task ID immediately after submitting an asynchronous model
`--timeout <seconds>`	number	No	300	Synchronous request timeout or asynchronous polling cutoff; must be positive, and the latter is not a strict end-to-end limit
`--api-key <key>`	string	No	documented credential order	Use only for this inference call
`--format <fmt>`	enum	No	`auto`	`auto`, `table`, `json`, or `text`

The CLI dispatches only by model ID: IDs beginning with wanx, or matching wan2.<minor> with a minor version below 6, run asynchronously. wan1.x, wan2.6+, and other models are not classified as asynchronous by this rule. The current default model runs synchronously. --image validates the editing model first; the current default model does not enter the editing branch directly. A prompt cannot coexist with request.input. --image requires a positional prompt; --image in a request-only invocation is not written into the request. If --size, --n, or --image coexists with the corresponding request field, the command reports PARAM_LAYER_CONFLICT. Successful images download to --out or the current directory by default. With --response-format b64 --format json, the CLI downloads each result, converts it locally to base64, and returns it through data.images[ ].b64; table and text output show only a message or URL, not base64. Other --response-format values currently do not report an error and still use the default download behavior; do not rely on that behavior. For an asynchronous model, --no-wait returns a task ID and exits with code 0 without preserving --out or b64 post-processing settings; a later task get applies its own automatic-download rules. When asynchronous polling reaches the --timeout threshold, the current implementation returns the incomplete status and exits with code 0. Queries already in flight can make the actual duration exceed that value. This does not mean the task is complete; continue with qwencloud task get <task-id>. An asynchronous FAILED task exits with code 1. A synchronous transport timeout or other NETWORK_ERROR, and a non-2xx download response, exit with code 3. A non-2xx model API response, an unwrapped download network error, or a write failure usually exits with code 1. --image follows the domain-level file rules. Passing a local file with Token Plan reports LOCAL_UPLOAD_UNSUPPORTED and exits with code 4; use a URL accessible to the target model instead. For parameters, use the page that matches the execution branch: Qwen text-to-image for the default qwen-image-3.0-pro synchronous branch, Qwen image editing for the Qwen editing branch, and Wan text-to-image v2 create task for the Wan v2 asynchronous text-to-image create-task branch.

video generate

Submit a text-to-video or image-to-video task. The current default model is happyhorse-1.1-t2v when --image is absent and happyhorse-1.1-i2v when --image is supplied.

qwencloud video generate [prompt] [--model <id>] [--image <path-or-url>] [--wait|--no-wait] [--timeout <seconds>] [--out <path>] [--request <json|@file|->] [--api-key <key>] [--format <auto|table|json|text>]

qwencloud video generate "A paper airplane flying over a city"
qwencloud video generate "Make the cat run" --image ./cat.png --out ./cat.mp4
qwencloud video generate "A sunrise over the sea" --no-wait --format json

Flag / Arg	Type	Required	Default	Description
`[prompt]`	string	conditional	none	Video prompt; provide this or `--request`
`--model <id>`	string	No	see below	Model ID; the default depends only on whether an explicit `--image` is present
`--image <path-or-url>`	string	No	none	First-frame image; switches to the current I2V default model
`--wait` / `--no-wait`	boolean	No	wait	Wait for a terminal state or return the task ID immediately after submission
`--timeout <seconds>`	number	No	900	Asynchronous polling cutoff; must be positive and is not a strict end-to-end limit
`--out <path>`	string	No	none	File or directory downloaded after this invocation waits successfully; without it, only the URL is returned
`--request <json\|@file\|->`	string	conditional	none	Native request body; provide this or a prompt
`--api-key <key>`	string	No	documented credential order	Use only for this inference call
`--format <fmt>`	enum	No	`auto`	`auto`, `table`, `json`, or `text`

This command always submits asynchronously and waits for completion by default. Default-model selection checks only an explicit --image, not an image inside --request; a native I2V request should set model explicitly. A prompt cannot coexist with request.input, and an explicit T2V model cannot be combined with --image. These parameter errors exit with code 4. --no-wait returns a task ID and exits with code 0, proving only that the task was submitted; it does not preserve --out for a later query. When asynchronous polling reaches the --timeout threshold, the command prints the latest task status and exits with code 8. Queries already in flight can make the actual duration exceed that value. A FAILED task exits with code 1. After a task succeeds, the file is downloaded only when this invocation waited for success and explicitly supplied --out; otherwise, the command returns the URL. --image follows the domain-level file rules. Passing a local file with Token Plan reports LOCAL_UPLOAD_UNSUPPORTED and exits with code 4; use a URL accessible to the target model instead. Without --image, the HappyHorse T2V branch uses HappyHorse text-to-video create task. Passing --image switches to the I2V branch, which uses HappyHorse image-to-video create task; do not use the T2V parameter page for that branch. For Wan models, select the official page that matches the specific T2V, I2V, first-and-last-frame, reference, or editing branch rather than binding all Wan invocations to one page.

audio transcribe

Transcribe a local audio recording or audio URL. The current default model is qwen-audio-3.0-asr-flash.

qwencloud audio transcribe [file-or-url] [--model <id>] [--language <hint>] [--wait|--no-wait] [--timeout <seconds>] [--request <json|@file|->] [--api-key <key>] [--format <auto|table|json|text>]

qwencloud audio transcribe ./meeting.wav
qwencloud audio transcribe https://example.com/meeting.mp3 --language en
qwencloud audio transcribe https://example.com/meeting.wav --model paraformer-v2 --no-wait --format json

Flag / Arg	Type	Required	Default	Description
`[file-or-url]`	string	conditional	none	Audio recording file or URL; provide this or `--request`
`--model <id>`	string	No	`qwen-audio-3.0-asr-flash`	Model ID
`--language <hint>`	string	No	unset	Language hint; Qwen models write it to `parameters.asr_options.language`, while other models write it to `parameters.language_hints[ ]`
`--wait` / `--no-wait`	boolean	No	wait	Wait for an asynchronous model's terminal state or return its task ID immediately; the synchronous Qwen branch ignores this choice
`--timeout <seconds>`	number	No	300	Must be positive; for asynchronous execution, it is a polling cutoff rather than a strict end-to-end limit, and the synchronous branch ignores it after validation
`--request <json\|@file\|->`	string	conditional	none	Native request body; provide this or the positional argument
`--api-key <key>`	string	No	documented credential order	Use only for this inference call
`--format <fmt>`	enum	No	`auto`	`auto`, `table`, `json`, or `text`

Models whose IDs begin with qwen use a synchronous native multimodal request; other models use asynchronous ASR. The Qwen branch infers parameters.format from the explicit audio source or the first audio URL in the request and uses wav when no recognizable extension is available. The positional argument cannot coexist with request.input, and --language cannot coexist with the corresponding language field in the request. These parameter errors exit with code 4. The synchronous branch returns text; --wait and --no-wait have no effect. --timeout must still pass positive-number validation, but it does not control the synchronous request afterward. Asynchronous --no-wait returns a task ID and exits with code 0. When polling reaches the --timeout threshold, the command prints the task status and exits with code 8; queries already in flight can make the actual duration exceed that value. On completion, the command prints a preview of up to 200 characters and the result URL; it does not save the complete transcription JSON. The positional argument follows the domain-level file rules. Passing a local file with Token Plan reports LOCAL_UPLOAD_UNSUPPORTED and exits with code 4; use a URL accessible to the target model instead. The default qwen-audio-3.0-asr-flash path is a synchronous native multimodal branch. No official parameter-schema page has been identified that exactly matches both this default model ID and protocol, so the qwen3-asr Qwen-ASR/DashScope page must not be treated as its exact parameter page. Use the speech-to-text model catalog for model discovery. For non-Qwen asynchronous models, select the create-task/query-result or Fun-ASR page that matches the specific model and protocol. To continue querying an asynchronous task, use qwencloud task get <task-id>.

audio speech

Synthesize text into audio and write it locally. The current default model is qwen-audio-3.0-tts-plus.

qwencloud audio speech [text] [--model <id>] [--voice <name>] [--out <path>] [--request <json|@file|->] [--api-key <key>] [--format <auto|table|json|text>]

qwencloud audio speech "Welcome to QwenCloud"
qwencloud audio speech "Welcome to QwenCloud" --voice longanhuan_v3.6 --out ./welcome.mp3

Flag / Arg	Type	Required	Default	Description
`[text]`	string	conditional	none	Text to synthesize; provide this or `--request`
`--model <id>`	string	No	`qwen-audio-3.0-tts-plus`	Model ID
`--voice <name>`	string	No	determined by model and input method	Voice ID or name; a positional-text Qwen-model call defaults to `longanhuan_v3.6`, a request-only call does not add a default, and CosyVoice requires an explicit value
`--out <path>`	string	No	current directory	Audio file or directory path
`--request <json\|@file\|->`	string	conditional	none	Native request body; provide this or text
`--api-key <key>`	string	No	documented credential order	Use only for this inference call
`--format <fmt>`	enum	No	`auto`	`auto`, `table`, `json`, or `text`

The command runs synchronously. Positional text cannot coexist with request.input. A model ID containing cosyvoice or beginning with sambert uses WebSocket; other applicable models use HTTP. Realtime-only TTS and omni/live-translate models are rejected locally with exit code 4. An HTTP URL result is downloaded, while a WebSocket binary result is written to a file. Without --out, the result is written to the current directory. A WebSocket request retains only the resolved model, input.text, and parameters. The CLI first adds default values for text_type, format, and sample_rate; request parameters then override those defaults, and an explicit --voice overrides the voice last. Other top-level request fields are not included in the WebSocket message. The current conflict check examines only request.input.voice; if the request already contains parameters.voice, an explicit --voice overrides it without reporting PARAM_LAYER_CONFLICT. The internal 60-second HTTP timeout covers only the period before a response is obtained, not reading the response body or subsequently downloading the audio URL. WebSocket uses an overall timer of approximately 60 seconds that intermediate messages do not reset. This command has no timeout flag. A transport timeout reports NETWORK_ERROR and exits with code 3. A non-2xx audio-download response exits with code 3; an unwrapped download network error or write failure usually exits with code 1. The default qwen-audio-3.0-tts-plus branch uses synchronous HTTP SpeechSynthesizer. No official parameter-schema page has been identified that exactly matches both this default model ID and protocol. Use the text-to-speech model catalog for model discovery and the Qwen voice list when selecting a Qwen voice. CosyVoice and Sambert WebSocket parameter pages apply only to those respective branches and must not be used as parameter pages for the default Qwen HTTP branch. This command has no upload input; --out is only a result path.

task get

Query the status of an existing task ID once. This command does not poll continuously.

qwencloud task get <task-id> [--api-key <key>] [--format <auto|table|json|text>]

qwencloud task get TASK_ID
qwencloud task get TASK_ID --format json

Flag / Arg	Type	Required	Default	Description
`<task-id>`	string	Yes	none	Asynchronous task ID to query
`--api-key <key>`	string	No	documented credential order	Use only for this query
`--format <fmt>`	enum	No	`auto`	`auto`, `table`, `json`, or `text`

`task_status`	CLI result	Exit code	Next step
`PENDING` / `RUNNING`	Print the current status	0	Run `task get` again later
`SUCCEEDED`	Print the normalized result; recognized image, video, or audio output is downloaded first	0, only if post-processing succeeds	Use the output path or URL
`FAILED` / `CANCELED`	Normalize `CANCELED` to `FAILED`; write the failed status to stdout first	1	Read `code` and `message` from the result
`UNKNOWN` or missing	Print normalized `UNKNOWN`	0	Inspect the normalized result with `--format json`; it is not the raw response

If <task-id> is omitted entirely, Commander reports MISSING_ARGUMENT and exits with code 1. If an explicit whitespace-only string is passed, the command reports INVALID_ARGUMENT and exits with code 4. This command has no --out flag or flag to disable downloads. After a remote task returns SUCCEEDED, the CLI processes the result before printing the final envelope. A non-2xx media-download response exits with code 3; an unwrapped network error or write failure usually exits with code 1. In these cases, no final status envelope is printed. A remote SUCCEEDED status therefore does not guarantee that the CLI returned successfully or wrote the file. If transcription preview retrieval fails, the CLI falls back to the URL; previews contain at most 200 characters. JSON output is also a normalized {meta,data} envelope, not the raw service response. This command has no upload input and no model parameter page. Query the task ID returned by the preceding operation, and evaluate task_status, the process exit code, and the local path together rather than treating any single signal as proof that all processing succeeded.

Usage, billing, and subscriptions

Want to know how much you've used this month, how much you've spent, which model or API Key costs the most, or how much subscription quota remains? Use these commands.

Date options vary by command: usage summary dates only affect PAYG, usage free-tier currently returns a snapshot only; other queries resolve in order: --from/--to > --days > --period > month-to-date. Common --period values include today, yesterday, week, month, last-month, quarter, year, and YYYY-MM.

usage summary

Summarize free quota, Token Plan, and pay-as-you-go usage.

qwencloud usage summary [--from <date>] [--to <date>] [--period <preset>] [--format <auto|table|json|text>]

qwencloud usage summary --period month
qwencloud usage summary --from 2026-07-01 --to 2026-07-21 --format json

Flag	Type	Required	Default	Description
`--from <date>`	date	No	first day of current month	PAYG start date, YYYY-MM-DD
`--to <date>`	date	No	today	PAYG end date, YYYY-MM-DD
`--period <preset>`	string	No	month	PAYG preset range or YYYY-MM

Date parameters and the JSON top-level period only scope pay_as_you_go; free_tier, coding_plan, and token_plan are current snapshots at query time. Full JSON structure example (sample values for field illustration only):

{
  "period": {
    "from": "2026-07-01",
    "to": "2026-07-21"
  },
  "free_tier": [
    {
      "model_id": "qwen-plus",
      "quota": {
        "remaining": 850000,
        "total": 1000000,
        "unit": "tokens",
        "used_pct": 15,
        "status": "valid",
        "resetDate": "2026-08-01T00:00:00.000Z"
      }
    }
  ],
  "coding_plan": {
    "subscribed": true,
    "plan": "pro",
    "price": {
      "amount": 50,
      "currency": "USD",
      "cycle": "monthly"
    },
    "included_models": [],
    "windows": {
      "per_5h": {
        "remaining": 4800,
        "total": 6000,
        "used_pct": 20,
        "next_reset_at": "2026-07-21T12:00:00.000Z"
      },
      "weekly": {
        "remaining": 25000,
        "total": 30000,
        "used_pct": 16.67,
        "next_reset_at": "2026-07-27T00:00:00.000Z"
      },
      "monthly": {
        "remaining": 90000,
        "total": 100000,
        "used_pct": 10,
        "next_reset_at": "2026-08-01T00:00:00.000Z"
      }
    }
  },
  "token_plan": {
    "subscribed": true,
    "planName": "Token Plan",
    "status": "valid",
    "totalCredits": 25000,
    "remainingCredits": 18000,
    "usedPct": 28,
    "resetDate": "2026-08-01T00:00:00.000Z"
  },
  "pay_as_you_go": {
    "models": [
      {
        "model_id": "qwen-plus",
        "usage": {
          "tokens": 600000
        },
        "cost": 0.38,
        "currency": "USD"
      }
    ],
    "total": {
      "cost": 0.38,
      "currency": "USD"
    }
  }
}

When a model shows unusual usage, run qwencloud usage breakdown --model <id>; for request-level details, use qwencloud usage logs.

usage breakdown

View pay-as-you-go usage for a specific model, broken down by day, month, or quarter.

qwencloud usage breakdown --model <id> [--granularity <day|month|quarter>] [--from <date>] [--to <date>] [--period <preset>] [--days <number>] [--format <auto|table|json|text>]

qwencloud usage breakdown --model qwen-plus --days 7
qwencloud usage breakdown --model qwen-plus --granularity month --period quarter

Flag	Type	Required	Default	Description
`--model <id>`	string	Yes	none	Model ID; validated at runtime
`--granularity <g>`	enum	No	day	day, month, quarter
`--from <date>`	date	No	unset	Start date
`--to <date>`	date	No	unset	End date
`--period <preset>`	string	No	month	Preset range
`--days <number>`	number	No	unset	Lookback days; pass a positive integer -- CLI does not strictly validate integer type

usage free-tier

Browse current free quota status for all models.

qwencloud usage free-tier [--from <date>] [--to <date>] [--period <preset>] [--format <auto|table|json|text>]

qwencloud usage free-tier --format json

Flag	Type	Required	Default	Description
`--from <date>`	date	No	unset	Registered; does not currently affect the returned quota snapshot
`--to <date>`	date	No	unset	Registered; does not currently affect the returned quota snapshot
`--period <preset>`	string	No	unset	Registered; does not currently affect the returned quota snapshot

This command always returns the current free quota snapshot; date flags do not currently filter historical quota.

usage payg

Browse pay-as-you-go usage for all models.

qwencloud usage payg [--from <date>] [--to <date>] [--period <preset>] [--days <number>] [--format <auto|table|json|text>]

qwencloud usage payg --period last-month
qwencloud usage payg --days 30 --format json

Flag	Type	Required	Default	Description
`--from <date>`	date	No	unset	Start date
`--to <date>`	date	No	unset	End date
`--period <preset>`	string	No	month	Preset range
`--days <number>`	number	No	unset	Lookback days; pass a positive integer -- CLI does not strictly validate integer type

usage logs

Query call logs by time, model, status, or request ID.

qwencloud usage logs [--from <date-or-rfc3339>] [--to <date-or-rfc3339>] [--period <preset>] [--model <id>]... [--status <type>]... [--request-id <id>] [--page <integer>] [--page-size <integer>] [--format <auto|table|json|text>]

qwencloud usage logs --period 24h --status 4xx --status 5xx
qwencloud usage logs --request-id 12345-abcdef --format json

Flag	Type	Required	Default	Description
`--from <value>`	date/time	No	7 days ago 00:00	YYYY-MM-DD or RFC3339
`--to <value>`	date/time	No	current time	YYYY-MM-DD or RFC3339
`--period <preset>`	string	No	unset	Supports `Nh`, `Nd`, and date presets
`--model <id>`	repeatable string	No	unset	Model filter, repeatable
`--status <type>`	repeatable string	No	unset	Supports 0/cancel, 2xx/success, 4xx/client-error, 5xx/server-error and aliases; unknown values are ignored
`--request-id <id>`	string	No	unset	Exact request ID; when set, other filters are ignored
`--page <integer>`	integer	No	1	Page number
`--page-size <integer>`	integer	No	20	1-100 per page

Maximum time span per query is 14 days.

billing summary

Summarize pre-tax, tax, and post-tax billing amounts by settlement month.

qwencloud billing summary [--from <yyyy-mm>] [--to <yyyy-mm>] [--charge-type <all|subscription|payg>] [--format <auto|table|json|text>]

qwencloud billing summary --from 2026-06 --to 2026-07

Flag	Type	Required	Default	Description
`--from <yyyy-mm>`	month	No	current month	Start settlement month
`--to <yyyy-mm>`	month	No	current month	End settlement month, inclusive
`--charge-type <type>`	enum	No	all	all, subscription, payg

To locate cost sources, run qwencloud billing breakdown --group-by model or --group-by api-key.

billing breakdown

Break down spending by model or API Key.

qwencloud billing breakdown [--granularity <day|month>] [--group-by <model|api-key>] [--from <date>] [--to <date>] [--period <preset>] [--charge-type <all|subscription|payg>] [--top <integer>] [--format <auto|table|json|text>]

qwencloud billing breakdown --group-by api-key --top 20
qwencloud billing breakdown --granularity day --period week

Flag	Type	Required	Default	Description
`--granularity <g>`	enum	No	month	day or month
`--group-by <dim>`	enum	No	model	model or api-key
`--from <date>`	date/month	No	current month	day uses YYYY-MM-DD; month accepts YYYY-MM
`--to <date>`	date/month	No	current month	End date or month
`--period <preset>`	string	No	unset	Preset range; periods shorter than 31 days may auto-adopt day
`--charge-type <type>`	enum	No	all	all, subscription, payg
`--top <integer>`	integer	No	10	Return top N items, max 100

Day-level queries span at most 31 days; month-level queries span at most 12 months.

billing limit

View spending cap and alert configuration.

qwencloud billing limit [--format <auto|table|json|text>]

qwencloud billing limit --format json

billing payment-method bind

Open the payment method management page to bind or manage payment methods.

qwencloud billing payment-method bind [--format <table|json|text>]

qwencloud billing payment-method bind

This command defaults to table format when no format is specified; agents should pass --format json explicitly.

billing payment-method list

List payment methods bound to the account.

qwencloud billing payment-method list [--format <table|json|text>]

qwencloud billing payment-method list --format json

If the list is empty or you need to change payment methods, run qwencloud billing payment-method bind.

subscription status

Summarize subscription status.

qwencloud subscription status [--plan <token|coding>] [--format <auto|table|json|text>]

qwencloud subscription status --plan coding --format json

Flag	Type	Required	Default	Description
`--plan <kind>`	string	No	all supported plans	Accepts token, coding; other values are treated as unset without error

When using Team Token Plan, run qwencloud subscription tokenplan seats --format json to view seat instances.

subscription orders

List subscription purchase, renewal, and upgrade orders.

qwencloud subscription orders [--from <date>] [--to <date>] [--type <purchase|renew|upgrade>] [--page <integer>] [--page-size <integer>] [--format <auto|table|json|text>]

qwencloud subscription orders --type purchase --page 1 --page-size 20

Flag	Type	Required	Default	Description
`--from <date>`	date	No	unset	Start date, YYYY-MM-DD
`--to <date>`	date	No	unset	End date, YYYY-MM-DD
`--type <kind>`	string	No	unset	Accepts purchase, renew, upgrade; other values are treated as unset without error
`--page <integer>`	integer	No	1	Page number
`--page-size <integer>`	integer	No	20	1-100 per page

subscription tokenplan status

View Token Plan seat type, cycle, renewal status, and diagnostic info.

qwencloud subscription tokenplan status [--format <auto|table|json|text>]

qwencloud subscription tokenplan status --format json

subscription tokenplan seats

List Token Plan seat instances with pagination.

qwencloud subscription tokenplan seats [--spec-type <pro|standard>] [--page <integer>] [--page-size <integer>] [--format <auto|table|json|text>]

qwencloud subscription tokenplan seats --spec-type pro --format json

Flag	Type	Required	Default	Description
`--spec-type <type>`	enum	No	unset	pro or standard
`--page <integer>`	integer	No	1	Page number
`--page-size <integer>`	integer	No	20	Max 100 per page

This command defaults to table format when no format is specified; agents should pass --format json explicitly.

Configuration, diagnostics, and completion

Want to lock machine-readable output, troubleshoot the local environment, enable shell completion, or confirm the version? Use these commands.

config list

List user-configurable settings. The only currently exposed setting is output.format.

qwencloud config list [--format <auto|table|json|text>]

qwencloud config list --format json

config get

Read a configuration value.

qwencloud config get <key> [--format <auto|table|json|text>]

qwencloud config get output.format

config set

Set a configuration value.

qwencloud config set <key> <value> [--format <auto|table|json|text>]

qwencloud config set output.format json

output.format accepts auto, table, json, text. After setting, run qwencloud config get output.format to confirm.

config unset

Delete a configuration value and restore default behavior.

qwencloud config unset <key> [--format <auto|table|json|text>]

qwencloud config unset output.format

doctor

Check version, authentication, token, network, shell completion, and global configuration.

qwencloud doctor [--format <auto|table|json|text>]

qwencloud doctor --format json

Fix issues based on diagnostic results and re-run qwencloud doctor until all failures are resolved.

completion install

Install command completion for the current or specified shell.

qwencloud completion install [--shell <bash|zsh|fish>]

qwencloud completion install --shell zsh

completion generate

Output the completion script for the current or specified shell.

qwencloud completion generate [--shell <bash|zsh|fish>]

qwencloud completion generate --shell bash

When --shell is omitted, the shell is auto-detected. Supported: bash, zsh, fish.

version

Output version; --check also checks for new versions.

qwencloud version [--check]

qwencloud version --check

Support and updates

Submit and track issues, close or rate tickets, or check for CLI updates? Choose your action here.

support list

List support tickets with pagination.

qwencloud support list [--page <integer>] [--page-size <integer>] [--format <auto|table|json|text>]

qwencloud support list --page 1 --page-size 10

Flag	Type	Required	Default	Description
`--page <integer>`	integer	No	1	Page number
`--page-size <integer>`	integer	No	10	1-10 per page

support view

View ticket details and message history.

qwencloud support view <ticket-id> [--format <auto|table|json|text>]

qwencloud support view TICKET_ID --format json

support create

Create a ticket interactively, or non-interactively with paired parameters.

qwencloud support create [--list-categories] [--category-id <id>] [--description <text>] [--format <auto|table|json|text>]

qwencloud support create --list-categories
qwencloud support create --category-id CATEGORY_ID --description "Issue description"

Flag	Type	Required	Default	Description
`--list-categories`	boolean	No	false	List categories and exit
`--category-id <id>`	string	conditional (non-interactive)	none	Must be provided with `--description`
`--description <text>`	string	conditional (non-interactive)	none	Max 2000 characters, truncated if exceeded

Requires TTY when complete non-interactive parameters are not provided. After creation, save the returned ticket ID and run qwencloud support view <ticket-id> to track progress.

support reply

Reply to a ticket; non-interactive environments must provide the message body.

qwencloud support reply <ticket-id> [--message <text>] [--format <auto|table|json|text>]

qwencloud support reply TICKET_ID --message "Please check the logs"

Flag / Arg	Type	Required	Default	Description
`<ticket-id>`	string	Yes	none	Ticket ID
`--message <text>`	string	required (non-interactive)	none	Max 2000 characters, truncated if exceeded

support close

Close a ticket; scripts should use --yes to skip confirmation.

qwencloud support close <ticket-id> [--yes] [--format <auto|table|json|text>]

qwencloud support close TICKET_ID --yes

Flag / Arg	Type	Required	Default	Description
`<ticket-id>`	string	Yes	none	Ticket ID
`--yes`	boolean	No	false	Skip confirmation; non-TTY without this flag treats as cancel

support rate

Rate a resolved ticket; rating range is 1-5.

qwencloud support rate <ticket-id> [--rating <1|2|3|4|5>] [--comment <text>] [--format <auto|table|json|text>]

qwencloud support rate TICKET_ID --rating 5 --comment "Excellent"

Flag / Arg	Type	Required	Default	Description
`<ticket-id>`	string	Yes	none	Ticket ID
`--rating <n>`	integer	required (non-interactive)	none	1-5 stars
`--comment <text>`	string	No	unset	Max 500 characters, truncated if exceeded

update

Check version and output upgrade prompt; does not install directly.

qwencloud update

qwencloud update

Global conventions

qwencloud [--format <auto|table|json|text>] [--quiet] <area> <verb> [args] [flags]

Global Flag	Type	Default	Description
`--format <fmt>`	enum	auto	Explicit format takes priority over `config output.format`
`-q, --quiet`	boolean	false	Suppress stdout/stderr; result conveyed via exit code only
`-v, --version`	boolean	false	Top-level version shortcut
`-h, --help`	boolean	false	Top-level and per-command help

auto uses table in TTY, JSON in pipe/redirect; an explicit table request in a non-TTY environment degrades to text with a stderr warning. Success data goes to stdout, errors and diagnostics go to stderr. JSON from management commands retains command-specific fields; successful model-invocation results are usually {meta,data}. Error JSON has no globally uniform fields: the exit-code field for a local CliError is error.exit_code, while some gateway, business, or authentication errors omit it. Scripts should rely on the process exit code. Chat with --stream --format json outputs NDJSON rather than a success envelope. In paginated queries, JSON typically preserves the requested page and returns an empty array for out-of-bounds; interactive tables typically adjust to a valid page. Agents should always specify --format json, page number, and page size explicitly.

Exit Code	Meaning
0	Success
1	General error; Commander argument parse errors also use 1
2	Authentication failure
3	Network error
4	Parameter or configuration error
8	Some asynchronous waits reached their limit while the task remained incomplete
10	`docs view` document not found
130	User interrupt

Some local validations in specific commands reuse general error code 1. Exit code 8 for model invocation is an exception: Video and asynchronous ASR first write the incomplete envelope to stdout, then exit with code 8 without writing a separate JSON error. Scripts should inspect both data.task_status in stdout and the process exit code. For other failures, treat any nonzero exit code as failure and dispatch on error.code when available.

Appendix

Command cheat sheet

Command	Purpose
`qwencloud auth login`	Obtain and save management credentials
`qwencloud auth logout`	Delete local credentials and log out
`qwencloud auth status`	Check credential and server verification status
`qwencloud models list`	Filter available models
`qwencloud models info`	View full details for a single model
`qwencloud models search`	Find models by keyword or modality
`qwencloud chat create`	Start a text or multimedia chat
`qwencloud image generate`	Generate or edit images
`qwencloud video generate`	Submit a text-to-video or image-to-video task
`qwencloud audio transcribe`	Transcribe audio
`qwencloud audio speech`	Synthesize text into a local audio file
`qwencloud task get`	Query an asynchronous task once and process its result
`qwencloud usage summary`	Summarize usage across billing methods
`qwencloud usage breakdown`	Break down usage for a specific model
`qwencloud usage free-tier`	Check free quota balance
`qwencloud usage payg`	View pay-as-you-go usage and cost
`qwencloud usage logs`	Query call logs by request or status
`qwencloud config list`	View public configuration keys
`qwencloud config get`	Read a single configuration value
`qwencloud config set`	Set default output format
`qwencloud config unset`	Restore configuration defaults
`qwencloud doctor`	Diagnose version, auth, or network issues
`qwencloud completion install`	Enable shell completion
`qwencloud completion generate`	Export shell completion script
`qwencloud version`	View version and check for updates
`qwencloud update`	Get upgrade prompt
`qwencloud docs search`	Search official docs by keyword
`qwencloud docs view`	Open document content
`qwencloud workspace list`	List accessible workspaces
`qwencloud workspace limit`	Check workspace count limit
`qwencloud billing summary`	View monthly settlement totals with tax
`qwencloud billing breakdown`	Break down costs by model or API Key
`qwencloud billing limit`	Check spending cap and alerts
`qwencloud billing payment-method bind`	Open payment method management page
`qwencloud billing payment-method list`	View bound payment methods
`qwencloud subscription status`	Confirm subscription status
`qwencloud subscription orders`	View purchase, renewal, and upgrade orders
`qwencloud subscription tokenplan status`	View cycle and renewal status
`qwencloud subscription tokenplan seats`	Browse seat instances with pagination
`qwencloud support list`	List tickets with pagination
`qwencloud support view`	View ticket and message history
`qwencloud support create`	Submit a new ticket
`qwencloud support reply`	Add a message to a ticket
`qwencloud support close`	Close a ticket
`qwencloud support rate`	Rate a resolved ticket

​Quick start

​Models and docs

​models list

​models info

​models search

​docs search

​docs view

​Authentication, account, and workspace

​auth login

​auth status

​auth logout

​workspace list

​workspace limit

​Model invocation

​chat create

​image generate

​video generate

​audio transcribe

​audio speech

​task get

​Usage, billing, and subscriptions

​usage summary

​usage breakdown

​usage free-tier

​usage payg

​usage logs

​billing summary

​billing breakdown

​billing limit

​billing payment-method bind

​billing payment-method list

​subscription status

​subscription orders

​subscription tokenplan status

​subscription tokenplan seats

​Configuration, diagnostics, and completion

​config list

​config get

​config set

​config unset

​doctor

​completion install

​completion generate

​version

​Support and updates

​support list

​support view

​support create

​support reply

​support close

​support rate

​update

​Global conventions

​Appendix

​Command cheat sheet