Metadata-Version: 2.4
Name: sub2api-usage
Version: 0.3.0
Summary: Interactive TUI for querying sub2api backend usage stats (Claude / OpenAI / Gemini)
Project-URL: Repository, https://github.com/kadaliao/sub2api-usage
Project-URL: Issues, https://github.com/kadaliao/sub2api-usage/issues
Author-email: Kada Liao <kadaliao@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: claude,cli,gemini,openai,sub2api,tui,usage
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: textual>=0.60
Description-Content-Type: text/markdown

# sub2api-usage

[![CI](https://github.com/kadaliao/sub2api-usage/actions/workflows/ci.yml/badge.svg)](https://github.com/kadaliao/sub2api-usage/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/sub2api-usage.svg)](https://pypi.org/project/sub2api-usage/)
[![Python](https://img.shields.io/pypi/pyversions/sub2api-usage.svg)](https://pypi.org/project/sub2api-usage/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

[sub2api](https://github.com/Wei-Shaw/sub2api) 后台用量查询的命令行工具。终端里直接看请求数、Token、成本、明细，支持今天 / 7 天 / 30 天 / 全部切换。

## 安装

```bash
# 推荐：uv tool install (隔离环境)
uv tool install sub2api-usage

# 或者用 pipx
pipx install sub2api-usage

# 或者直接 pip
pip install sub2api-usage
```

## 用法

```bash
# 首次运行会引导填写账号、密码、后台地址、时区，
# 配置保存到 ~/.config/sub2api-usage/config.json (chmod 600)
sub2api-usage

# 重新配置账号
sub2api-usage setup

# 非交互打印 (脚本 / 管道用)
sub2api-usage print
sub2api-usage print --period week --list --page-size 20
sub2api-usage print --period month --json
```

### 交互面板键位

| 键 | 功能 |
| --- | --- |
| `1` / `2` / `3` / `4` | 今天 / 7 天 / 30 天 / 全部 |
| `←` / `→` | 在标签间切换 |
| `n` / `p` | 下一页 / 上一页 |
| `r` | 刷新 |
| `q` | 退出 |

数据拉取时表格会显示加载指示器，避免误以为卡死。

### 单位

数量统一用计算机领域的 K/M/G/T，耗时按 ms/s/min/h/d 自动选择最适合的尺度。

## 管理员模式

如果你的账号在 sub2api 后端有 `role=admin`，可以用 `admin` 子命令查看上游账户用量窗口/配额、平台用户消费排行、用户订阅（每日/每周/每月用量与到期时间）等。管理员凭据保存在 `~/.config/sub2api-usage/config.json` 的 `admin_profiles` 命名空间，与普通账号互不影响。

```bash
# 首次运行会引导填写管理员邮箱/密码，登录后会校验 role=admin
sub2api-usage admin

# 配置 / 新增管理员 profile
sub2api-usage admin setup [name]

# 非交互打印
sub2api-usage admin print --view dashboard
sub2api-usage admin print --view accounts --json
sub2api-usage admin print --view users
sub2api-usage admin print --view users --sort-by week
sub2api-usage admin print --view subscriptions --json
sub2api-usage admin print --view subscriptions --status all --sort-by monthly_usage

# 管理 admin profile
sub2api-usage admin profiles list
sub2api-usage admin profiles use <name>
sub2api-usage admin profiles remove <name>
```

### 管理员面板键位

通用：

| 键 | 功能 |
| --- | --- |
| `d` / `a` / `u` / `s` | 切到 Dashboard / 上游账户 / 用户排行 / 订阅管理 |
| `r` | 刷新 |
| `q` | 退出 |

Dashboard / Accounts 视图：

| 键 | 功能 |
| --- | --- |
| `1` / `2` / `3` / `4` / `5` | 切换时段：今天 / 昨天 / 7 天 / 30 天 / 全部 |

Users 视图（多时段并排展示，按当前列倒序）：

| 键 | 功能 |
| --- | --- |
| `1` / `2` / `3` / `4` / `5` | 按今天 / 昨天 / 7 天 / 30 天 / 全部 倒序 |
| `e` | 按邮箱升序 |
| `o` | 排序键循环 |

Subscriptions 视图：

| 键 | 功能 |
| --- | --- |
| `1` / `3` / `4` | 按日 / 周 / 月用量倒序 |
| `e` / `i` / `x` | 按邮箱 / ID / 到期升序 |
| `S` | 状态过滤循环：active → expired → paused → all |
| `o` | 排序键循环 |

数据拉取时当前视图会显示加载指示器，避免误以为卡死。

### 视图

- **Dashboard**：今日 / 累计请求与成本、用户数、上游账户分类计数 (正常/异常/限流/过载)、RPM/TPM、平均耗时、运行时长，以及当前时段模型 Top。
- **Accounts**：所有上游账户列表，含 5h 窗口 (`current_window_cost` / `window_cost_limit`)、日/周 Quota (`quota_daily/weekly_*`)、今日请求 / Token / 成本、当前并发、活跃会话/RPM、最后使用时间。
- **Users**：用户消费排行，**今天 / 昨天 / 7 天 / 30 天 / 全部** 五列实际成本并排展示，默认按今日倒序。当前排序列在表头标注 `↓` 或 `↑`，方括号里是该列的快捷键。
- **Subscriptions**：管理员订阅列表，默认只显示 `active`，可用 `S` 切换状态、`o` 或快捷键切换排序。含用户、分组、状态、日/周/月用量与对应分组限额、到期时间与剩余天数。

## License

[MIT](LICENSE)
