back
loading skill details...
[QwenCloud] Manage account auth and query usage/billing. Use for: login, logout, check usage, view billing, free tier quota, coding plan status, pay-as-you-g...
---
name: qwencloud-usage
description: "[QwenCloud] Manage account auth and query usage/billing. Use for: login, logout, check usage, view billing, free tier quota, coding plan status, pay-as-you-go costs. Skip for: model browsing, non-account tasks."
---
# QwenCloud Usage
Query QwenCloud usage, free tier quota, coding plan status, and pay-as-you-go billing.
## 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).
### Environment Variables
| Variable | Description |
|-----------------------------|----------------------------------------------------------------------------------------------|
| `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`). |
## Authentication Flow (for Agents)
The CLI auto-detects non-TTY environments and degrades safely — no wrapper script needed.
### 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
### Quick check: already logged in?
```bash
qwencloud auth status --format json
```
If `authenticated: true` and token is not expired, skip login entirely.
### 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
### TTY environments (interactive terminal)
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.
### JSON event structure
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`.
### 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)
## 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.
### 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
```
### 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
```
### 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
# Single model, single month, daily detail
qwencloud usage breakdown --model qwen3.5-plus --period 2026-03
# Single model, last 3 months, monthly summary
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
# Single model, this month, daily breakdown
qwencloud usage breakdown --model qwen3.6-plus --period month
```
## Output and Agent Display Rules
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.
### JSON output example (`--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" }
}
}
```
### Text output example (`--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
```
### ⚠️ 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)
```
## Exit Codes
| Code | Meaning |
|------|----------------------|
| 0 | Success |
| 1 | General/usage error |
| 2 | Authentication error |
| 3 | Network error |
| 4 | Configuration error |
| 130 | Interrupted |
## CLI Update Check
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.
## 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.
don't have the plugin yet? install it then click "run inline in claude" again.