@loongphy/codex-auth-linux-x64 0.1.5 → 0.2.0-alpha.1

package/README.md

@@ -1,11 +1,29 @@
 # Codex Auth
 
-![command list](https://github.com/user-attachments/assets/7bbd463b-c5ed-4b90-b1f6-8dfbf21a8944)
+![command list](https://github.com/user-attachments/assets/6c13a2d6-f9da-47ea-8ec8-0394fc072d40)
 
-`codex-auth` is a local-only command-line tool for switching Codex accounts.
+`codex-auth` is a command-line tool for switching Codex accounts.
 
-- It never calls OpenAI APIs; all operations happen locally on your machine.
-- It reads and updates local Codex files under `~/.codex` (including `sessions/` and auth files).
+> [!IMPORTANT]
+> For **Codex CLI** users, after switching accounts, you must fully exit `codex` (type `/exit` or close the terminal session) and start it again for the new account to take effect.
+>
+> If you want seamless automatic account switching without restarting `codex`, use forked [codext](https://github.com/Loongphy/codext), but you need to build it yourself because there is no prebuilt install method yet.
+
+## Supported Platforms
+
+`codex-auth` works with these Codex clients:
+
+- Codex CLI
+- VS Code extension
+- Codex App
+
+For the best experience, install the Codex CLI even if you mainly use the VS Code extension or the App, because it makes adding accounts easier:
+
+```shell
+npm install -g @openai/codex
+```
+
+After that, you can use `codex login` or `codex-auth login` to sign in and add accounts more easily.
 
 ## Install
 
@@ -42,16 +60,44 @@ irm https://raw.githubusercontent.com/loongphy/codex-auth/main/scripts/install.p
   The installer adds the install dir to current/user `PATH` by default.
   Use `-NoAddToPath` to skip user `PATH` persistence.
 
+## Upgrade
+
+If you are upgrading from any `v0.1.x` release to `v0.2.0`, back up these files first to avoid data loss:
+
+- Always back up `~/.codex/auth.json`
+- If you have already used `codex-auth`, also back up `~/.codex/accounts/`
+
+Then complete these steps:
+
+1. Install the latest `v0.2.0` release:
+
+```shell
+npm install -g @loongphy/codex-auth@latest
+```
+
+1. Enable API-based usage refresh if needed (see the Disclaimer for more details):
+
+```shell
+codex-auth config api enable
+```
+
 ## Full Commands
 
 ```shell
 codex-auth list # list all accounts
-codex-auth add [--no-login] # add current account (runs `codex login` by default)
+codex-auth login # run `codex login`, then add the current account
 codex-auth switch [<email>] # switch active account (interactive or partial/fragment match)
 codex-auth import <path> [--alias <alias>] # smart import: file -> single import, folder -> batch import
+codex-auth import --purge [<path>] # rebuild registry.json from auth files for the current version
 codex-auth remove # remove accounts (interactive multi-select)
+codex-auth status # show auto-switch/service/api usage status
+codex-auth config auto enable|disable # manage background auto-switching
+codex-auth config auto --5h <percent> [--weekly <percent>] # configure auto-switch thresholds
+codex-auth config api enable|disable # choose API-only or local-sessions-only usage refresh
 ```
 
+Compatibility note: `codex-auth add` is still accepted as a deprecated alias for `codex-auth login`.
+
 ### Examples
 
 List accounts (default table with borders):
@@ -63,7 +109,7 @@ codex-auth list
 Add the currently logged-in Codex account:
 
 ```shell
-codex-auth add
+codex-auth login
 ```
 
 Import an auth.json backup:
@@ -78,12 +124,21 @@ Batch import from a folder:
 codex-auth import /path/to/auth-exports
 ```
 
+Rebuild `registry.json` from imported auth files:
+
+```shell
+codex-auth import --purge /path/to/auth-exports
+codex-auth import --purge                  # rebuild from ~/.codex/accounts/*.auth.json
+```
+
 Switch accounts (interactive list shows email, 5h, weekly, last activity):
 
 ```shell
-codex-auth switch               # arrow + number input
+codex-auth switch               # arrow + number input, q to quit
 ```
 
+Before the switch picker opens, `codex-auth switch` refreshes the current active account's usage once so the currently selected row is not stale. It does not refresh the newly selected account after the switch completes.
+
 ![command switch](https://github.com/user-attachments/assets/48a86acf-2a6e-4206-a8c4-591989fdc0df)
 
 Switch account non-interactively (for scripts/other CLIs):
@@ -92,10 +147,66 @@ Switch account non-interactively (for scripts/other CLIs):
 codex-auth switch user
 ```
 
-If multiple accounts match, interactive selection is shown.
+If multiple accounts match, interactive selection is shown, and you can press `q` to quit without switching.
 
 Remove accounts (interactive multi-select):
 
 ```shell
 codex-auth remove
 ```
+
+Show current status:
+
+```shell
+codex-auth status
+```
+
+Enable background auto-switching:
+
+```shell
+codex-auth config auto enable
+```
+
+Configure auto-switch thresholds:
+
+```shell
+codex-auth config auto --5h 12
+codex-auth config auto --5h 12 --weekly 8
+```
+
+Use API-only usage refresh:
+
+```shell
+codex-auth config api enable
+```
+
+Use pure local rollout refresh without any API calls:
+
+```shell
+codex-auth config api disable
+```
+
+When auto-switching is enabled, a background worker refreshes the active account's usage from the configured source and silently switches accounts when:
+
+- 5h remaining drops below the configured 5h threshold (default `10%`), or
+- weekly remaining drops below the configured weekly threshold (default `5%`)
+
+Accounts without any usage snapshot are treated as fresh accounts with full quota when ranking candidates.
+On Linux/WSL, background checks run through `systemd --user` as a oneshot service triggered every minute by a timer. On Windows, a user scheduled task runs the same one-shot check every minute. On macOS, the background worker remains long-running.
+Successful foreground `codex-auth` commands also reconcile the managed auto-switch service, so a disabled config removes stale background units while an enabled background worker is refreshed onto the current binary after upgrades or stale service drift.
+Changing thresholds updates `registry.json`; Linux/WSL and Windows pick them up on the next scheduled run, while macOS picks them up on the next polling cycle, without a service restart.
+Changing `config api` updates `registry.json` immediately; `api enable` means API-only and `api disable` means local-sessions-only.
+`codex-auth help` also shows whether auto-switching and usage API calls are currently enabled.
+
+## Disclaimer
+
+This project is provided as-is and use is at your own risk.
+
+**Usage Data Refresh Source:**
+`codex-auth` supports two sources for refreshing account usage/quota information:
+
+1. **Local (default):** Scans local `~/.codex/sessions/*/rollout-*.jsonl` files. This mode is strictly local.
+2. **API:** When `config api enable` is on, the tool will make direct HTTPS requests to OpenAI's endpoints using your account's access token.
+
+**API Call Declaration:**
+By enabling API-based usage refresh, this tool will send your ChatGPT access token to OpenAI's servers (specifically `https://chatgpt.com/backend-api/wham/usage`) to fetch current quota information. This behavior may be detected by OpenAI and could violate their terms of service, potentially leading to account suspension or other risks. The decision to use this feature and any resulting consequences are entirely yours.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loongphy/codex-auth-linux-x64",
-  "version": "0.1.5",
+  "version": "0.2.0-alpha.1",
   "description": "@loongphy/codex-auth binary for linux x64",
   "license": "MIT",
   "repository": {