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
Metadata
Release files for sub2api-usage 0.3.21
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sub2api_usage-0.3.21.tar.gz | 28.5 kB | With provenance | Details for sub2api_usage-0.3.21.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sub2api_usage-0.3.21-py3-none-any.whl | Python 3 | none | any | Details for sub2api_usage-0.3.21-py3-none-any.whl |
Total release size: 57.4 kB
Release files / sub2api_usage-0.3.21.tar.gz
| Download URL | sub2api_usage-0.3.21.tar.gz |
|---|---|
| Size | 28.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5e01f316f900c735d4829cf7b7a0b3f9785e279b71c802b69d3e5de89cd014f1
|
|
BLAKE2b-256 checksum How to use checksums |
998769d1e4e5499a5a73778eb561dcce303274ec4a68a32cfa0b68688c6881c7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logRelease files / sub2api_usage-0.3.21-py3-none-any.whl
| Download URL | sub2api_usage-0.3.21-py3-none-any.whl |
|---|---|
| Size | 28.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d67ff8ea4917e34dc96cef12b05d3782362427cd21a2d3dd5ffe12d943399b9e
|
|
BLAKE2b-256 checksum How to use checksums |
8b6659ddcea55999eca5708ec2f882a8a8516c652e5a21bcbab91c02b8d4461c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logSecurity for sub2api-usage 0.3.21
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for sub2api_usage-0.3.21.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 30, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.