qwencloud-usage

What this skill does

# 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": 4