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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +155 -73
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -27,7 +27,7 @@ After that, you can use `codex login` or `codex-auth login` to sign in and add a
27
27
 
28
28
  ## Install
29
29
 
30
- - npm:
30
+ Install with npm:
31
31
 
32
32
  ```shell
33
33
  npm install -g @loongphy/codex-auth
@@ -41,162 +41,244 @@ npx @loongphy/codex-auth list
41
41
 
42
42
  npm packages currently support Linux x64, macOS x64, macOS arm64, and Windows x64.
43
43
 
44
- - Linux/macOS/WSL2:
44
+ > [!NOTE]
45
+ > Older Bash/PowerShell GitHub-release installs could leave a standalone `codex-auth` binary outside npm's install path.
46
+ > Those legacy installs can shadow the npm package or a local source build, so remove them during migration.
47
+
48
+ ### Uninstall
49
+
50
+ Remove the npm package:
45
51
 
46
52
  ```shell
47
- curl -fsSL https://raw.githubusercontent.com/loongphy/codex-auth/main/scripts/install.sh | bash
53
+ npm uninstall -g @loongphy/codex-auth
48
54
  ```
49
55
 
50
- The installer writes the install dir to your shell profile by default.
51
- Supported profiles: `~/.bashrc`/`~/.bash_profile`/`~/.profile`, `~/.zshrc`/`~/.zprofile`, `~/.config/fish/config.fish`.
52
- Use `--no-add-to-path` to skip profile updates.
56
+ Remove old Bash-installer leftovers on Linux/macOS/WSL2:
53
57
 
54
- - Windows (PowerShell):
58
+ ```shell
59
+ rm -f ~/.local/bin/codex-auth
60
+ rm -f ~/.local/bin/codex-auth-auto
61
+ sed -i '/# Added by codex-auth installer/,+1d' ~/.bashrc ~/.bash_profile ~/.profile ~/.zshrc ~/.zprofile 2>/dev/null || true
62
+ ```
55
63
 
56
- ```powershell
57
- irm https://raw.githubusercontent.com/loongphy/codex-auth/main/scripts/install.ps1 | iex
64
+ If you used fish:
65
+
66
+ ```shell
67
+ sed -i '/# Added by codex-auth installer/,+3d' ~/.config/fish/config.fish 2>/dev/null || true
58
68
  ```
59
69
 
60
- The installer adds the install dir to current/user `PATH` by default.
61
- Use `-NoAddToPath` to skip user `PATH` persistence.
70
+ Remove old PowerShell-installer leftovers on Windows:
71
+
72
+ ```powershell
73
+ Remove-Item "$env:LOCALAPPDATA\codex-auth\bin\codex-auth.exe" -Force -ErrorAction SilentlyContinue
74
+ Remove-Item "$env:LOCALAPPDATA\codex-auth\bin\codex-auth-auto.exe" -Force -ErrorAction SilentlyContinue
75
+ [Environment]::SetEnvironmentVariable(
76
+ "Path",
77
+ (($env:Path -split ';' | Where-Object { $_ -and $_ -ne "$env:LOCALAPPDATA\codex-auth\bin" }) -join ';'),
78
+ "User"
79
+ )
80
+ ```
62
81
 
63
- ## Full Commands
82
+ After cleanup, verify which binary is still active:
64
83
 
65
84
  ```shell
66
- codex-auth list # list all accounts
67
- codex-auth login # run `codex login`, then add the current account
68
- codex-auth switch [<email>] # switch active account (interactive or partial/fragment match)
69
- codex-auth import <path> [--alias <alias>] # smart import: file -> single import, folder -> batch import
70
- codex-auth import --cpa [<path>] # import CPA flat token JSON from one file or directory
71
- codex-auth import --purge [<path>] # rebuild registry.json from auth files for the current version
72
- codex-auth remove # remove accounts (interactive multi-select)
73
- codex-auth status # show auto-switch/service/api usage status
74
- codex-auth config auto enable|disable # manage background auto-switching
75
- codex-auth config auto --5h <percent> [--weekly <percent>] # configure auto-switch thresholds
76
- codex-auth config api enable|disable # choose API-only or local-sessions-only usage refresh
85
+ which codex-auth
86
+ codex-auth --version
77
87
  ```
