@loongphy/codex-auth 0.2.1 → 0.2.2-alpha.2

package/README.md

@@ -27,7 +27,7 @@ After that, you can use `codex login` or `codex-auth login` to sign in and add a
 
 ## Install
 
-- npm:
+Install with npm:
 
 ```shell
 npm install -g @loongphy/codex-auth
@@ -41,69 +41,144 @@ npx @loongphy/codex-auth list
 
   npm packages currently support Linux x64, macOS x64, macOS arm64, and Windows x64.
 
-- Linux/macOS/WSL2:
+> [!NOTE]
+> Older Bash/PowerShell GitHub-release installs could leave a standalone `codex-auth` binary outside npm's install path.
+> Those legacy installs can shadow the npm package or a local source build, so remove them during migration.
+
+### Uninstall
+
+Remove the npm package:
 
 ```shell
-curl -fsSL https://raw.githubusercontent.com/loongphy/codex-auth/main/scripts/install.sh | bash
+npm uninstall -g @loongphy/codex-auth
 ```
 
-  The installer writes the install dir to your shell profile by default.
-  Supported profiles: `~/.bashrc`/`~/.bash_profile`/`~/.profile`, `~/.zshrc`/`~/.zprofile`, `~/.config/fish/config.fish`.
-  Use `--no-add-to-path` to skip profile updates.
+Remove old Bash-installer leftovers on Linux/macOS/WSL2:
 
-- Windows (PowerShell):
+```shell
+rm -f ~/.local/bin/codex-auth
+rm -f ~/.local/bin/codex-auth-auto
+sed -i '/# Added by codex-auth installer/,+1d' ~/.bashrc ~/.bash_profile ~/.profile ~/.zshrc ~/.zprofile 2>/dev/null || true
+```
 
-```powershell
-irm https://raw.githubusercontent.com/loongphy/codex-auth/main/scripts/install.ps1 | iex
+If you used fish:
+
+```shell
+sed -i '/# Added by codex-auth installer/,+3d' ~/.config/fish/config.fish 2>/dev/null || true
 ```
 
-  The installer adds the install dir to current/user `PATH` by default.
-  Use `-NoAddToPath` to skip user `PATH` persistence.
+Remove old PowerShell-installer leftovers on Windows:
+
+```powershell
+Remove-Item "$env:LOCALAPPDATA\codex-auth\bin\codex-auth.exe" -Force -ErrorAction SilentlyContinue
+Remove-Item "$env:LOCALAPPDATA\codex-auth\bin\codex-auth-auto.exe" -Force -ErrorAction SilentlyContinue
+[Environment]::SetEnvironmentVariable(
+  "Path",
+  (($env:Path -split ';' | Where-Object { $_ -and $_ -ne "$env:LOCALAPPDATA\codex-auth\bin" }) -join ';'),
+  "User"
+)
+```
 
-## Full Commands
+After cleanup, verify which binary is still active:
 
 ```shell
-codex-auth list # list all accounts
-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
+which codex-auth
+codex-auth --version
 ```
 
-Compatibility note: `codex-auth add` is still accepted as a deprecated alias for `codex-auth login`.
+## Commands
+
+### Account Management
+
+| Command | Description |
+|---------|-------------|
+| `codex-auth list` | List all accounts |
+| `codex-auth login` | Run `codex login`, then add the current account |
+| `codex-auth switch [<email>]` | Switch active account interactively or by partial match |
+| `codex-auth remove` | Remove accounts with interactive multi-select |
+| `codex-auth status` | Show auto-switch, service, and usage status |
+
+> `codex-auth add` is still accepted as a deprecated alias for `codex-auth login`.
+
+### Import
+
+| Command | Description |
+|---------|-------------|
+| `codex-auth import <path> [--alias <alias>]` | Import a single file or batch import from a folder |
+| `codex-auth import --cpa [<path>]` | Import [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) (CPA) token JSON |
+| `codex-auth import --purge [<path>]` | Rebuild `registry.json` from existing auth files |
+
+### Configuration
+
+| Command | Description |
+|---------|-------------|
+| `codex-auth config auto enable\|disable` | Enable or disable background auto-switching |
+| `codex-auth config auto [--5h <%>] [--weekly <%>]` | Set auto-switch thresholds |
+| `codex-auth config api enable\|disable` | Use API-backed fallback or local-only usage refresh |
+
+---
 
