qwencloud-usage

QwenCloud Usage

Query QwenCloud usage, free tier quota, coding plan status, and pay-as-you-go billing.

Prerequisites

qwencloud version

If not installed, run:

npm install -g @qwencloud/qwencloud-cli

Node.js >= 18 required.

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?

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

qwencloud auth login --init-only --format json

On desktop environments with a browser, open the URL for the user:

open "$VERIFICATION_URL"          # macOS
xdg-open "$VERIFICATION_URL"      # Linux
start "" "$VERIFICATION_URL"      # Windows

Step 2 — IMMEDIATELY start polling (do NOT wait for user confirmation):

qwencloud auth login --complete --format json

TTY environments (interactive terminal)

If the agent is running in a TTY (e.g., user's terminal), simply run:

qwencloud auth login

JSON event structure

Both --init-only and --complete output a single JSON document:

{
  "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:

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

qwencloud auth status --format json

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

qwencloud auth logout

Usage Commands

qwencloud usage summary — View usage summary (free tier, coding plan, pay-as-you-go)

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

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

qwencloud usage free-tier
qwencloud usage free-tier --format json

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

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:

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

Classic examples:

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

qwencloud usage summary --period month --format json

Returns structured JSON with three sections:

{
  "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)

qwencloud usage summary --period month --format text

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:

✅ 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

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

qwencloud auth status --format json

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

qwencloud auth logout

Usage Commands

qwencloud usage summary — View usage summary (free tier, coding plan, pay-as-you-go)

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

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

qwencloud usage free-tier
qwencloud usage free-tier --format json

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

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:

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

Classic examples:

# 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

qwencloud version

If not installed, run:

npm install -g @qwencloud/qwencloud-cli

Node.js >= 18 required.

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