78
88
 
79
- Compatibility note: `codex-auth add` is still accepted as a deprecated alias for `codex-auth login`.
89
+ ## Commands
90
+
91
+ ### Account Management
92
+
93
+ | Command | Description |
94
+ |---------|-------------|
95
+ | `codex-auth list` | List all accounts |
96
+ | `codex-auth login` | Run `codex login`, then add the current account |
97
+ | `codex-auth switch [<email>]` | Switch active account interactively or by partial match |
98
+ | `codex-auth remove` | Remove accounts with interactive multi-select |
99
+ | `codex-auth status` | Show auto-switch, service, and usage status |
100
+
101
+ > `codex-auth add` is still accepted as a deprecated alias for `codex-auth login`.
102
+
103
+ ### Import
104
+
105
+ | Command | Description |
106
+ |---------|-------------|
107
+ | `codex-auth import <path> [--alias <alias>]` | Import a single file or batch import from a folder |
108
+ | `codex-auth import --cpa [<path>]` | Import [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) (CPA) token JSON |
109
+ | `codex-auth import --purge [<path>]` | Rebuild `registry.json` from existing auth files |
110
+
111
+ ### Configuration
112
+
113
+ | Command | Description |
114
+ |---------|-------------|
115
+ | `codex-auth config auto enable\|disable` | Enable or disable background auto-switching |
116
+ | `codex-auth config auto [--5h <%>] [--weekly <%>]` | Set auto-switch thresholds |
117
+ | `codex-auth config api enable\|disable` | Use API-backed fallback or local-only usage refresh |
118
+
119
+ ---
80
120
 
81
- ### Examples
121
+ ## Examples
82
122
 
83
- List accounts (default table with borders):
123
+ ### List Accounts
84
124
 
85
125
  ```shell
86
126
  codex-auth list
87
127
  ```
88
128
 
89
- Add the currently logged-in Codex account:
129
+ ### Switch Account
130
+
131
+ Interactive: shows email, 5h, weekly, and last activity.
90
132
 
91
133
  ```shell
92
- codex-auth login
134
+ codex-auth switch
93
135
  ```
94
136
 
