Qianwen Usage

QianWenAI Usage

Unified entry point for QianWenAI account, usage, billing, and subscription: auth status, usage summary, free tier quota, Token Plan, pay-as-you-go, billing summary, model cost breakdown, subscription status, order history, team seats, and PAYG spending limit.

Prerequisites

• QianWen CLI must be installed. Verify with:

qianwen version

If not installed, run:

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

Execution Baseline

These rules apply to every command in this skill:

• CLI version baseline: 1.3.0. Before executing, check qianwen version. If the installed version is below 1.3.0, do NOT invoke commands that may be missing (notably the billing and subscription groups); explain that the installed CLI predates the baseline and wait for the user to confirm an upgrade before proceeding. (This is a pre-execution check on every run — distinct from the "CLI Update Check" section below, which only applies when the user explicitly asks about CLI updates.)
• Whitelist only. Only run the commands and parameters documented in this file. Never concatenate arbitrary shell strings or pass unchecked user input into command lines.
• Uniform result states. Map every command result to one of five states: success / partial / empty / confirmation_required / error. Never fill in missing or failed results with mock data — report what actually happened.
• URLs from CLI output only. Only present URLs returned by the CLI (e.g., verification_url). Never fabricate a URL from a name or a guess.

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. qianwen auth status --format json → authenticated: true → skip to commands
2. qianwen auth login --init-only --format json → extract verification_url → open in browser
3. qianwen auth login --complete --format json → poll until success event

Quick check: already logged in?

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

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:

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

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

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

TTY environments (interactive terminal)

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

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

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

qianwen auth status — Check current authentication state

qianwen auth status --format json

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

⚠️ Confirmation required: logout is destructive to the current session. Always ask the user to confirm first (confirmation_required state); only run the command after explicit confirmation.

qianwen auth logout

Usage Commands

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

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

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

Note: breakdown shows PAYG consumption only. Free tier usage is not included — use usage free-tier for current quota state.

qianwen usage free-tier — View free tier quota details

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

qianwen usage payg — View pay-as-you-go usage and costs by model

Shows pay-as-you-go consumption for the current period. For historical billing cycles, use qianwen billing summary (see Billing Commands below).

qianwen usage payg
qianwen usage payg --format json
qianwen usage payg --period month --format json   # Recommended: current month PAYG

qianwen usage logs — Browse paginated call logs (per-request history), filterable by time, model, and status

Use this for request-level questions — "which calls failed?", "show me the 4xx/5xx errors", "how long did those requests take?", "which models did I call recently?", "look up this request id". This is distinct from usage summary/breakdown (aggregate token/cost) — route failure-diagnosis, latency, and call-history questions here, not to summary/breakdown.

qianwen usage logs --period 7d --format json
qianwen usage logs --period 24h --status 4xx --status 5xx --format json   # recent client/server errors
qianwen usage logs --model qwen-plus --page 2 --page-size 50 --format json
qianwen usage logs --from 2026-07-25 --to 2026-08-07 --format json         # explicit range (must be ≤ 14 days)
qianwen usage logs --request-id 8c81644f-... --format json                # exact lookup

Options:

• --from / --to — date range (YYYY-MM-DD or RFC3339)
• --period <preset> — 1h, 24h, 7d, today, yesterday, week, month, … (same preset family as usage summary). ⚠️ The resolved range must be ≤ 14 days. Presets like month (after mid-month), last-month, quarter, and year will exceed the limit and return INVALID_ARGUMENT. Prefer short presets: 1h, 24h, 7d, today, yesterday, week.
• --model <id> — filter by model; repeatable (pass multiple --model flags to include several models)
• --status <type> — status filter: 0 (cancelled), 2xx (success), 4xx (client error), 5xx (server error); repeatable
• --request-id <id> — exact request id; when set, all other filters are ignored
• --page <n> (default 1) / --page-size <n> (1..100)

⚠️ 14-day range limit: the resolved time range must be ≤ 14 days. Any range wider than 14 days (whether via --from/--to or a long --period) returns INVALID_ARGUMENT (exit 4, "Time range cannot be longer than 14 days."). To scan a longer history, slide a ≤14-day window with successive --from/--to calls. This differs from usage summary/breakdown, which accept multi-month ranges.

Pagination: results are paged. To walk the full history within a window, start at --page 1 --page-size 100, then keep incrementing --page while page × pageSize < totalCount, until all totalCount entries are retrieved.

