Back to Details

qwencloud-usage

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

QwenCloud Usage

QwenCloud 使用指南

Query QwenCloud usage, free tier quota, coding plan status, and pay-as-you-go billing.
查询QwenCloud的使用情况、免费额度、编码计划状态以及按需付费账单。

Prerequisites

前提条件

  • QwenCloud CLI must be installed. Verify with:
bash
qwencloud version
If not installed, run:
bash
npm install -g @qwencloud/qwencloud-cli
Node.js >= 18 required.
  • Authentication: No configuration needed on first use. The CLI handles non-TTY detection and safe login automatically (see Authentication Flow below).
  • QwenCloud CLI 必须安装。可通过以下命令验证：
bash
qwencloud version
如果未安装，运行：
bash
npm install -g @qwencloud/qwencloud-cli
Node.js >= 18 为必要条件。
  • 认证：首次使用无需配置。CLI会自动检测非TTY环境并安全完成登录（详见下方的认证流程）。

Environment Variables

环境变量

VariableDescription
QWENCLOUD_KEYRING
Set to 
plaintext
, 
no
, 
0
, 
false
, or 
off
to opt out of OS keychain credential storage.
QWENCLOUD_CREDENTIALS_DIR
Override file-based credential directory (default: 
~/.qwencloud/credentials
).
变量名描述
QWENCLOUD_KEYRING
设置为 
plaintext
、
no
、
0
、
false
或 
off
可退出操作系统密钥链凭证存储。
QWENCLOUD_CREDENTIALS_DIR
覆盖基于文件的凭证目录（默认：
~/.qwencloud/credentials
）。

Authentication Flow (for Agents)

认证流程（适用于Agent）

The CLI auto-detects non-TTY environments and degrades safely — no wrapper script needed.
CLI会自动检测非TTY环境并安全降级处理 — 无需包装脚本。

TL;DR — 3-step auth path

快速概览 — 三步认证路径

  1. qwencloud auth status --format json
    → 
    authenticated: true
    → skip to commands
  2. qwencloud auth login --init-only --format json
    → extract 
    verification_url
    → open in browser
  3. qwencloud auth login --complete --format json
    → poll until 
    success
    event
  1. qwencloud auth status --format json
    → 
    authenticated: true
    → 直接执行后续命令
  2. qwencloud auth login --init-only --format json
    → 提取 
    verification_url
    → 在浏览器中打开
  3. qwencloud auth login --complete --format json
    → 轮询直到出现 
    success
    事件

Quick check: already logged in?

快速检查：是否已登录？

bash
qwencloud auth status --format json
If 
authenticated: true
and token is not expired, skip login entirely.
bash
qwencloud auth status --format json
如果返回 
authenticated: true
且令牌未过期，可直接跳过登录步骤。

Recommended: Two-phase login

推荐：两阶段登录

Works in all environments (desktop, headless, remote container).
Step 1 — Initialize login (non-blocking):
bash
qwencloud auth login --init-only --format json
Exits immediately. Parse the stdout JSON 
events
array:
  • already_authenticated
    → user is logged in, skip to commands
  • device_code
    → extract 
    verification_url
    and present it to the user
On desktop environments with a browser, open the URL for the user:
bash
open "$VERIFICATION_URL"          # macOS
xdg-open "$VERIFICATION_URL"      # Linux
start "" "$VERIFICATION_URL"      # Windows
Step 2 — IMMEDIATELY start polling (do NOT wait for user confirmation):
bash
qwencloud auth login --complete --format json
Parse the stdout JSON 
events
array:
  • success
    → login complete, proceed to commands
  • expired
    → device code expired, go back to Step 1
  • error
    → report failure
适用于所有环境（桌面、无头环境、远程容器）。
步骤1 — 初始化登录（非阻塞）：
bash
qwencloud auth login --init-only --format json
命令立即退出。解析标准输出的JSON 
events
数组：
  • already_authenticated
    → 用户已登录，直接执行后续命令
  • device_code
    → 提取 
    verification_url
    并展示给用户
在带有浏览器的桌面环境中，可为用户自动打开该链接：
bash
open "$VERIFICATION_URL"          # macOS
xdg-open "$VERIFICATION_URL"      # Linux
start "" "$VERIFICATION_URL"      # Windows
步骤2 — 立即启动轮询（请勿等待用户确认）：
bash
qwencloud auth login --complete --format json
解析标准输出的JSON 
events
数组：
  • success
    → 登录完成，执行后续命令
  • expired
    → 设备代码已过期，返回步骤1重新操作
  • error
    → 报告登录失败

TTY environments (interactive terminal)

