sub-cli

subc is a small CLI for Base Router / sub2api OpenAI OAuth account onboarding.

It supports logging in, managing local defaults, generating an OpenAI authorization URL, listing groups/accounts, adding an account from the OAuth callback URL, and reauthorizing an existing OpenAI OAuth account.

Install

npm install -g @jingoz/sub-cli

subc --help

Node.js 20 or newer is required.

Quick Start

subc auth --email [email protected] --password "<password>"
subc gen [email protected]

Open the generated authorization URL, finish the OAuth flow, then copy the callback URL:

subc add "http://localhost:1455/callback?code=..."

Commands

auth

Log in and persist the access/refresh tokens used by later commands:

subc auth --email [email protected] --password "<password>"

Check current authorization status:

subc auth status

auth status refreshes the access token when possible.

config

Show current config:

subc config
subc config list

Set values:

subc config set BASE_URL https://muryorouter.cc/
subc config set PROXY http://127.0.0.1:7890
subc config set PROXY http://user:[email protected]:7890
subc config set PREFER_GROUP 3

Read or unset values:

subc config get BASE_URL
subc config unset PROXY

Supported keys:

| Key | Default | Notes | | --- | --- | --- | | BASE_URL | https://muryorouter.cc/ | Site origin; the CLI appends /api/v1. | | PROXY | unset | Optional HTTP proxy for API requests. | | PREFER_GROUP | unset | Numeric group id used by add when --group is not passed. |

If PROXY contains credentials, config get/list/set redacts them in both human and JSON output. The real value is still stored locally so API requests can use it.

gen

Generate an OpenAI authorization URL and a random three-part English profile name:

subc gen [email protected]
subc gen --email [email protected]

The generated OAuth session is saved locally for add. Saved sessions expire after 30 minutes.

groups

List available OpenAI groups:

subc groups

Use this to find numeric group ids for PREFER_GROUP or add --group.

accounts

List accounts:

subc accounts
subc accounts --page 1 --limit 20
subc accounts --search [email protected]
subc accounts --status active
subc accounts --group 3

accounts --group filters only when the flag is passed. It does not read PREFER_GROUP.

Supported status filters:

• active
• inactive
• error
• rate_limited
• temp_unschedulable
• unschedulable

add

Add an OpenAI OAuth account from the callback URL:

subc add "http://localhost:1455/callback?code=..."
subc add --callback-url "http://localhost:1455/callback?code=..."

When multiple gen sessions exist, select one by email:

subc add --email [email protected] "http://localhost:1455/callback?code=..."

Override the configured preferred group:

subc add --group 3 "http://localhost:1455/callback?code=..."

Group precedence is: explicit add --group first, then configured PREFER_GROUP, then no group. When no group is available, add does not submit group_ids.

New OpenAI OAuth accounts created by add use fixed defaults: concurrency 10, priority 1, model mapping for gpt-5.5, gpt-5.4-mini, and gpt-image-2, plus OpenAI responses WebSocket mode enabled.

reauth

Generate a reauthorization URL for an existing OpenAI OAuth account:

subc reauth gen 123

Open the generated URL, finish OAuth, then apply the callback URL:

subc reauth add "http://localhost:1455/callback?code=..."

When only the callback URL is passed, reauth add uses the latest saved reauth gen account. You can also target an account explicitly:

subc reauth add 123 "http://localhost:1455/callback?code=..."
subc reauth add --account 123 --callback-url "http://localhost:1455/callback?code=..."

JSON Output

All commands support --json:

subc --json auth status
subc accounts --json

Successful JSON output is machine-readable. Errors use this shape:

{
  "ok": false,
  "error": {
    "message": "Email is required.",
    "code": "missing_email"
  }
}

JSON errors are written as a single object to stdout and set a non-zero exit code. Human error text is not mixed into stdout. Error messages and metadata redact access tokens, refresh tokens, passwords, callback authorization codes, and proxy credentials.

Local State

subc stores config, auth tokens, temporary gen sessions, and temporary reauth sessions in one local JSON state file.

Default locations:

• Windows: %APPDATA%\sub-cli\state.json
• macOS: ~/Library/Application Support/sub-cli/state.json
• Linux: ~/.config/sub-cli/state.json

Environment overrides:

• SUBC_CONFIG_DIR
• SUBC_STATE_FILE
• SUBC_CACHE_DIR

SUBC_STATE_FILE overrides the exact state file path. Use it for project-scoped automation so commands do not read or write the default global state.

Subprocess Integration

Automation tools can call subc as a subprocess without importing package internals. Set a project-scoped state file before every call:

SUBC_STATE_FILE=/path/to/project/data/subc-state.json \
SUBC_CACHE_DIR=/path/to/project/data/subc/cache \
subc --json auth status

On Windows PowerShell:

$env:SUBC_STATE_FILE = "D:\project\data\subc-state.json"
$env:SUBC_CACHE_DIR = "D:\project\data\subc\cache"
subc --json auth status

SUBC_CONFIG_DIR is optional. When SUBC_STATE_FILE is set, auth, auth status, config, gen, and add use that state file for config, auth, and saved sessions.

Stable JSON Contracts

subc auth --email <email> --password <password> --json returns:

{
  "ok": true,
  "authenticated": true,
  "user": {}
}

The auth success payload does not include the password, access token, or refresh token.

subc gen <email> --json returns:

{
  "ok": true,
  "email": "[email protected]",
  "authUrl": "https://auth.example/authorize?state=state-1",
  "sessionId": "session-1",
  "state": "state-1",
  "generatedName": "James Mary John",
  "expiresAt": "2026-05-31T00:00:00.000Z"
}

The gen session is saved to the same SUBC_STATE_FILE under that email.

subc add <callbackUrl> --email <email> --group <group> --json returns:

{
  "ok": true,
  "email": "[email protected]",
  "groupId": 3,
  "result": {}
}

add reads the saved gen session from the same SUBC_STATE_FILE. Explicit --group overrides PREFER_GROUP.

JSON errors return:

{
  "ok": false,
  "error": {
    "message": "Email is required.",
    "code": "missing_email",
    "metadata": {}
  }
}

Sensitive metadata is redacted before it reaches stdout. For example, a proxy value with credentials is displayed as http://***:***@127.0.0.1:7890/.