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，openai 平台已取消 5h 限制、不显示) 与 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.19.tar.gz
(26.9 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.19.tar.gz.
File metadata
- Download URL: sub2api_usage-0.3.19.tar.gz
- Upload date:
- Size: 26.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
465e390915b0c1e8de47def77f02ef61a2a3e8afb82ff604dc492db6e0ffa926
|
|
| MD5 |
fe121a6809371226e0777d05378d98b2
|
|
| BLAKE2b-256 |
623bfe250df7abeec7ea5de2c6064b0df28c7de92cf107f61cb8c3bf6de1ceba
|
Provenance
The following attestation bundles were made for sub2api_usage-0.3.19.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.19.tar.gz -
Subject digest:
465e390915b0c1e8de47def77f02ef61a2a3e8afb82ff604dc492db6e0ffa926 - Sigstore transparency entry: 2194737880
- Sigstore integration time:
-
Permalink:
kadaliao/sub2api-usage@efebb04efe3faa6cabf797dade95754a08108b4f -
Branch / Tag:
refs/tags/v0.3.19 - Owner: https://github.com/kadaliao
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@efebb04efe3faa6cabf797dade95754a08108b4f -
Trigger Event:
push
-
Statement type:
File details
Details for the file sub2api_usage-0.3.19-py3-none-any.whl.
File metadata
- Download URL: sub2api_usage-0.3.19-py3-none-any.whl
- Upload date:
- Size: 27.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
777d0e3f0001896e305e3ae06ecefec43ee4a9baacc970db8c1bcfc78f5c22c4
|
|
| MD5 |
5e61d7b28766c535e48e7871412351e2
|
|
| BLAKE2b-256 |
88823de73dbad8aa763c4340ed0b3699643fef606c1861b182f2e2fa719a392d
|
Provenance
The following attestation bundles were made for sub2api_usage-0.3.19-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.19-py3-none-any.whl -
Subject digest:
777d0e3f0001896e305e3ae06ecefec43ee4a9baacc970db8c1bcfc78f5c22c4 - Sigstore transparency entry: 2194737887
- Sigstore integration time:
-
Permalink:
kadaliao/sub2api-usage@efebb04efe3faa6cabf797dade95754a08108b4f -
Branch / Tag:
refs/tags/v0.3.19 - Owner: https://github.com/kadaliao
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@efebb04efe3faa6cabf797dade95754a08108b4f -
Trigger Event:
push
-
Statement type:
