qianwen-usage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

QianWen Usage

QianWen 使用指南

Query QianWen usage, free tier quota, Token Plan status, and pay-as-you-go billing.

查询QianWen的使用情况、免费额度、Token Plan状态以及按需付费账单。

Prerequisites

前提条件

QianWen CLI must be installed. Verify with:

bash

qianwen version

If not installed, run:

bash

npm install -g @qianwenai/qianwen-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).

必须安装 QianWen CLI。可通过以下命令验证：

bash

qianwen version

若未安装，请运行：

bash

npm install -g @qianwenai/qianwen-cli

需要Node.js版本 >= 18。

认证：首次使用无需配置。CLI会自动处理非TTY环境检测并安全完成登录（详见下方认证流程）。

Environment Variables

环境变量

Variable	Description
`QIANWEN_KEYRING`	Set to `plaintext` , `no` , `0` , `false` , or `off` to opt out of OS keychain credential storage.
`QIANWEN_CREDENTIALS_DIR`	Override file-based credential directory (default: `~/.qianwen/credentials` ).

变量名称	描述
`QIANWEN_KEYRING`	设置为 `plaintext` 、 `no` 、 `0` 、 `false` 或 `off` 以退出操作系统钥匙串凭证存储。
`QIANWEN_CREDENTIALS_DIR`	覆盖基于文件的凭证存储目录（默认路径： `~/.qianwen/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

快速概述——三步认证流程

qianwen auth status --format json

→

authenticated: true

→ skip to commands

qianwen auth login --init-only --format json

→ extract

verification_url

→ open in browser

qianwen auth login --complete --format json

→ poll until

success

event

qianwen auth status --format json

→ 返回

authenticated: true

→ 直接执行后续命令

qianwen auth login --init-only --format json

→ 提取

verification_url

→ 在浏览器中打开

qianwen auth login --complete --format json

→ 轮询直到出现

success

事件

Quick check: already logged in?

快速检查：是否已登录？

bash

qianwen auth status --format json

authenticated: true

and token is not expired, skip login entirely.

bash

qianwen 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

qianwen 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

qianwen 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

qianwen 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

qianwen 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

qianwen auth login

The CLI will automatically open the browser and poll until authorization completes.

若Agent运行在TTY环境（如用户终端），只需运行：

bash

qianwen 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

认证命令

qianwen auth status
— Check current authentication state

bash

qianwen auth status --format json

qianwen auth logout
— Revoke session server-side and clear local credentials

bash

qianwen auth logout

qianwen auth status
— 检查当前认证状态

bash

qianwen auth status --format json

qianwen auth logout
— 吊销服务器端会话并清除本地凭证

bash

qianwen auth logout

Usage Commands

使用情况查询命令

qianwen usage summary
— View usage summary (free tier, Token Plan, pay-as-you-go)

bash

qianwen usage summary                      # Current month
qianwen usage summary --period last-month  # Last month
qianwen usage summary --from 2026-03-01 --to 2026-03-31
qianwen usage summary --format json        # JSON output

Period presets:

today

yesterday

week

month

(default),

last-month

quarter

year

YYYY-MM

qianwen usage breakdown
— View model usage breakdown

bash

qianwen usage breakdown --model qwen3.6-plus --days 7
qianwen usage breakdown --model qwen3.5-plus --period 2026-03
qianwen usage breakdown --model qwen-plus --period 2026-03 --granularity month
qianwen usage breakdown --model qwen3.6-plus --format json

qianwen usage free-tier
— View free tier quota details

bash

qianwen usage free-tier
qianwen usage free-tier --format json

qianwen usage payg
— View pay-as-you-go billing details

bash

qianwen usage payg
qianwen usage payg --format json

qianwen usage summary
— 查看使用情况汇总（免费额度、Token Plan、按需付费）

bash

qianwen usage summary                      # 当前月份
qianwen usage summary --period last-month  # 上月
qianwen usage summary --from 2026-03-01 --to 2026-03-31
qianwen usage summary --format json        # JSON格式输出

时间周期预设值：

today

、

yesterday

、

week

、

month

（默认）、

last-month

、

quarter

、

year

、

YYYY-MM

qianwen usage breakdown
— 查看模型使用情况细分

bash

qianwen usage breakdown --model qwen3.6-plus --days 7
qianwen usage breakdown --model qwen3.5-plus --period 2026-03
qianwen usage breakdown --model qwen-plus --period 2026-03 --granularity month
qianwen usage breakdown --model qwen3.6-plus --format json

qianwen usage free-tier
— 查看免费额度详情

bash

qianwen usage free-tier
qianwen usage free-tier --format json

qianwen usage payg
— 查看按需付费账单详情

bash

qianwen usage payg
qianwen 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:

Pattern	When to use	How 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/range	Full 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

单个模型、单个月份、每日详情

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

Single model, last 3 months, monthly summary

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

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

Single model, specific quarter, quarterly rollup

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

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

Single model, this month, daily breakdown

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

qianwen usage breakdown --model qwen3.6-plus --period month

undefined

qianwen 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

qianwen 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

qianwen 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

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

-- Token Plan  ·  Token Plan Team Edition - Standard Seat  ·  生效中-------
Usage:      25K / 25K Credits
Quota Left: 100%
Status:     生效中
Resets:     2026-06-01
--------------------------------------------------------------------------

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

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

-- Token Plan  ·  Token Plan Team Edition - Standard Seat  ·  生效中-------
Usage:      25K / 25K Credits
Quota Left: 100%
Status:     生效中
Resets:     2026-06-01
--------------------------------------------------------------------------

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

Parse the JSON and extract the relevant data for the user's question
Present a human-readable summary — do not dump raw JSON to the user
Add analysis AFTER the summary — clearly separated with
```
---
```

When using
--format text
:

Display CLI output EXACTLY AS-IS — no modification, no reformatting
Preserve all formatting — alignment, spacing, progress bars, separators
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 QianWen usage for April:

**Free Tier**: qwen3.6-plus has 85% remaining (850K / 1M tokens), wan2.6-t2i has 76% remaining (38 / 50 images).
**Token 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推荐模式）：

解析JSON并提取与用户问题相关的数据
展示人类可读的汇总内容——不要直接向用户输出原始JSON
在汇总后添加分析内容——用
```
---
```
清晰分隔

当使用
--format text
：

完全原样展示CLI输出——不修改、不重新格式化
保留所有格式——对齐方式、间距、进度条、分隔线
仅在输出后添加分析内容——用
```
---
```
清晰分隔

禁止操作：

❌ 不做解释直接向用户输出原始JSON
❌ 重新格式化或汇总文本/表格输出
❌ 添加类似“这是你的使用情况：”的前缀
❌ 将文本/表格输出转换为项目符号列表

✅ 正确示例（JSON模式）：

你4月份的QianWen使用情况：

**免费额度**：qwen3.6-plus剩余85%（85万 / 100万tokens），wan2.6-t2i剩余76%（38 / 50张图片）。
**Token Plan（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

退出码

Code	Meaning
0	Success
1	General/usage error
2	Authentication error
3	Network error
4	Configuration error
130	Interrupted

代码	含义
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"):

Run:
```
qianwen version --check
```
Report the result.

The QianWen CLI handles update notifications natively; no additional stderr signal handling is required in this skill.

当用户明确要求检查CLI更新时（例如“检查CLI更新”、“查看CLI版本”、“CLI有新版本吗”）：

运行：
```
qianwen version --check
```
向用户报告结果。

QianWen CLI原生支持更新通知；本技能无需额外处理stderr信号。

Implementation Notes

实现说明

Pay-as-you-go: API returns total usage only (no input/output split)
Token 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
```
qianwen usage summary
```
instead.

按需付费：API仅返回总使用量（不区分输入/输出）
Token Plan：按计划级别汇总请求次数（无模型级细分）
logout：吊销服务器端会话并清除本地凭证（钥匙串+文件）。服务器端调用为尽力而为——本地登出始终成功。
认证：采用OAuth 2.0设备授权码流程+PKCE。凭证优先存储在操作系统钥匙串中， fallback到加密文件存储。
breakdown必须指定--model：与之前的Python实现不同，CLI的细分查询必须指定
```
--model
```
。若要查询所有模型的使用情况，请使用
```
qianwen usage summary
```
。

qianwen-usage

Original

Translation

QianWen Usage

QianWen 使用指南

Prerequisites

前提条件

Environment Variables

环境变量

Authentication Flow (for Agents)

认证流程（适用于Agent）

TL;DR — 3-step auth path

快速概述——三步认证流程

Quick check: already logged in?

快速检查：是否已登录？

Recommended: Two-phase login

推荐：两阶段登录

TTY environments (interactive terminal)

TTY环境（交互式终端）

JSON event structure

JSON事件结构

NEVER:

禁止操作：

Usage

使用方法

Auth Commands

认证命令

Usage Commands

使用情况查询命令

Breakdown Parameters: How to Think About Them

细分参数说明：如何选择参数

Single model, single month, daily detail

单个模型、单个月份、每日详情

Single model, last 3 months, monthly summary

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

Single model, specific quarter, quarterly rollup

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

Single model, this month, daily breakdown

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

Output and Agent Display Rules

输出与Agent展示规则

JSON output example (--format json)

JSON输出示例（--format json）

Text output example (--format text)

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

⚠️ CRITICAL: How to present output to the user

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

Exit Codes

退出码

CLI Update Check

CLI版本检查

Implementation Notes

实现说明

JSON output example (
`--format json`
)

JSON输出示例（
`--format json`
）

Text output example (
`--format text`
)

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