qianwen-usage

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: qianwen-usage
description: "Manage account auth and query usage/billing/subscription. Use for: login, logout, check usage, view billing, free tier quota, Token Plan status, pay-as-you-go costs, billing summary, model cost breakdown, call logs (which requests failed, 4xx/5xx errors, request latency, recent models called, request-id lookup), subscription status, order history, team seats, PAYG spending limit. Skip for: model browsing, payment/recharge (use qianwen-payment), non-account tasks."
---

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

```bash
qianwen version
```

If not installed, run:

```bash
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?

```bash
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):**
```bash
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:
```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
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:
```bash
qianwen auth login
```
The CLI will automatically open the browser and poll until authorization completes.

### JSON event struct