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

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