Sub2API Account Cleaner

Local CLI + GUI for scanning and safely deleting exhausted sub2api account records from your own deployed instance.

It does not touch your server, domain, or IDC panel. It only operates on sub2api admin account records through the REST API.

GUI preview

Highlights

• Scans openai/oauth accounts whose 7-day Codex window is fully exhausted
• Revalidates each candidate immediately before deletion
• Writes sanitized backups outside the repo by default
• Ships with both a terminal CLI and a local browser GUI
• Includes automated tests and GitHub Actions CI

What it does

• Logs into your sub2api admin account with POST /api/v1/auth/login
• Pulls all accounts from GET /api/v1/admin/accounts
• Selects deletion candidates with this fixed rule:
  • platform === "openai"
  • type === "oauth"
  • codex_7d_used_percent >= 100
  • the 7-day reset time is still in the future
• Requires a fresh usage snapshot before a record can qualify for deletion
• In delete mode, writes a sanitized JSON backup first, then re-fetches and re-checks each candidate before issuing DELETE /api/v1/admin/accounts/:id

Requirements

• Node.js 20+
• A sub2api admin account
• Network access to your deployed sub2api instance

Environment variables

export SUB2API_BASE_URL="https://example-sub2api.com"
export SUB2API_EMAIL="admin@example.com"
export SUB2API_PASSWORD="your-password"

Optional flags:

• --json
• --page-size 100
• --backup-dir /path/to/backups
• --base-url https://example.com
• --email admin@example.com

Quick start

npm install
npm run scan -- --json

Commands

Preview only:

npm run scan

Machine-readable preview:

npm run scan -- --json

Delete matched accounts:

npm run delete -- --confirm

Delete with JSON output:

npm run delete -- --confirm --json

GUI

Start the local GUI:

npm run gui

Then open:

http://127.0.0.1:43123

The GUI talks only to the local helper server, which then proxies requests to your configured sub2api instance.

Backups

• Delete mode creates a sanitized backup before deleting anything.
• Backups are written to ~/.sub2api-cleaner/backups/sub2api-accounts-YYYYMMDDHHmmss.json by default.
• Use --backup-dir /path/to/backups if you want an explicit location.
• If zero accounts match, no backup file is created.

Safety notes

• npm run scan never deletes anything.
• npm run delete without --confirm is rejected.
• Delete mode re-fetches each candidate before deleting it; if it no longer qualifies, it is reported as skipped.
• The backup is intentionally sanitized and does not include raw credentials or tokens.

Development

Run the test suite:

npm test