qwencloud-usage

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:

qwencloud version

If not installed, run:

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

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

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:

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

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:

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:

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

qwencloud auth status --format json

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

Usage Commands

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

Period presets: today, yesterday, week, month (default), last-month, quarter, year, YYYY-MM

qwencloud usage breakdown — View model usage breakdown

qwencloud usage free-tier — View free tier quota details

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

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:

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)

Returns structured JSON with three sections:

Text output example (--format text)

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

✅ CORRECT (Text mode):

❌ WRONG:

Exit Codes

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.