-### Examples
+## Examples
 
-List accounts (default table with borders):
+### List Accounts
 
 ```shell
 codex-auth list
 ```
 
+### Switch Account
+
+Interactive: shows email, 5h, weekly, and last activity.
+
+```shell
+codex-auth switch
+```
+
+Before the picker opens, the current active account's usage is refreshed once so the selected row is not stale. The newly selected account is not refreshed after the switch completes.
+
+![command switch](https://github.com/user-attachments/assets/48a86acf-2a6e-4206-a8c4-591989fdc0df)
+
+Non-interactive: fuzzy match by email or alias.
+
+```shell
+codex-auth switch john             # match any account containing "john"
+codex-auth switch john@gmail.com   # match by full or partial email
+codex-auth switch work             # match by alias set during import
+```
+
+If the keyword matches multiple accounts, the command falls back to interactive selection. Press `q` to quit without switching.
+
+### Remove Accounts
+
+```shell
+codex-auth remove
+```
+
+### Login (Add Account)
+
 Add the currently logged-in Codex account:
 
 ```shell
 codex-auth login
 ```
 
-Import an auth.json backup:
+### Import
+
+#### Single File
 
 ```shell
 codex-auth import /path/to/auth.json --alias personal
 ```
 
-Batch import from a folder:
+#### Batch Import from a Folder
+
+Scans all `.json` files in the directory:
 
 ```shell
 codex-auth import /path/to/auth-exports
 ```
 
-Typical batch import output:
+Typical output:
 
 ```text
 Scanning /path/to/auth-exports...
@@ -113,81 +188,97 @@ Scanning /path/to/auth-exports...
 Import Summary: 1 imported, 1 updated, 1 skipped (total 3 files)
 ```
 
-`stdout` carries scanning/success/summary lines. Skipped files and warnings stay on `stderr`.
+`stdout` carries scanning, success, and summary lines. Skipped files and warnings stay on `stderr`.
 
-Rebuild `registry.json` from imported auth files:
+#### Import CLIProxyAPI (CPA) Tokens
 
-```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):
+[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) stores tokens as flat JSON under `~/.cli-proxy-api/`. Import them directly without conversion:
 
 ```shell
-codex-auth switch               # arrow + number input, q to quit
+codex-auth import --cpa                                  # scan default ~/.cli-proxy-api/*.json
+codex-auth import --cpa /path/to/cpa-dir                 # scan a specific directory
+codex-auth import --cpa /path/to/token.json --alias bob  # import a single CPA file
 ```
 
-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)
+#### Fix Broken Account Data (Rebuild Registry)
 
-Switch account non-interactively (for scripts/other CLIs):
+If `codex-auth list` shows missing accounts or wrong usage data, the internal registry file may be out of sync with the actual auth files on disk. This command re-reads all auth files and rebuilds the registry from scratch:
 
 ```shell
-codex-auth switch user
+codex-auth import --purge                                # rebuild from ~/.codex/accounts/*.auth.json
+codex-auth import --purge /path/to/auth-exports          # rebuild from a specific folder
 ```
 
-If multiple accounts match, interactive selection is shown, and you can press `q` to quit without switching.
+This does not import new files. It repairs the registry index for auth snapshots that already exist on disk.
 
-Remove accounts (interactive multi-select):
+### Show Status
 
 ```shell
-codex-auth remove
+codex-auth status
 ```
 
-Show current status:
+### Config
 
-```shell
-codex-auth status
-```
+#### Auto-Switch
 
-Enable background auto-switching:
+Enable or disable:
 
 ```shell
 codex-auth config auto enable
+codex-auth config auto disable
 ```
 
-Configure auto-switch thresholds:
+`config auto enable` prints the current usage mode after installing the watcher, so you can immediately see whether auto-switch is running with default API-backed usage or local-only fallback semantics.
+
+Adjust thresholds:
 
 ```shell
 codex-auth config auto --5h 12
 codex-auth config auto --5h 12 --weekly 8
+codex-auth config auto --weekly 8
 ```
 
-Use API-only usage refresh:
+When auto-switching is enabled, a long-running background watcher refreshes the active account's usage 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%`)
+
+Candidate selection follows the current watcher behavior:
+
+- when `config api enable` is on, the watcher keeps a daemon-local in-memory candidate index, does bounded top-candidate upkeep in the background, and revalidates only the best few stale candidates before a switch
+- in local-only mode, accounts without any usage snapshot are still treated as fresh candidates with full quota
+- when the 5h trigger comes from an actual 300-minute window or an unlabeled primary window, free accounts use a stronger real-time 5h guard and switch no later than `35%` remaining even if the configured 5h threshold is lower
+- free accounts that expose only a single `10080`-minute weekly window are still eligible auto-switch candidates; that weekly remaining percentage is used as their candidate score
+
+The managed background worker is long-running on all supported platforms:
+
+- Linux/WSL: persistent `systemd --user` service
+- macOS: `LaunchAgent`
+- Windows: scheduled task that launches the long-running helper at logon, restarts it after failures, has no 72-hour execution cap, and also starts it immediately on enable
+
+The watcher checks local rollout usage roughly once per second and prefers local rollout events over API polling. In watch mode it caches the newest rollout file between bounded full rescans so large `~/.codex/sessions` trees are not re-walked every second. When `config api enable` is on, the usage API remains a slower fallback, active-account API cooldown resets when the active account changes, and candidate revalidation is driven by a daemon-local in-memory candidate index instead of batch-refreshing every account on every loop.
+
+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 service drift.
+
+Changing thresholds updates `registry.json`, and the running watcher picks them up on the next polling cycle without a service restart.
+
+#### Usage Refresh Source
+
+API-backed fallback:
 
 ```shell
 codex-auth config api enable
 ```
 