TTY环境（交互式终端）

If the agent is running in a TTY (e.g., user's terminal), simply run:
bash
qwencloud auth login
The CLI will automatically open the browser and poll until authorization completes.
如果Agent运行在TTY环境中（例如用户的终端），只需运行：
bash
qwencloud auth login
CLI会自动打开浏览器并轮询直到授权完成。

JSON event structure

JSON事件结构

Both 
--init-only
and 
--complete
output a single JSON document:
json
{
  "events": [
    {"event": "device_code", "verification_url": "...", "expires_in": 300},
    {"event": "success", "authenticated": true, "user": {"aliyunId": "..."}}
  ]
}
Event types: 
already_authenticated
, 
device_code
, 
success
, 
expired
, 
error
, 
pending
.
--init-only
和 
--complete
命令均会输出单个JSON文档：
json
{
  "events": [
    {"event": "device_code", "verification_url": "...", "expires_in": 300},
    {"event": "success", "authenticated": true, "user": {"aliyunId": "..."}}
  ]
}
事件类型包括：
already_authenticated
、
device_code
、
success
、
expired
、
error
、
pending
。

NEVER:

禁止操作：

  • ❌ Ask the user "Have you completed authorization?" before running 
    --complete
  • ❌ Wait for user confirmation before polling — run 
    --complete
    immediately after presenting the URL
  • ❌ Re-run 
    --init-only
    without completing (this creates a new device code and invalidates the previous one)
  • ❌ 在运行 
    --complete
    前询问用户“是否已完成授权？”
  • ❌ 在用户确认后才启动轮询 — 展示链接后立即运行 
    --complete
  • ❌ 在未完成当前流程的情况下重新运行 
    --init-only
    （这会生成新的设备代码并使之前的代码失效）

Usage

使用方法

All commands support 
--format json
for structured, machine-parseable output (recommended default), and 
--format text
for clean plaintext output.
For agent use, always prefer 
--format json
 and parse the JSON response. Only fall back to 
--format text
when the user explicitly requests human-readable plaintext.
Never parse 
table
format programmatically — it contains ANSI codes and Unicode borders.
所有命令均支持 
--format json
以输出结构化、可机器解析的内容（推荐默认使用），同时支持 
--format text
以输出简洁的纯文本内容。
对于Agent使用场景，始终优先使用 
--format json
 并解析JSON响应。仅当用户明确要求人类可读的纯文本时，才回退到 
--format text
。
请勿以编程方式解析 
table
格式 — 该格式包含ANSI代码和Unicode边框。

Auth Commands

认证命令

qwencloud auth status
 — Check current authentication state
bash
qwencloud auth status --format json
qwencloud auth logout
 — Revoke session server-side and clear local credentials
bash
qwencloud auth logout
qwencloud auth status
 — 检查当前认证状态
bash
qwencloud auth status --format json
qwencloud auth logout
 — 服务器端吊销会话并清除本地凭证
bash
qwencloud auth logout

Usage Commands

使用情况查询命令

qwencloud usage summary
 — View usage summary (free tier, coding plan, pay-as-you-go)
bash
qwencloud usage summary                      # Current month
qwencloud usage summary --period last-month  # Last month
qwencloud usage summary --from 2026-03-01 --to 2026-03-31
qwencloud usage summary --format json        # JSON output
Period presets: 
today
, 
yesterday
, 
week
, 
month
(default), 
last-month
, 
quarter
, 
year
, 
YYYY-MM
qwencloud usage breakdown
 — View model usage breakdown
bash
qwencloud usage breakdown --model qwen3.6-plus --days 7
qwencloud usage breakdown --model qwen3.5-plus --period 2026-03
qwencloud usage breakdown --model qwen-plus --period 2026-03 --granularity month
qwencloud usage breakdown --model qwen3.6-plus --format json
qwencloud usage free-tier
 — View free tier quota details
bash
qwencloud usage free-tier
qwencloud usage free-tier --format json
qwencloud usage payg
 — View pay-as-you-go billing details
bash
qwencloud usage payg
qwencloud usage payg --format json
qwencloud usage summary
 — 查看使用情况汇总（免费额度、编码计划、按需付费）
bash
qwencloud usage summary                      # 当前月份
qwencloud usage summary --period last-month  # 上月
qwencloud usage summary --from 2026-03-01 --to 2026-03-31
qwencloud usage summary --format json        # JSON输出
周期预设值：
today
、
yesterday
、
week
、
month
（默认）、
last-month
、
quarter
、
year
、
YYYY-MM
qwencloud usage breakdown
 — 查看模型使用明细
bash
qwencloud usage breakdown --model qwen3.6-plus --days 7
qwencloud usage breakdown --model qwen3.5-plus --period 2026-03
qwencloud usage breakdown --model qwen-plus --period 2026-03 --granularity month
qwencloud usage breakdown --model qwen3.6-plus --format json
qwencloud usage free-tier
 — 查看免费额度详情
bash
qwencloud usage free-tier
qwencloud usage free-tier --format json
qwencloud usage payg
 — 查看按需付费账单详情
bash
qwencloud usage payg
qwencloud usage payg --format json

Breakdown Parameters: How to Think About Them

明细参数：使用思路

Three independent dimensions — combine them freely:
--model
(required) + date range + granularity
Model scope:
  • --model <id>
    — single model (e.g. 
    qwen3.5-plus
    ); required for breakdown
Date range — three patterns, pick by how the user described the period:
PatternWhen to useHow it works
--period YYYY-MM
User names a specific month ("March", "last April")Exact calendar month, start to end
--period <preset>
User describes a relative period
last-month
= previous full month; 
month
= this month so far; 
quarter
= this calendar quarter so far
--days N
User says "last N days"Rolling window backwards from today, crosses month boundaries naturally
--from YYYY-MM-DD --to YYYY-MM-DD
User gives explicit dates or a named quarter/rangeFull control, use when other patterns don't fit
Granularity — determines the grouping of results, not the range:
  • day
    (default) — one row per day; good for spotting usage spikes
  • month
    — one row per calendar month; good for multi-month trends
  • quarter
    — one row per quarter; good for Q-over-Q comparison
Classic examples:
bash
undefined
三个独立维度 — 可自由组合：
--model
（必填） + 日期范围 + 粒度
模型范围：
  • --model <id>
    — 指定单个模型（例如 
    qwen3.5-plus
    ）；查询明细时必填
日期范围 — 三种模式，根据用户描述的周期选择：
模式使用场景工作原理
--period YYYY-MM
用户指定具体月份（“三月”、“去年四月”）精确的日历月份，从月初到月末
--period <preset>
用户描述相对周期
last-month
= 上月完整周期；
month
= 当前月至今；
quarter
= 当前日历季度至今
--days N
用户提及“过去N天”从今天开始向前滚动的时间窗口，自然跨越月份边界
--from YYYY-MM-DD --to YYYY-MM-DD
用户给出明确日期或指定季度/范围完全可控，当其他模式不适用时使用
粒度 — 决定结果的分组方式，而非时间范围：
  • day
    （默认） — 按天分组；便于发现使用量峰值
  • month
    — 按日历月分组；便于查看多月趋势
  • quarter
    — 按季度分组；便于季度间对比
经典示例：
bash
undefined

Single model, single month, daily detail

单个模型、单个月份、每日明细

qwencloud usage breakdown --model qwen3.5-plus --period 2026-03
qwencloud usage breakdown --model qwen3.5-plus --period 2026-03

Single model, last 3 months, monthly summary

单个模型、过去3个月、月度汇总

qwencloud usage breakdown --model qwen3.5-plus --days 90 --granularity month
qwencloud usage breakdown --model qwen3.5-plus --days 90 --granularity month

Single model, specific quarter, quarterly rollup

单个模型、指定季度、季度汇总

qwencloud usage breakdown --model qwen3.5-plus --from 2026-01-01 --to 2026-03-31 --granularity quarter
qwencloud usage breakdown --model qwen3.5-plus --from 2026-01-01 --to 2026-03-31 --granularity quarter

Single model, this month, daily breakdown

单个模型、当前月份、每日明细

qwencloud usage breakdown --model qwen3.6-plus --period month
undefined
qwencloud usage breakdown --model qwen3.6-plus --period month
undefined

Output and Agent Display Rules

输出与Agent展示规则

CLI commands return JSON by default in agent/pipe environments (
auto
format: TTY → table, pipe → json). JSON is the primary output mode for agents — always pass 
--format json
explicitly, parse the structured response, then present a human-readable summary to the user.
在Agent/管道环境中，CLI命令默认返回JSON（
auto
格式：TTY环境返回表格，管道环境返回JSON）。 JSON是Agent的主要输出模式 — 始终显式传递 
--format json
，解析结构化响应后，再向用户展示人类可读的摘要。

JSON output example (
--format json
)

JSON输出示例（
--format json
）

bash
qwencloud usage summary --period month --format json
Returns structured JSON with three sections:
json
{
  "period": { "from": "2026-04-01", "to": "2026-04-24" },
  "free_tier": [
    { "model_id": "qwen3.6-plus", "quota": { "remaining": 850000, "total": 1000000, "unit": "tokens", "used_pct": 15 } }
  ],
  "coding_plan": {
    "subscribed": true,
    "plan": "PRO",
    "windows": {
      "per_5h": { "remaining": 4800, "total": 6000, "used_pct": 20 },
      "weekly": { "remaining": 38200, "total": 45000, "used_pct": 15 },
      "monthly": { "remaining": 82500, "total": 90000, "used_pct": 8 }
    }
  },
  "pay_as_you_go": {
    "models": [
      { "model_id": "qwen3.6-plus", "usage": { "tokens_total": 480000 }, "cost": 0.38, "currency": "USD" },
      { "model_id": "qwen-plus", "usage": { "tokens_total": 460000 }, "cost": 0.13, "currency": "USD" }
    ],
    "total": { "cost": 0.51, "currency": "USD" }
  }
}
bash
qwencloud usage summary --period month --format json
返回包含三个部分的结构化JSON：
json
{
  "period": { "from": "2026-04-01", "to": "2026-04-24" },
  "free_tier": [
    { "model_id": "qwen3.6-plus", "quota": { "remaining": 850000, "total": 1000000, "unit": "tokens", "used_pct": 15 } }
  ],
  "coding_plan": {
    "subscribed": true,
    "plan": "PRO",
    "windows": {
      "per_5h": { "remaining": 4800, "total": 6000, "used_pct": 20 },
      "weekly": { "remaining": 38200, "total": 45000, "used_pct": 15 },
      "monthly": { "remaining": 82500, "total": 90000, "used_pct": 8 }
    }
  },
  "pay_as_you_go": {
    "models": [
      { "model_id": "qwen3.6-plus", "usage": { "tokens_total": 480000 }, "cost": 0.38, "currency": "USD" },
      { "model_id": "qwen-plus", "usage": { "tokens_total": 460000 }, "cost": 0.13, "currency": "USD" }
    ],
    "total": { "cost": 0.51, "currency": "USD" }
  }
}

Text output example (
--format text
)

文本输出示例（
--format text
）

bash
qwencloud usage summary --period month --format text
plaintext
Usage Summary  ·  2026-04-10

-- Free Tier Quota -------------------------------------------------------
Model                Remaining      Total          Progress
qwen3.6-plus         850K tokens    1M tokens      85% left
wan2.6-t2i           38 images      50 images      76% left
--------------------------------------------------------------------------

-- Coding Plan · PRO Plan ------------------------------------------------
Window           Remaining      Total          Progress
Per 5 hours      4.8K req       6K req         20% used
This week        38.2K req      45K req        15% used
This month       82.5K req      90K req         8% used
--------------------------------------------------------------------------

-- Pay-as-you-go · 2026-04-01 → 2026-04-10 -------------------------------
Model                Usage              Cost
qwen3.6-plus         480K tok           $0.38
qwen-plus            460K tok           $0.13
--------------------------------------------------------------------------
Total                —                  $0.51
bash
qwencloud usage summary --period month --format text
plaintext
Usage Summary  ·  2026-04-10

-- Free Tier Quota -------------------------------------------------------
Model                Remaining      Total          Progress
qwen3.6-plus         850K tokens    1M tokens      85% left
wan2.6-t2i           38 images      50 images      76% left
--------------------------------------------------------------------------

-- Coding Plan · PRO Plan ------------------------------------------------
Window           Remaining      Total          Progress
Per 5 hours      4.8K req       6K req         20% used
This week        38.2K req      45K req        15% used
This month       82.5K req      90K req         8% used
--------------------------------------------------------------------------

-- Pay-as-you-go · 2026-04-01 → 2026-04-10 -------------------------------
Model                Usage              Cost
qwen3.6-plus         480K tok           $0.38
qwen-plus            460K tok           $0.13
--------------------------------------------------------------------------
Total                —                  $0.51

⚠️ CRITICAL: How to present output to the user

⚠️ 重要提示：如何向用户展示输出

When using 
--format json
(recommended for agents):
  1. Parse the JSON and extract the relevant data for the user's question
  2. Present a human-readable summary — do not dump raw JSON to the user
  3. Add analysis AFTER the summary — clearly separated with 
    ---
When using 
--format text
:
  1. Display CLI output EXACTLY AS-IS — no modification, no reformatting
  2. Preserve all formatting — alignment, spacing, progress bars, separators
  3. Add analysis AFTER output only — clearly separated with 
    ---
NEVER:
  • ❌ Dump raw JSON to the user without interpretation
  • ❌ Reformat or summarize text/table output
  • ❌ Add prefixes like "Here's your usage:"
  • ❌ Convert text/table output to bullet points
✅ CORRECT (JSON mode):
Your QwenCloud usage for April:

**Free Tier**: qwen3.6-plus has 85% remaining (850K / 1M tokens), wan2.6-t2i has 76% remaining (38 / 50 images).
**Coding Plan (PRO)**: 8% used this month (82.5K / 90K requests).
**Pay-as-you-go**: $0.51 total — qwen3.6-plus $0.38, qwen-plus $0.13.

---

**💡 Analysis**: Your qwen3.6-plus free tier is 85% remaining...
✅ CORRECT (Text mode):
[CLI text output - exactly as-is]

---

**💡 Analysis**: Your qwen3.6-plus free tier is 85% remaining...
❌ WRONG:
Here's your usage:
- qwen3.6-plus: 850K tokens remaining (85% left)
使用 
--format json
时（Agent推荐模式）：
  1. 解析JSON 并提取与用户问题相关的数据
  2. 展示人类可读的摘要 — 请勿直接向用户输出原始JSON
  3. 在摘要后添加分析 — 用 
    ---
    清晰分隔
使用 
--format text
时：
  1. 完全原样展示CLI输出 — 不修改、不重新格式化
  2. 保留所有格式 — 对齐方式、间距、进度条、分隔线
  3. 仅在输出后添加分析 — 用 
    ---
    清晰分隔
禁止操作：
  • ❌ 不做解释直接向用户输出原始JSON
  • ❌ 重新格式化或汇总文本/表格输出
  • ❌ 添加类似“这是您的使用情况：”的前缀
  • ❌ 将文本/表格输出转换为项目符号列表
✅ 正确示例（JSON模式）：
您的QwenCloud四月使用情况：

**免费额度**：qwen3.6-plus剩余85%（85万/100万 tokens），wan2.6-t2i剩余76%（38/50张图片）。
**编码计划（PRO）**：本月已使用8%（8.25万/9万次请求）。
**按需付费**：总计0.51美元 — qwen3.6-plus花费0.38美元，qwen-plus花费0.13美元。

---

**💡 分析**：您的qwen3.6-plus免费额度剩余85%...
✅ 正确示例（文本模式）：
[CLI文本输出 — 完全原样]

---

**💡 分析**：您的qwen3.6-plus免费额度剩余85%...
❌ 错误示例：
这是您的使用情况：
- qwen3.6-plus：剩余85万 tokens（85%）

Exit Codes

退出码

CodeMeaning
0Success
1General/usage error
2Authentication error
3Network error
4Configuration error
130Interrupted
代码含义
0成功
1常规/使用错误
2认证错误
3网络错误
4配置错误
130操作中断

CLI Update Check

CLI版本检查

When the user explicitly asks to check for cli updates (e.g. "check for cli updates", "check cli version", "is there a new version cli"):
  1. Run: 
    qwencloud version --check
  2. Report the result.
The QwenCloud CLI handles update notifications natively; no additional stderr signal handling is required in this skill.
当用户明确要求检查CLI更新时（例如“检查CLI更新”、“查看CLI版本”、“CLI有新版本吗”）：
  1. 运行：
    qwencloud version --check
  2. 向用户报告结果。
QwenCloud CLI原生支持更新通知；本技能无需额外处理stderr信号。

Implementation Notes

实现说明

  • Pay-as-you-go: API returns total usage only (no input/output split)
  • Coding Plan: Aggregate request counts at plan level (no per-model breakdown)
  • logout: Revokes server-side session and clears local credentials (keychain + file). Server-side call is best-effort — local logout always succeeds.
  • Authentication: Uses OAuth 2.0 Device Authorization Grant with PKCE. Credentials stored in OS keychain when available, with encrypted file fallback.
  • breakdown --model is required: Unlike the previous Python implementation, the CLI requires 
    --model
    for breakdown. To query all models' usage, use 
    qwencloud usage summary
    instead.
  • 按需付费：API仅返回总使用量（不区分输入/输出）
  • 编码计划：按计划级别汇总请求次数（无按模型细分）
  • logout：服务器端吊销会话并清除本地凭证（密钥链+文件）。服务器端调用为尽力而为 — 本地登出始终成功。
  • 认证：使用带有PKCE的OAuth 2.0设备授权流程。凭证优先存储在操作系统密钥链中， fallback到加密文件存储。
  • breakdown --model为必填项：与之前的Python实现不同，CLI查询明细时必须指定
    --model
    。如需查询所有模型的使用情况，请使用
    qwencloud usage summary
    。