95
- Import an auth.json backup:
137
+ 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.
138
+
139
+ ![command switch](https://github.com/user-attachments/assets/48a86acf-2a6e-4206-a8c4-591989fdc0df)
140
+
141
+ Non-interactive: fuzzy match by email or alias.
96
142
 
97
143
  ```shell
98
- codex-auth import /path/to/auth.json --alias personal
144
+ codex-auth switch john # match any account containing "john"
145
+ codex-auth switch john@gmail.com # match by full or partial email
146
+ codex-auth switch work # match by alias set during import
99
147
  ```
100
148
 
101
- Batch import from a folder:
149
+ If the keyword matches multiple accounts, the command falls back to interactive selection. Press `q` to quit without switching.
150
+
151
+ ### Remove Accounts
102
152
 
103
153
  ```shell
104
- codex-auth import /path/to/auth-exports
154
+ codex-auth remove
105
155
  ```
106
156
 
107
- Import CPA exports directly:
157
+ ### Login (Add Account)
158
+
159
+ Add the currently logged-in Codex account:
108
160
 
109
161
  ```shell
110
- codex-auth import --cpa # scan ~/.cli-proxy-api/*.json
111
- codex-auth import --cpa /path/to/cpa-dir
112
- codex-auth import --cpa /path/to/cpa.json --alias personal
162
+ codex-auth login
113
163
  ```
114
164
 
115
- Typical batch import output:
165
+ ### Import
116
166
 
117
- ```text
118
- Scanning /path/to/auth-exports...
119
- ✓ imported token_ryan.taylor.alpha@email.com
120
- ✓ updated token_jane.smith.alpha@email.com
121
- ✗ skipped token_invalid: MalformedJson
122
- Import Summary: 1 imported, 1 updated, 1 skipped (total 3 files)
167
+ #### Single File
168
+
169
+ ```shell
170
+ codex-auth import /path/to/auth.json --alias personal
123
171
  ```
124
172
 
125
- `stdout` carries scanning/success/summary lines. Skipped files and warnings stay on `stderr`.
173
+ #### Batch Import from a Folder
126
174
 
127
- Rebuild `registry.json` from imported auth files:
175
+ Scans all `.json` files in the directory:
128
176
 
129
177
  ```shell
130
- codex-auth import --purge /path/to/auth-exports
131
- codex-auth import --purge # rebuild from ~/.codex/accounts/*.auth.json
178
+ codex-auth import /path/to/auth-exports
132
179
  ```
133
180
 
134
- Switch accounts (interactive list shows email, 5h, weekly, last activity):
181
+ Typical output:
135
182
 
136
- ```shell
137
- codex-auth switch # arrow + number input, q to quit
183
+ ```text
184
+ Scanning /path/to/auth-exports...
185
+ ✓ imported token_ryan.taylor.alpha@email.com
186
+ ✓ updated token_jane.smith.alpha@email.com
187
+ ✗ skipped token_invalid: MalformedJson
188
+ Import Summary: 1 imported, 1 updated, 1 skipped (total 3 files)
138
189
  ```
139
190
 
140
- 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.
191
+ `stdout` carries scanning, success, and summary lines. Skipped files and warnings stay on `stderr`.
141
192
 
142
- ![command switch](https://github.com/user-attachments/assets/48a86acf-2a6e-4206-a8c4-591989fdc0df)
193
+ #### Import CLIProxyAPI (CPA) Tokens
143
194
 
144
- Switch account non-interactively (for scripts/other CLIs):
195
+ [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) stores tokens as flat JSON under `~/.cli-proxy-api/`. Import them directly without conversion:
145
196
 
146
197
  ```shell
147
- codex-auth switch user
198
+ codex-auth import --cpa # scan default ~/.cli-proxy-api/*.json
199
+ codex-auth import --cpa /path/to/cpa-dir # scan a specific directory
200
+ codex-auth import --cpa /path/to/token.json --alias bob # import a single CPA file
148
201
  ```
149
202
 
150
- If multiple accounts match, interactive selection is shown, and you can press `q` to quit without switching.
203
+ #### Fix Broken Account Data (Rebuild Registry)
151
204
 
152
- Remove accounts (interactive multi-select):
205
+ 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:
153
206
 
154
207
  ```shell
155
- codex-auth remove
208
+ codex-auth import --purge # rebuild from ~/.codex/accounts/*.auth.json
209
+ codex-auth import --purge /path/to/auth-exports # rebuild from a specific folder
156
210
  ```
157
211
 
158
- Show current status:
212
+ This does not import new files. It repairs the registry index for auth snapshots that already exist on disk.
213
+
214
+ ### Show Status
159
215
 
160
216
  ```shell
161
217
  codex-auth status
162
218
  ```
163
219
 
164
- Enable background auto-switching:
220
+ ### Config
221
+
222
+ #### Auto-Switch
223
+
224
+ Enable or disable:
165
225
 
166
226
  ```shell
167
227
  codex-auth config auto enable
228
+ codex-auth config auto disable
168
229
  ```
169
230
 
170
- Configure auto-switch thresholds:
231
+ `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.
232
+
233
+ Adjust thresholds:
171
234
 
172
235
  ```shell
173
236
  codex-auth config auto --5h 12
174
237
  codex-auth config auto --5h 12 --weekly 8
238
+ codex-auth config auto --weekly 8
175
239
  ```
176
240
 
177
- Use API-only usage refresh:
241
+ When auto-switching is enabled, a long-running background watcher refreshes the active account's usage and silently switches accounts when:
242
+
243
+ - 5h remaining drops below the configured 5h threshold (default `10%`), or
244
+ - weekly remaining drops below the configured weekly threshold (default `5%`)
245
+
246
+ Candidate selection follows the current watcher behavior:
247
+
248
+ - 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
249
+ - in local-only mode, accounts without any usage snapshot are still treated as fresh candidates with full quota
250
+ - 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
251
+ - 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
252
+
253
+ The managed background worker is long-running on all supported platforms:
254
+
255
+ - Linux/WSL: persistent `systemd --user` service
256
+ - macOS: `LaunchAgent`
257
+ - 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
258
+
259
+ 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.
260
+
261
+ 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.
262
+
263
+ Changing thresholds updates `registry.json`, and the running watcher picks them up on the next polling cycle without a service restart.
264
+
265
+ #### Usage Refresh Source
266
+
267
+ API-backed fallback:
178
268
 
179
269
  ```shell
180
270
  codex-auth config api enable
181
271
  ```
182
272
 
183
- Use pure local rollout refresh without any API calls:
273
+ Local-only, no usage API calls:
184
274
 
185
275
  ```shell
186
276
  codex-auth config api disable
187
277
  ```
188
278
 
189
- When auto-switching is enabled, a background worker refreshes the active account's usage from the configured source and silently switches accounts when:
190
-
191
- - 5h remaining drops below the configured 5h threshold (default `10%`), or
192
- - weekly remaining drops below the configured weekly threshold (default `5%`)
279
+ Changing `config api` updates `registry.json` immediately. `api enable` is shown as API mode and `api disable` is shown as local mode.
193
280
 
194
- Accounts without any usage snapshot are treated as fresh accounts with full quota when ranking candidates.
195
- 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.
196
- 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.
197
- 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.
198
- Changing `config api` updates `registry.json` immediately; `api enable` means API-only and `api disable` means local-sessions-only.
199
- `codex-auth help` also shows whether auto-switching and usage API calls are currently enabled.
281
+ Implementation details are documented in [`docs/auto-switch.md`](docs/auto-switch.md).
200
282
 
201
283
  ## Q&A
202
284
 
@@ -223,7 +305,7 @@ codex-auth status
223
305
  Upgrade notes:
224
306
 
225
307
  - If you are upgrading from `v0.1.x` to the latest `v0.2.x`, API usage refresh is enabled by default.
226
- - 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.
308
+ - 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.
227
309
 
228
310
  ### How to import tokens from cli-proxy-api?
229
311
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@loongphy/codex-auth",
3
- "version": "0.2.2-alpha.1",
3
+ "version": "0.2.2-alpha.2",
4
4
  "description": "CLI for switching Codex accounts",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -20,10 +20,10 @@
20
20
  "README.md"
21
21
  ],
22
22
  "optionalDependencies": {
23
- "@loongphy/codex-auth-linux-x64": "0.2.2-alpha.1",
24
- "@loongphy/codex-auth-darwin-x64": "0.2.2-alpha.1",
25
- "@loongphy/codex-auth-darwin-arm64": "0.2.2-alpha.1",
26
- "@loongphy/codex-auth-win32-x64": "0.2.2-alpha.1"
23
+ "@loongphy/codex-auth-linux-x64": "0.2.2-alpha.2",
24
+ "@loongphy/codex-auth-darwin-x64": "0.2.2-alpha.2",
25
+ "@loongphy/codex-auth-darwin-arm64": "0.2.2-alpha.2",
26
+ "@loongphy/codex-auth-win32-x64": "0.2.2-alpha.2"
27
27
  },
28
28
  "scripts": {
29
29
  "check:versions": "node scripts/npm/check-versions.mjs",