sub2api-usage
sub2api 后台用量查询的命令行工具。普通模式聚焦统计数据，一屏展示今天、昨天、7 天、30 天的请求数、Token、成本和平均耗时；管理员模式提供账户、用户、订阅等运维视图。
安装
# 推荐：uv tool install (隔离环境)
uv tool install sub2api-usage
# 或者用 pipx
pipx install sub2api-usage
用法
# 首次运行会引导填写账号、密码、后台地址、时区，
# 配置保存到 ~/.config/sub2api-usage/config.json (chmod 600)
# 默认打开统计面板：今天 / 昨天 / 7 天 / 30 天
sub2api-usage
sub2api-usage -p work
sub2api-usage --profile work
# 配置账号：没有 profile 时直接进入新增；已有 profile 时先选择要修改的 profile 或新增
sub2api-usage setup
# 明确新增普通 profile
sub2api-usage profiles add <name>
sub2api-usage profiles list
sub2api-usage profiles use <name>
sub2api-usage profiles remove <name>
# 非交互打印 (脚本 / 管道用)
# 默认一屏打印今天 / 昨天 / 7 天 / 30 天
sub2api-usage print
# 脚本场景也可以只打印单个时段
sub2api-usage print --period week
sub2api-usage print --period month --json
# 检查是否有新版本；交互面板启动时发现新版本会弹窗询问
sub2api-usage update
# 在弹窗中确认后，更新会在后台继续，当前面板可正常使用
# 更新完成后会显示通知，下次启动自动使用新版本
# 也可以根据安装方式手动更新
uv tool upgrade sub2api-usage
pipx upgrade sub2api-usage
python -m pip install --upgrade sub2api-usage
交互面板键位
| 键 | 功能 |
|---|---|
r |
刷新 |
q |
退出 |
普通面板不展示请求明细，只展示统计性质的数据：今天、昨天、最近 7 天、最近 30 天。
单位
数量统一用计算机领域的 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
sub2api-usage admin -p root
sub2api-usage admin --profile root
# 配置管理员账号：没有 admin profile 时直接进入新增；已有时先选择要修改的 profile 或新增
sub2api-usage admin setup
# 明确新增管理员 profile
sub2api-usage admin profiles add <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 窗口利用率、下次重置时间、Codex OAuth 剩余可用重置次数、今日请求 / Token / 成本、当前并发、活跃会话/RPM、最后使用时间。 - Users：用户消费排行，今天 / 昨天 / 7 天 / 30 天 / 全部 五列实际成本并排展示，默认按今日倒序。当前排序列在表头标注
↓或↑，方括号里是该列的快捷键。 - Subscriptions：管理员订阅列表，默认只显示
active，可用S切换状态、o或快捷键切换排序。含用户、分组、状态、日/周/月用量与对应分组限额、到期时间与剩余天数。
License
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
sub2api_usage-0.3.21.tar.gz
(28.5 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file sub2api_usage-0.3.21.tar.gz.
File metadata
- Download URL: sub2api_usage-0.3.21.tar.gz
- Upload date:
- Size: 28.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
5e01f316f900c735d4829cf7b7a0b3f9785e279b71c802b69d3e5de89cd014f1
|
|
| MD5 |
0c4dfd7d85f9124d5930071fd63135b4
|
|
| BLAKE2b-256 |
998769d1e4e5499a5a73778eb561dcce303274ec4a68a32cfa0b68688c6881c7
|
Provenance
The following attestation bundles were made for sub2api_usage-0.3.21.tar.gz:
Publisher:
publish.yml on kadaliao/sub2api-usage
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
sub2api_usage-0.3.21.tar.gz -
Subject digest:
5e01f316f900c735d4829cf7b7a0b3f9785e279b71c802b69d3e5de89cd014f1 - Sigstore transparency entry: 2288127366
- Sigstore integration time:
-
Permalink:
kadaliao/sub2api-usage@daf02ae2195ce5a9d698e33bbac9686dc522ac19 -
Branch / Tag:
refs/tags/v0.3.21 - Owner: https://github.com/kadaliao
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@daf02ae2195ce5a9d698e33bbac9686dc522ac19 -
Trigger Event:
push
-
Statement type:
File details
Details for the file sub2api_usage-0.3.21-py3-none-any.whl.
File metadata
- Download URL: sub2api_usage-0.3.21-py3-none-any.whl
- Upload date:
- Size: 28.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
d67ff8ea4917e34dc96cef12b05d3782362427cd21a2d3dd5ffe12d943399b9e
|
|
| MD5 |
222ef3c1705b9c3aa44bdf8e86b8f287
|
|
| BLAKE2b-256 |
8b6659ddcea55999eca5708ec2f882a8a8516c652e5a21bcbab91c02b8d4461c
|
Provenance
The following attestation bundles were made for sub2api_usage-0.3.21-py3-none-any.whl:
Publisher:
publish.yml on kadaliao/sub2api-usage
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
sub2api_usage-0.3.21-py3-none-any.whl -
Subject digest:
d67ff8ea4917e34dc96cef12b05d3782362427cd21a2d3dd5ffe12d943399b9e - Sigstore transparency entry: 2288127392
- Sigstore integration time:
-
Permalink:
kadaliao/sub2api-usage@daf02ae2195ce5a9d698e33bbac9686dc522ac19 -
Branch / Tag:
refs/tags/v0.3.21 - Owner: https://github.com/kadaliao
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@daf02ae2195ce5a9d698e33bbac9686dc522ac19 -
Trigger Event:
push
-
Statement type:
