sub2api-usage 0.3.8

Interactive TUI for querying sub2api backend usage stats (Claude / OpenAI / Gemini)

sub2api-usage

sub2api 后台用量查询的命令行工具。终端里直接看请求数、Token、成本、明细，默认展示今天，支持今天 / 7 天 / 30 天 / 全部切换。

安装

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

# 或者用 pipx
pipx install sub2api-usage

# 或者直接 pip
pip install sub2api-usage

用法

# 首次运行会引导填写账号、密码、后台地址、时区，
# 配置保存到 ~/.config/sub2api-usage/config.json (chmod 600)
# 默认打开今天视图
sub2api-usage

# 重新配置账号
sub2api-usage setup

# 非交互打印 (脚本 / 管道用)
# 默认打印今天；用 --period week 可看最近 7 天
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 命名空间，与普通账号互不影响。

# 首次运行会引导填写管理员邮箱/密码，登录后会校验 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	排序键循环
/	搜索当前表格，底部状态栏以 /关键字 输入并高亮匹配数据；Enter 完成，Esc 清除

Subscriptions 视图：

键	功能
1 / 3 / 4	按日 / 周 / 月用量倒序
e / i / x	按邮箱 / ID / 到期升序
S	状态过滤循环：active → expired → paused → all
o	排序键循环
/	搜索当前表格，底部状态栏以 /关键字 输入并高亮匹配数据；Enter 完成，Esc 清除

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

视图

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

License

MIT