QianWen CLI

千问AI平台官方命令行工具。在终端或 AI Agent 运行时中，发现模型、查看用量、管理认证与诊断本地环境。

中文 · English

功能特性

• 交互模式与一次性命令：不带参数运行 qianwen 进入 REPL，传递命令则适用于脚本、CI 和 Agent 工具。
• 模型调用命令族：通过 chat、image、video、audio、model3d、music 与 task 直接调用对话、图像、视频、语音、3D 与音乐模型，支持流式输出、文件落盘和异步任务查询。
• Agent 友好协议：命令支持 --format json、标准化退出码、可解析的 JSON 错误信息，以及 --quiet 仅返回退出码。
• 模型与用量工作流：浏览模型、查看模型详情、按关键词搜索，以及查看免费额度、Token Plan 和按量计费用量。
• 技能发现与安装：通过 skills search 搜索 技能市场 技能，通过 skills install 安装到本地目录，无需登录即可使用。
• 云栖大会活动：通过 yunqi 浏览大会论坛与展商信息，订阅感兴趣的论坛，并查看订阅状态与会议纪要。
• 原生凭证存储：凭证存储在操作系统钥匙串中（可用时），并支持加密文件回退。无需 keytar 或原生 Node 绑定。
• 自文档化命令树：每个命令均支持 --help，生成的帮助信息即为权威语法参考。

安装

npm

npm install -g @qianwenai/qianwen-cli

验证安装：

qianwen version

若出现 command not found: qianwen，说明 npm 全局 bin 目录未加入 PATH。执行对应 shell 的命令即可：

| Shell | 命令 | | ----- | ------------------------------------------------------------------------------------------ | | bash | echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc | | zsh | echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc |

从源码构建

git clone https://github.com/QianWen-AI/qianwen-cli.git
cd qianwen-cli
pnpm install
pnpm run build
pnpm link --global

验证安装：

qianwen version

快速开始

开发者

# 1. OAuth Device Flow 登录
qianwen auth login

# 2. 列出可用模型
qianwen models list

# 3. 查看模型详情
qianwen models info qwen3-coder-plus

# 4. 查看当前用量
qianwen usage summary

# 5. 搜索并安装技能
qianwen skills search 部署
qianwen skills install @qianwen-ai/qianwen-find-skills

# 6. 诊断认证、网络、配置和本地环境
qianwen doctor

不带参数运行 qianwen 将进入 REPL。REPL 使用与一次性模式相同的命令树，并支持 readline 历史、Tab 补全和丰富的终端表格。

AI Agent

使用一次性命令并显式请求 JSON 输出：

qianwen auth status --format json
qianwen models list --all --format json
qianwen usage summary --period month --format json
qianwen skills search deploy --limit 5 --format json
qianwen doctor --format json

推荐的 Agent 启动流程：

# 1. 检查凭证是否可用
qianwen auth status --format json

# 2. 如果认证缺失或过期，初始化非交互式登录
qianwen auth login --init-only --format json

# 3. 让用户打开返回的验证 URL，然后完成轮询
qianwen auth login --complete --format json

示例

浏览可用模型，查看模态信息、免费额度和定价：

一站式查看免费额度、Token Plan 和按量计费用量：

需要选择仍有试用容量的模型时，查看免费额度详情：

运行诊断，验证认证、网络访问、配置和 Shell 补全：

命令

| 领域 | 命令 | 常用标志 | | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 模型调用 | chat create, image generate, video generate, audio transcribe, audio speech, model3d generate, music generate, task get | --model, --stream, --size, --image, --voice, --out, --no-wait, --timeout, --request, --api-key, --format | | 认证 | auth login, auth logout, auth status | --init-only, --complete, --timeout, --format | | 模型 | models list, models info, models search | --input, --output, --all, --verbose, --page, --per-page, --format | | 用量 | usage summary, usage breakdown, usage free-tier, usage payg, usage logs | --period, --from, --to, --days, --model, --granularity, --format | | 账单 | billing summary, billing breakdown, billing limit, billing balance summary, billing balance recharge, billing balance recharge-history | --from, --to, --period, --group-by, --granularity, --channel, --amount, --range, --start-time, --end-time, --page, --page-size, --format | | 业务空间 | workspace list, workspace limit | --format | | 订阅 | subscription status, subscription orders, subscription tokenplan status, subscription tokenplan seats | --format | | 云栖大会 | yunqi list forums, yunqi list exhibitors, yunqi list subscriptions, yunqi list summaries, yunqi subscribe forum, yunqi unsubscribe forum | --page, --page-size, --forum-id, --keyword, --format | | 文档 | docs search, docs view | --format | | 技能 | skills search, skills install, skills pack-install | --limit, --dir, --format | | 工单 | support list, support view, support create, support reply, support close, support rate | --format | | 配置 | config list, config get, config set, config unset | --format | | 诊断 | doctor | --format | | Shell | completion install, completion generate | --shell | | 版本 | version | --check |

