@loongphy/codex-auth 0.2.10 → 0.3.0-alpha.10

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 (3) hide show
  1. package/README.md +86 -228
  2. package/bin/codex-auth.js +1 -20
  3. package/package.json +8 -10
package/README.md CHANGED
@@ -1,30 +1,9 @@
1
- # Codex Auth
1
+ # Codex Auth [![latest release](https://img.shields.io/github/v/release/Loongphy/codex-auth?sort=semver&label=latest)](https://github.com/Loongphy/codex-auth/releases/latest) [![latest pre-release](https://img.shields.io/github/v/release/Loongphy/codex-auth?include_prereleases&sort=semver&filter=*-*&label=pre-release)](https://github.com/Loongphy/codex-auth/releases)
2
2
 
3
3
  ![command list](https://github.com/user-attachments/assets/6c13a2d6-f9da-47ea-8ec8-0394fc072d40)
4
4
 
5
5
  `codex-auth` is a command-line tool for switching Codex accounts.
6
6
 
7
- > [!IMPORTANT]
8
- > For **Codex CLI** and **Codex App** users, switch accounts, then restart the client for the new account to take effect.
9
- >
10
- > If you use the CLI and want seamless automatic account switching without restarting, use the forked [`codext`](https://github.com/Loongphy/codext), an enhanced Codex CLI. Install it with `npm i -g @loongphy/codext` and run `codext`.
11
-
12
- ## Supported Platforms
13
-
14
- `codex-auth` works with these Codex clients:
15
-
16
- - Codex CLI
17
- - VS Code extension
18
- - Codex App
19
-
20
- 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:
21
-
22
- ```shell
23
- npm install -g @openai/codex
24
- ```
25
-
26
- After that, you can use `codex login`, `codex login --device-auth`, `codex-auth login`, or `codex-auth login --device-auth` to sign in and add accounts more easily.
27
-
28
7
  ## Install
29
8
 
30
9
  Install with npm:
@@ -33,271 +12,146 @@ Install with npm:
33
12
  npm install -g @loongphy/codex-auth
34
13
  ```
35
14
 
36
- You can also run it without a global install:
15
+ You can also run it without a global install:
37
16
 
38
17
  ```shell
39
18
  npx @loongphy/codex-auth list
40
19
  ```
41
20
 
42
- npm packages currently support Linux x64, Linux arm64, macOS x64, macOS arm64, Windows x64, and Windows arm64.
43
-
44
- ### Uninstall
45
-
46
- #### npm
47
-
48
- Remove the npm package:
49
-
50
- ```shell
51
- npm uninstall -g @loongphy/codex-auth
52
- ```
53
-
54
- #### Legacy Bash Installer
21
+ ## Supported Platforms
55
22
 
56
- > [!NOTE]
57
- > If you only installed `@loongphy/codex-auth` with npm, you do not need any legacy cleanup steps.
58
- > Older Bash/PowerShell GitHub-release installs could leave a standalone `codex-auth` binary outside npm's install path.
59
- > If you previously used those legacy installers, remove the leftover binaries and profile changes during migration.
60
- > API-backed usage refresh and team-name refresh use Node.js `fetch`.
61
- > npm installs already satisfy that requirement.
23
+ `codex-auth` works with these Codex clients:
62
24
 
63
- For non-npm installs on Linux/macOS/WSL2 only:
25
+ - Codex CLI
26
+ - VS Code extension
27
+ - Codex App
64
28
 
65
- ```shell
66
- rm -f ~/.local/bin/codex-auth
67
- rm -f ~/.local/bin/codex-auth-auto
68
- sed -i '/# Added by codex-auth installer/,+1d' ~/.bashrc ~/.bash_profile ~/.profile ~/.zshrc ~/.zprofile 2>/dev/null || true
69
- ```
29
+ > [!IMPORTANT]
30
+ > For **Codex CLI** and **Codex App** users, switch accounts, then restart the client for the new account to take effect.
31
+ >
32
+ > If you want seamless automatic account switching without restarting, use the forked [`codext`](https://github.com/Loongphy/codext), an enhanced Codex CLI.
33
+ >
34
+ > Install it with `npm i -g @loongphy/codext` and run `codext`.
35
+ >
36
+ > Codex App users can use `codex-auth app`, but it is not stable. See [Details](#codex-app).
70
37
 
71
- If you used fish, also remove the old profile entry:
38
+ Install the Codex CLI even if you mainly use the VS Code extension or the App, because it makes adding accounts easier:
72
39
 
73
40
  ```shell
74
- sed -i '/# Added by codex-auth installer/,+3d' ~/.config/fish/config.fish 2>/dev/null || true
41
+ npm install -g @openai/codex
75
42
  ```
76
43
 
77
- #### Legacy PowerShell Installer
44
+ After that, you can use `codex-auth login`, or `codex-auth login --device-auth` to sign in and add accounts more easily.
78
45
 
79
- For non-npm installs on Windows only:
46
+ ## Commands
80
47
 
81
- ```powershell
82
- Remove-Item "$env:LOCALAPPDATA\codex-auth\bin\codex-auth.exe" -Force -ErrorAction SilentlyContinue
83
- Remove-Item "$env:LOCALAPPDATA\codex-auth\bin\codex-auth-auto.exe" -Force -ErrorAction SilentlyContinue
84
- [Environment]::SetEnvironmentVariable(
85
- "Path",
86
- (($env:Path -split ';' | Where-Object { $_ -and $_ -ne "$env:LOCALAPPDATA\codex-auth\bin" }) -join ';'),
87
- "User"
88
- )
89
- ```
48
+ Detailed command documentation lives in [docs/commands/README.md](./docs/commands/README.md).
90
49
 
91
- ## Commands
50
+ > [!NOTE]
51
+ > This documentation is based on **v0.3.x**. Some commands described here may not be available in the current release.
52
+ >
53
+ > To try the latest features, please install the alpha version via:
54
+ >
55
+ > ```bash
56
+ > npm install -g @loongphy/codex-auth@next
57
+ > ```
58
+ >
59
+ > If you want to downgrade to **v0.2.x**, you may need to manually update the `~/.codex/accounts/registry.json`:
60
+ >
61
+ > ```json
62
+ > "schema_version": 3
63
+ > ```
92
64
 
93
65
  ### Account Management
94
66
 
95
67
  | Command | Description |
96
68
  |---------|-------------|
97
- | `codex-auth list [--debug]` | List all accounts |
98
- | `codex-auth login [--device-auth]` | Run `codex login` (optionally with `--device-auth`), then add the current account |
99
- | `codex-auth switch [<email>]` | Switch active account interactively or by partial match |
100
- | `codex-auth remove` | Remove accounts with interactive multi-select |
101
- | `codex-auth status` | Show auto-switch, service, and usage status |
102
-
103
- ### Import
69
+ | [`codex-auth list [--live] [--active] [--api\|--skip-api]`](./docs/commands/list.md) | List stored accounts and usage state |
70
+ | [`codex-auth login [--device-auth]`](./docs/commands/login.md) | Run `codex login`, then add the current account |
71
+ | [`codex-auth switch [--live] [--api\|--skip-api]`](./docs/commands/switch.md) | Switch the active account interactively |
72
+ | [`codex-auth switch <query>`](./docs/commands/switch.md) | Switch directly by row number or account selector |
73
+ | [`codex-auth remove [--live] [--api\|--skip-api]`](./docs/commands/remove.md) | Remove accounts interactively |
74
+ | [`codex-auth remove <query> [<query>...]`](./docs/commands/remove.md) | Remove accounts by selector |
75
+ | [`codex-auth remove --all`](./docs/commands/remove.md) | Remove all stored accounts |
76
+ | [`codex-auth alias set <query> <alias>`](./docs/commands/alias.md) | Set an alias for an account |
77
+ | [`codex-auth alias clear <query>`](./docs/commands/alias.md) | Clear the alias for an account |
78
+
79
+ ### Import and Maintenance
104
80
 
105
81
  | Command | Description |
106
82
  |---------|-------------|
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 |
83
+ | [`codex-auth import <path> [--alias <alias>]`](./docs/commands/import.md) | Import a single auth file or batch import a folder |
84
+ | [`codex-auth import --cpa [<path>]`](./docs/commands/import.md) | Import CLIProxyAPI token JSON |
85
+ | [`codex-auth import --purge [<path>]`](./docs/commands/import.md) | Rebuild `registry.json` from auth files |
86
+ | [`codex-auth export [<dir>]`](./docs/commands/export.md) | Export stored account auth files |
87
+ | [`codex-auth export --cpa [<dir>]`](./docs/commands/export.md) | Export CLIProxyAPI token JSON |
88
+ | [`codex-auth clean`](./docs/commands/clean.md) | Delete managed backup and stale account files |
110
89
 
111
90
  ### Configuration
112
91
 
113
92
  | Command | Description |
114
93
  |---------|-------------|
115
- | `codex-auth config auto enable\|disable` | Enable or disable experimental background auto-switching |
116
- | `codex-auth config auto [--5h <%>] [--weekly <%>]` | Set experimental auto-switch thresholds |
117
- | `codex-auth config api enable\|disable` | Enable or disable both usage refresh and team name refresh API calls |
94
+ | [`codex-auth config live --interval <seconds>`](./docs/commands/config.md) | Configure live TUI refresh interval |
118
95
 
119
- ---
120
-
121
- ## Examples
122
-
123
- ### List Accounts
124
-
125
- > [!IMPORTANT]
126
- > Built-in Node proxy support for API refresh requires Node.js `22.21.0+` or `24.0.0+`.
96
+ ## Quick Examples
127
97
 
128
98
  ```shell
129
99
  codex-auth list
130
- codex-auth list --debug
131
- ```
132
-
133
- ### Switch Account
134
-
135
- Interactive: shows email, 5h, weekly, and last activity.
136
-
137
- ```shell
100
+ codex-auth list --active
138
101
  codex-auth switch
139
- ```
140
-
141
- ![command switch](https://github.com/user-attachments/assets/48a86acf-2a6e-4206-a8c4-591989fdc0df)
142
-
143
- Non-interactive: fuzzy match by email or alias.
144
-
145
- ```shell
146
- codex-auth switch john # match any account containing "john"
147
- codex-auth switch john@gmail.com # match by full or partial email
148
- codex-auth switch work # match by alias set during import
149
- ```
150
-
151
- If the keyword matches multiple accounts, the command falls back to interactive selection. Press `q` to quit without switching.
152
-
153
- ### Remove Accounts
154
-
155
- ```shell
156
- codex-auth remove
157
- ```
158
-
159
- ### Login (Add Account)
160
-
161
- Add the currently logged-in Codex account:
162
-
163
- ```shell
164
- codex-auth login
165
- codex-auth login --device-auth
166
- ```
167
-
168
- ### Import
169
-
170
- #### Single File
171
-
172
- ```shell
102
+ codex-auth switch 02
103
+ codex-auth remove work
173
104
  codex-auth import /path/to/auth.json --alias personal
105
+ codex-auth list --skip-api
174
106
  ```
175
107
 
176
- #### Batch Import from a Folder
177
-
178
- Scans all `.json` files in the directory:
179
-
180
- ```shell
181
- codex-auth import /path/to/auth-exports
182
- ```
183
-
184
- Typical output:
185
-
186
- ```text
187
- Scanning /path/to/auth-exports...
188
- ✓ imported token_ryan.taylor.alpha@email.com
189
- ✓ updated token_jane.smith.alpha@email.com
190
- ✗ skipped token_invalid: MalformedJson
191
- Import Summary: 1 imported, 1 updated, 1 skipped (total 3 files)
192
- ```
193
-
194
- `stdout` carries scanning, success, and summary lines. Skipped files and warnings stay on `stderr`.
195
-
196
- #### Import CLIProxyAPI (CPA) Tokens
197
-
198
- [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) stores tokens as flat JSON under `~/.cli-proxy-api/`. Import them directly without conversion:
199
-
200
- ```shell
201
- codex-auth import --cpa # scan default ~/.cli-proxy-api/*.json
202
- codex-auth import --cpa /path/to/cpa-dir # scan a specific directory
203
- codex-auth import --cpa /path/to/token.json --alias bob # import a single CPA file
204
- ```
205
-
206
- #### Fix Broken Account Data (Rebuild Registry)
207
-
208
- 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:
209
-
210
- ```shell
211
- codex-auth import --purge # rebuild from ~/.codex/accounts/*.auth.json
212
- codex-auth import --purge /path/to/auth-exports # rebuild from a specific folder
213
- ```
214
-
215
- This does not import new files. It repairs the registry index for auth snapshots that already exist on disk.
216
-
217
- ### Show Status
218
-
219
- ```shell
220
- codex-auth status
221
- ```
222
-
223
- ### Config
224
-
225
- #### Auto-Switch
226
-
227
- > [!WARNING]
228
- > Auto-switch is experimental. Behavior, defaults, and platform integration may change in future releases while the feature matures.
229
-
230
- Enable or disable:
231
-
232
- ```shell
233
- codex-auth config auto enable
234
- codex-auth config auto disable
235
- ```
236
-
237
- `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.
238
-
239
- Adjust thresholds:
240
-
241
- ```shell
242
- codex-auth config auto --5h 12
243
- codex-auth config auto --5h 12 --weekly 8
244
- codex-auth config auto --weekly 8
245
- ```
246
-
247
- When auto-switching is enabled, a long-running background watcher refreshes the active account's usage and silently switches accounts when:
248
-
249
- - 5h remaining drops below the configured 5h threshold (default `10%`), or
250
- - weekly remaining drops below the configured weekly threshold (default `5%`)
108
+ ## Codex App
251
109
 
252
- The managed background worker is long-running on all supported platforms:
110
+ > [!IMPORTANT]
111
+ > The `app` command is **experimental** and may never become a stable feature.
112
+ >
113
+ > It is designed to enable seamless account switching without restarting the Codex App. By leveraging the `CODEX_CLI_PATH` environment variable, it dynamically injects our managed codext CLI to handle authentication on the fly.
114
+ >
115
+ > The `app` command is constrained by ongoing changes in the official Codex App and [Codex CLI](https://github.com/openai/codex). It may not always take effect and may also break your app.
253
116
 
254
- - Linux/WSL: persistent `systemd --user` service
255
- - macOS: `LaunchAgent`
256
- - 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
117
+ | Command | Description |
118
+ |---------|-------------|
119
+ | [`codex-auth app [--id <id>] [--codex-cli-path <path>]`](./docs/commands/app.md) | Experimental: launch Codex App with detected defaults, CODEX_HOME, CODEX_CLI_PATH, and platform overrides |
257
120
 
258
- #### Usage Refresh Source
121
+ Support seamless account switching including:
259
122
 
260
- API-backed fallback:
123
+ - New Chat
124
+ - Restoring or resuming an existing conversation
125
+ - Continuing a previously completed, interrupted, or manually stopped conversation
261
126
 
262
- ```shell
263
- codex-auth config api enable
264
- ```
127
+ ### Uninstall
265
128
 
266
- Local-only, no usage API calls:
129
+ Remove the npm package:
267
130
 
268
131
  ```shell
269
- codex-auth config api disable
132
+ npm uninstall -g @loongphy/codex-auth
270
133
  ```
271
134
 
272
- Changing `config api` updates `registry.json` immediately. `api enable` is shown as API mode and `api disable` is shown as local mode.
273
-
274
135
  ## Q&A
275
136
 
276
137
  ### Why is my usage limit not refreshing?
277
138
 
278
- If `codex-auth` is using local-only usage refresh, it reads the newest `~/.codex/sessions/**/rollout-*.jsonl` file. Recent Codex builds often write `token_count` events with `rate_limits: null`. The local files may still contain older usable usage limit data, but in practice they can lag by several hours, so local-only refresh may show a usage limit snapshot from hours ago instead of your latest state.
139
+ API-backed refresh is the default. When you pass `--skip-api`, `codex-auth` reads the newest `~/.codex/sessions/**/rollout-*.jsonl` file instead. Recent Codex builds often write `token_count` events with `rate_limits: null`. The local files may still contain older usable usage limit data, but in practice they can lag by several hours, so local-only refresh may show a usage limit snapshot from hours ago instead of your latest state.
279
140
 
280
141
  - Upstream Codex issue: [openai/codex#14880](https://github.com/openai/codex/issues/14880)
281
142
 
282
- You can switch usage limit refresh to the usage API with:
143
+ Run the API-backed default with:
283
144
 
284
145
  ```shell
285
- codex-auth config api enable
146
+ codex-auth list
286
147
  ```
287
148
 
288
- Then confirm the current mode with:
149
+ Run one local-only command with:
289
150
 
290
151
  ```shell
291
- codex-auth status
152
+ codex-auth list --skip-api
292
153
  ```
293
154
 
294
- `status` should show `usage: api`.
295
-
296
- Upgrade notes:
297
-
298
- - If you are upgrading from `v0.1.x` to the latest `v0.2.x`, API usage refresh is enabled by default.
299
- - 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.
300
-
301
155
  Verify with:
302
156
 
303
157
  ```shell
@@ -311,8 +165,12 @@ This project is provided as-is and use is at your own risk.
311
165
  **Usage Data Refresh Source:**
312
166
  `codex-auth` supports two sources for refreshing account usage/usage limit information:
313
167
 
314
- 1. **API (default):** When `config api enable` is on, the tool makes direct HTTPS requests to OpenAI's endpoints using your account's access token. This enables both usage refresh and team name refresh. npm installs already satisfy the runtime requirement; legacy standalone binary installs need Node.js 22+ on `PATH`.
315
- 2. **Local-only:** When `config api disable` is on, the tool scans local `~/.codex/sessions/*/rollout-*.jsonl` files for usage data and skips team name refresh API calls. This mode is safer, but it can be less accurate because recent Codex rollout files often contain `rate_limits: null`, so the latest local usage limit data may lag by several hours.
168
+ 1. **API (default):** The tool makes direct HTTPS requests to OpenAI's endpoints using your account's access token. This enables both usage refresh and team name refresh. `curl` must be available at runtime.
169
+ 2. **Local-only:** With per-command `--skip-api`, the tool scans local `~/.codex/sessions/*/rollout-*.jsonl` files for usage data and skips team name refresh API calls. This mode is safer, but it can be less accurate because recent Codex rollout files often contain `rate_limits: null`, so the latest local usage limit data may lag by several hours.
316
170
 
317
171
  **API Call Declaration:**
318
- By enabling API(`codex-auth config api enable`), this tool will send your ChatGPT access token to OpenAI's servers, including `https://chatgpt.com/backend-api/wham/usage` for usage limit and `https://chatgpt.com/backend-api/accounts/check/v4-2023-04-27` for team name. 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.
172
+ By using the default API-backed refresh, this tool will send your ChatGPT access token to OpenAI's servers for usage limit and team name refresh. The exact endpoints are:
173
+ - `GET https://chatgpt.com/backend-api/wham/usage`
174
+ - `GET https://chatgpt.com/backend-api/accounts`
175
+
176
+ 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/bin/codex-auth.js CHANGED
@@ -10,21 +10,6 @@ const __filename = fileURLToPath(import.meta.url);
10
10
  const __dirname = path.dirname(__filename);
11
11
  const require = createRequire(import.meta.url);
12
12
  const rootPackageJsonPath = path.join(__dirname, "..", "package.json");
13
- const requiredNodeMajor = 22;
14
-
15
- function ensureSupportedNodeVersion() {
16
- const major = Number(process.versions?.node?.split(".")[0] ?? 0);
17
- if (Number.isInteger(major) && major >= requiredNodeMajor) {
18
- return;
19
- }
20
-
21
- console.error(
22
- `Node.js ${requiredNodeMajor}+ is required to run @loongphy/codex-auth. Current version: ${process.version}.`
23
- );
24
- process.exit(1);
25
- }
26
-
27
- ensureSupportedNodeVersion();
28
13
 
29
14
  const packageMap = {
30
15
  "linux:x64": "@loongphy/codex-auth-linux-x64",
@@ -92,11 +77,7 @@ function resolveBinary() {
92
77
 
93
78
  const binaryPath = resolveBinary();
94
79
  const child = spawnSync(binaryPath, process.argv.slice(2), {
95
- stdio: "inherit",
96
- env: {
97
- ...process.env,
98
- CODEX_AUTH_NODE_EXECUTABLE: process.execPath
99
- }
80
+ stdio: "inherit"
100
81
  });
101
82
 
102
83
  if (child.error) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@loongphy/codex-auth",
3
- "version": "0.2.10",
3
+ "version": "0.3.0-alpha.10",
4
4
  "type": "module",
5
5
  "description": "CLI for switching Codex accounts",
6
6
  "license": "MIT",
@@ -21,21 +21,19 @@
21
21
  "README.md"
22
22
  ],
23
23
  "optionalDependencies": {
24
- "@loongphy/codex-auth-linux-x64": "0.2.10",
25
- "@loongphy/codex-auth-linux-arm64": "0.2.10",
26
- "@loongphy/codex-auth-darwin-x64": "0.2.10",
27
- "@loongphy/codex-auth-darwin-arm64": "0.2.10",
28
- "@loongphy/codex-auth-win32-x64": "0.2.10",
29
- "@loongphy/codex-auth-win32-arm64": "0.2.10"
24
+ "@loongphy/codex-auth-linux-x64": "0.3.0-alpha.10",
25
+ "@loongphy/codex-auth-linux-arm64": "0.3.0-alpha.10",
26
+ "@loongphy/codex-auth-darwin-x64": "0.3.0-alpha.10",
27
+ "@loongphy/codex-auth-darwin-arm64": "0.3.0-alpha.10",
28
+ "@loongphy/codex-auth-win32-x64": "0.3.0-alpha.10",
29
+ "@loongphy/codex-auth-win32-arm64": "0.3.0-alpha.10"
30
30
  },
31
31
  "scripts": {
32
32
  "check:versions": "node scripts/npm/check-versions.mjs",
33
+ "check:release-metadata": "node scripts/npm/check-release-metadata.mjs",
33
34
  "stage:npm": "node scripts/npm/stage-packages.mjs"
34
35
  },
35
36
  "publishConfig": {
36
37
  "access": "public"
37
- },
38
- "engines": {
39
- "node": ">=22"
40
38
  }
41
39
  }