shusub2/README.md

shusub2

Terminal UI for the token-safe Sub2API account feed exposed by cliproxy-codex-quota.

Quick Start

Run once from a public Git repo with uvx:

uvx --from git+https://gitea.shujk.top/shujakuin/shusub2.git shusub2 \
  --api-url https://codex.server2.shujk.top/1232131231313123/api/tui/accounts

Bootstrap a new machine from uvx: save the API URL, install shusub2 as a user command, then run it later as shusub2:

uvx --from git+https://gitea.shujk.top/shujakuin/shusub2.git shusub2 \
  --api-url https://codex.server2.shujk.top/1232131231313123/api/tui/accounts \
  --install
shusub2

Install as a user command:

uv tool install git+https://gitea.shujk.top/shujakuin/shusub2.git
shusub2 --api-url https://codex.server2.shujk.top/1232131231313123/api/tui/accounts --save-config

Configure the default public API URL for shusub2:

mkdir -p ~/.config/shusub2
chmod 700 ~/.config/shusub2
printf '%s\n' 'https://codex.server2.shujk.top/1232131231313123/api/tui/accounts' > ~/.config/shusub2/api-url
chmod 600 ~/.config/shusub2/api-url
shusub2

Environment variables override the config file:

• SHUSUB2_API_URL
• SUB2API_QUOTA_TUI_API_URL
• SHUSUB2_API_URL_FILE
• SHUSUB2_STATUS_URL
• SHUSUB2_STATUS_URL_FILE
• SHUSUB2_VERSION_CHECK_URL
• SHUSUB2_VERSION_CHECK_TIMEOUT
• SHUSUB2_NO_VERSION_CHECK

Local Development

cd apps/sub2api-quota-tui
uv run shusub2

Run inside zellij:

zellij action new-pane --name sub2api-quota -- \
  bash -lc 'cd /home/shujakuin/infra/apps/sub2api-quota-tui && uv run shusub2'

Configuration:

• --api-url / SUB2API_QUOTA_TUI_API_URL
• --status-url / SHUSUB2_STATUS_URL
• --save-config
• --install
• --refresh-seconds / SUB2API_QUOTA_TUI_REFRESH_SECONDS
• --timeout / SUB2API_QUOTA_TUI_TIMEOUT

The TUI reads /api/tui/accounts and can optionally read sub2api-status /api/status for channel monitor health. It does not need SSH, database access, API keys, OAuth credentials, or plaintext env files.

When --status-url is omitted, shusub2 infers a sibling /api/status URL from account URLs ending in /api/tui/accounts, so the public Codex endpoint automatically enables monitor availability. On startup it also checks the public Gitea repo for a newer package version and prints a short upgrade hint when one is available.

Columns are ordered for scanning inside zellij:

Name | Provider | Group | Daily | Today | Tokens | Req | Kind | 5h | 7d | Reset | Status | Availability

Provider distinguishes openai and anthropic accounts from the public platform field returned by the API.

Daily is shown as used/limit when Sub2API has quota_daily_* fields in accounts.extra; otherwise it is -.

Group is the derived Sub2API tier alias group. Higher tiers win when multiple aliases exist: id < slow < fast < sfast. The table shows sfast first, then fast, slow, id, and ungrouped accounts.

When --status-url is configured, the status line shows channel monitor health, and the selected account detail shows the matching monitor status when one exists. Monitor binding first uses the shared base_url_hash emitted by the account API and sub2api-status; name-token matching remains only as a fallback for older status payloads.

Availability is derived from the bound channel monitor. Accounts without a matching monitor show -.