使用帮助查看完整语法：

qianwen --help
qianwen models --help
qianwen usage breakdown --help

输出与退出码

输出格式解析优先级：

1. --format 标志
2. 配置中的 output.format
3. TTY 检测：交互终端使用表格，管道或重定向使用 JSON

qianwen models list
qianwen models list --format json
qianwen models list --format text
qianwen --quiet doctor

退出码：

| 代码 | 含义 | | ----: | ------------------ | | 0 | 成功 | | 1 | 通用错误或用法错误 | | 2 | 认证错误 | | 3 | 网络错误 | | 4 | 配置错误 | | 130 | 中断 |

JSON 错误遵循稳定格式：

{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "未认证。请先运行 `qianwen auth login`。",
    "exit_code": 2
  }
}

自动化场景建议使用 --format json，表格输出仅供人工阅读。

JSON 输出示例：

{
  "models": [
    {
      "id": "qwen3-coder-plus",
      "modality": { "input": ["text"], "output": ["text"] },
      "pricing": { "tiers": [{ "input": 0.5, "output": 2.0, "unit": "CNY/1M tokens" }] }
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

认证

qianwen auth login 使用 OAuth 2.0 Device Authorization Grant with PKCE。

交互式登录：

qianwen auth login

非交互式登录：

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

凭证存储在操作系统钥匙串中（可用时）。如果钥匙串不可用，CLI 会回退到加密的本地凭证文件。设置 QIANWEN_KEYRING=plaintext 强制使用明文文件存储（调试用）；no、0、false 和 off 也会跳过钥匙串。

技能

skills 命令用于从 技能市场 发现并安装技能，无需登录。

# 按关键词搜索技能
qianwen skills search 部署
qianwen skills search deploy --limit 5

# 按完整 slug 安装技能，默认安装到当前目录下的 skill-name/ 单级目录
qianwen skills install @qianwen-ai/qianwen-find-skills

# 安装到指定目录（目录须已存在且可写）
qianwen skills install @qianwen-ai/qianwen-find-skills --dir ~/.qoder/skills

# 通过包名安装包内所有技能
qianwen skills pack-install qianwen-forge-pack

安装会自动识别全新安装、升级和已是最新三种情况。非 CLI 管理的同名目录不会被覆盖。

配置

QianWen CLI 使用一个全局配置文件：

~/.qianwen/config.json

公开配置项：

| 键 | 值 | 默认 | | --------------- | ------------------------------- | ------ | | output.format | auto, table, json, text | auto |

qianwen config set output.format json
qianwen config get output.format
qianwen config list
qianwen config unset output.format

贡献

我们欢迎修复、文档改进和功能提议。

1. 从最新的 master 分支开始。
2. 创建一个聚焦的分支，例如 fix/auth-token-expiry 或 doc/install-options。
3. 使用 pnpm install 安装依赖。
4. 进行修改，并在行为变更时添加或更新测试。
5. 在提交 PR 之前运行相关检查：

pnpm run lint
pnpm run format:check
pnpm test
pnpm run build

6. 使用 Conventional Commits 提交，如 feat:、fix:、doc:、refactor: 和 chore:。
7. 推送分支并向 master 发起 Pull Request。
8. 填写 PR 模板，关联相关 Issue，描述用户可见变更，CLI UX 变更需附截图或终端输出。

面向产品的变更应包含文档更新，并需要产品和工程评审。

许可证

本项目基于 Apache-2.0 许可证 授权。