JSON structure (per CLI source — top-level totalCount / page / pageSize / period / items; within items[], errorCode is present only for failed calls, and usages carries the per-request token/character consumption and is empty for failed/cancelled calls):

{
  "totalCount": 4,
  "page": 1,
  "pageSize": 20,
  "period": { "from": "2026-07-25", "to": "2026-08-07" },
  "items": [
    { "requestId": "8c81644f-...", "model": "wan3.0-video", "statusCode": 403, "durationMs": 548, "errorCode": "Forbidden.NoPermission", "usages": [] },
    { "requestId": "8e3a2c02-...", "model": "qwen3.8-max", "statusCode": 200, "durationMs": 956, "usages": [ { "type": "tokens", "total": 1820 } ] }
  ]
}

period.from / period.to echo the resolved window: calendar presets and explicit --from/--to dates render as YYYY-MM-DD, while rolling presets (1h, 24h, 7d) render as RFC3339 timestamps. When no calls match, the CLI returns totalCount: 0 with an empty items: [] — map this to the empty state (not an error).

Fields: requestId (correlate with server-side traces), model, statusCode (HTTP-style code — 2xx success, 4xx client error, 5xx server error, 0 cancelled), durationMs (call latency), errorCode (failure reason, present only on non-2xx), usages (per-request consumption; empty for failed/cancelled calls). Use statusCode + errorCode for failure triage and durationMs for latency analysis.

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:

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:

# Single model, single month, daily detail
qianwen usage breakdown --model qwen3.5-plus --period 2026-03

# Single model, last 3 months, monthly summary
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

Billing Commands

qianwen billing summary — Bill totals for an inclusive YYYY-MM cycle window

qianwen billing summary --from 2026-05 --to 2026-07 --format json
qianwen billing summary --charge-type payg --format json   # payg | subscription | all (default)

cycles covers every month in the --from..--to window, in order, with no gaps. Each cycle carries billingCycle, aftertaxAmount, and a settled flag. chargeType is the internal value — all, prepaid for subscription, postpaid for payg; amounts are decimal strings.

If settled appears in the JSON output, it indicates whether bill data exists for that cycle (true = exists, false = none). When true, report aftertaxAmount as a real amount (including ¥0).

{
  "period": { "from": "2026-05", "to": "2026-08" },
  "chargeType": "all",
  "currency": "CNY",
  "cycles": [
    { "billingCycle": "202605", "aftertaxAmount": null, "settled": false },
    { "billingCycle": "202606", "aftertaxAmount": "3.710000", "settled": true },
    { "billingCycle": "202607", "aftertaxAmount": null, "settled": false },
    { "billingCycle": "202608", "aftertaxAmount": "0.000000", "settled": true }
  ],
  "totals": { "aftertaxAmount": "3.71" }
}

qianwen billing breakdown — Top-N consumption by model (or API key)

qianwen billing breakdown --period month --group-by model --top 10 --format json
qianwen billing breakdown --group-by api-key --top 10 --format json

Options: --group-by model|api-key (default model), --top <n> (default 10, max 100), --granularity day|month (default month), --charge-type all|subscription|payg, plus --period / --from / --to date range. Day granularity requires a range ≤ 31 days; month granularity ≤ 12 months.

JSON structure for a single-period query (per CLI source, the raw ConsumeBreakdown object):

{
  "groupBy": "model",
  "period": { "from": "2026-07-01", "to": "2026-07-29" },
  "chargeType": "all",
  "rows": [
    { "groupKey": "qwen3.6-plus", "groupLabel": "qwen3.6-plus", "amount": "5.20" },
    { "groupKey": "qwen-plus", "groupLabel": "qwen-plus", "amount": "1.80" }
  ],
  "totalRows": 12,
  "totalAmount": "9.80",
  "currency": "CNY"
}

When the range spans multiple periods (e.g. several months), the JSON is instead sliced per period: { "groupBy", "dateRange": { "from", "to" }, "granularity", "chargeType", "slices": [ { "period", "rows", "totalAmount" } ], "currency" }.

qianwen billing limit — Pay-as-you-go consumption limit and alert configuration

qianwen billing limit --format json

Read-only — this command only displays the PAYG spending limit; the CLI does not support modifying it. Direct users to the console for changes.

JSON structure (per CLI source, the raw UsageLimit object; limitAmount may be null when no limit is set):

{
  "status": "normal",
  "limitAmount": "500.00",
  "currency": "CNY",
  "alertThreshold": "80"
}

status values: normal / active / exceeded / warning / unknown.