-Use pure local rollout refresh without any API calls:
+Local-only, no usage 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:
+Changing `config api` updates `registry.json` immediately. `api enable` is shown as API mode and `api disable` is shown as local mode.
 
-- 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.
+Implementation details are documented in [`docs/auto-switch.md`](docs/auto-switch.md).
 
 ## Q&A
 
@@ -214,12 +305,21 @@ codex-auth status
 Upgrade notes:
 
 - If you are upgrading from `v0.1.x` to the latest `v0.2.x`, API usage refresh is enabled by default.
-- If you previously used an early `v0.2` prerelease/test build and `status` still shows `usage: local`, run `codex-auth config api enable` once to switch to API mode.
+- If you previously used an early `v0.2` prerelease/test build and `status` still shows `usage: local`, run `codex-auth config api enable` once to switch back to API mode.
 
 ### How to import tokens from cli-proxy-api?
 
 If you have token files from `~/.cli-proxy-api/token*.json`, this repository includes a helper script that can convert them into a format codex-auth can read.
 
+The CLI can also import the flat cli-proxy-api / CPA JSON files directly:
+
+```shell
+codex-auth import --cpa                  # default source: ~/.cli-proxy-api
+codex-auth import --cpa /path/to/cpa-dir # scans direct child .json files
+```
+
+Each CPA file is converted in memory to the standard auth snapshot shape before it is written into `~/.codex/accounts/`. Missing or empty `refresh_token` values are skipped as `MissingRefreshToken`.
+
 The script is not bundled in the published npm package, so run it from a clone of this repository:
 
 ```shell
@@ -234,6 +334,8 @@ Then import and switch:
 
 ```shell
 codex-auth import /tmp/tokens/
+# or import the CPA files directly without a conversion step
+codex-auth import --cpa
 codex-auth switch
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loongphy/codex-auth",
-  "version": "0.2.1",
+  "version": "0.2.2-alpha.2",
   "description": "CLI for switching Codex accounts",
   "license": "MIT",
   "repository": {
@@ -20,10 +20,10 @@
     "README.md"
   ],
   "optionalDependencies": {
-    "@loongphy/codex-auth-linux-x64": "0.2.1",
-    "@loongphy/codex-auth-darwin-x64": "0.2.1",
-    "@loongphy/codex-auth-darwin-arm64": "0.2.1",
-    "@loongphy/codex-auth-win32-x64": "0.2.1"
+    "@loongphy/codex-auth-linux-x64": "0.2.2-alpha.2",
+    "@loongphy/codex-auth-darwin-x64": "0.2.2-alpha.2",
+    "@loongphy/codex-auth-darwin-arm64": "0.2.2-alpha.2",
+    "@loongphy/codex-auth-win32-x64": "0.2.2-alpha.2"
   },
   "scripts": {
     "check:versions": "node scripts/npm/check-versions.mjs",