npm - @wangxt0223/codex-switcher - Versions diffs - 0.4.0 → 0.4.1 - Mend

@wangxt0223/codex-switcher 0.4.0 → 0.4.1

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 (7) hide show

package/CHANGELOG.md +7 -0
package/README.en.md +14 -14
package/README.md +43 -23
package/package.json +1 -1
package/plugins/codex-switcher/.codex-plugin/plugin.json +1 -1
package/plugins/codex-switcher/README.en.md +44 -44
package/plugins/codex-switcher/README.md +44 -44

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,12 @@
 # Changelog
+## 0.4.1 - 2026-04-12
+- Refined README wording for a more conversational background/auth mechanism explanation.
+- Moved command reference from plugin docs to root README in table format.
+- Standardized README title to `codex-switcher`.
+- Removed legacy package-name migration notices from docs.
 ## 0.4.0 - 2026-04-12
 - Changed npm package name to `@wangxt0223/codex-switcher` (CLI command remains `codex-sw`).

package/README.en.md CHANGED Viewed

@@ -1,8 +1,8 @@
-# codex-sw
+# codex-switcher
 [中文](README.md) | English
-`codex-sw` is a lightweight profile switcher for Codex CLI and Codex App.
+`codex-switcher` is a lightweight profile switcher for Codex CLI and Codex App.
 It isolates accounts by running each profile in its own `CODEX_HOME` directory.
 ## Background
@@ -10,7 +10,7 @@ It isolates accounts by running each profile in its own `CODEX_HOME` directory.
 I originally used Codex for personal work while my company account lived in Cursor, so there was no conflict.
 After the company migrated from Cursor to Codex, my personal and company Codex accounts started conflicting on the same machine, and switching became unreliable.
-After inspecting local behavior, I found Codex's local auth model is straightforward: if account-local data is isolated per directory, account switching becomes stable. Based on that, I built `codex-sw` with Codex to manage, switch, and isolate all my Codex accounts.
+After inspecting local behavior, I found Codex's local auth model is straightforward: if account-local data is isolated per directory, account switching becomes stable. Based on that, I built `codex-switcher` with Codex to manage, switch, and isolate all my Codex accounts.
 ## Codex Local Auth Model (Summary)
@@ -21,7 +21,7 @@ The following is based on observed local behavior and filesystem layout:
 - Session/history/state data is also stored under the same `CODEX_HOME` (for example `history.jsonl`, `sessions/`, `state_*.sqlite`).
 - So when multiple accounts share one `CODEX_HOME`, auth/session data can overwrite or contaminate each other.
-`codex-sw` solves this by assigning each account its own `CODEX_HOME` (`~/.codex-profiles/<profile>`) and switching that directory for CLI/App operations.
+`codex-switcher` solves this by assigning each account its own `CODEX_HOME` (`~/.codex-profiles/<profile>`) and switching that directory for CLI/App operations.
 ## Install
@@ -29,28 +29,28 @@ The following is based on observed local behavior and filesystem layout:
 ```bash
 npm i -g @wangxt0223/codex-switcher
-codex-sw check
+codex-switcher check
 ```
 ### Option B: from source checkout
 ```bash
 ./scripts/install.sh
-codex-sw check
+codex-switcher check
 ```
 ## Quick start
 ```bash
-codex-sw add work
-codex-sw add personal
+codex-switcher add work
+codex-switcher add personal
-codex-sw use work --sync
-codex-sw login --sync
-codex-sw exec -- login status
+codex-switcher use work --sync
+codex-switcher login --sync
+codex-switcher exec -- login status
-codex-sw switch personal --sync
-codex-sw app use personal
+codex-switcher switch personal --sync
+codex-switcher app use personal
 ```
 ## Sync options
@@ -81,7 +81,7 @@ npm run release:npm
 ## Upgrade
 ```bash
-codex-sw upgrade
+codex-switcher upgrade
 ```
 ## Docs

package/README.md CHANGED Viewed

@@ -1,8 +1,8 @@
-# codex-sw
+# codex-switcher
 中文 | [English](README.en.md)
-`codex-sw` 是一个面向 Codex CLI 与 Codex App 的轻量账号切换工具。
+`codex-switcher` 是一个面向 Codex CLI 与 Codex App 的轻量账号切换工具。
 它通过为每个 profile 使用独立的 `CODEX_HOME` 目录实现账号隔离。
 ## 项目背景
@@ -11,18 +11,14 @@
 后来公司从 Cursor 切到 Codex 后，我就得在同一台电脑上同时用个人账号和公司账号，很快就遇到冲突：登录态会互相覆盖，切换也不顺手。
 为了搞清楚原因，我看了下 Codex 的本地数据机制，发现思路其实很直接：只要把不同账号对应的本地目录隔离开，就能稳定切换。
-基于这个思路，我用 Codex 写了 `codex-sw`，专门用来管理、切换和隔离我所有的 Codex 账号，现在日常在个人/公司账号之间切换方便很多。
+基于这个思路，我用 Codex 写了 `codex-switcher`，专门用来管理、切换和隔离我所有的 Codex 账号，现在日常在个人/公司账号之间切换方便很多。
 ## Codex 本地认证机制（简述）
-以下是基于本地行为和目录结构观察到的机制：
+简单说就是：Codex 会把“账号登录态 + 会话历史 + 一些本地状态”都放在 `CODEX_HOME` 这个目录里（默认一般是 `~/.codex`）。
+如果两个账号共用同一个目录，就很容易出现你登我下、我登你下，或者历史数据串在一起的问题。
-- `Codex CLI` 与 `Codex App` 都会读取同一个工作目录根：`CODEX_HOME`（默认通常是 `~/.codex`）。
-- 账号认证状态主要保存在 `CODEX_HOME/auth.json`。
-- 会话、历史、索引和状态等数据也会写在同一 `CODEX_HOME` 下（如 `history.jsonl`、`sessions/`、`state_*.sqlite` 等）。
-- 因此当多个账号共享同一个 `CODEX_HOME` 时，最容易出现“登录态互相覆盖/污染”的问题。
-`codex-sw` 的做法就是为每个账号分配独立 `CODEX_HOME`（`~/.codex-profiles/<profile>`），并在执行命令或启动 App 时切换到对应目录，从而实现账号隔离与可控切换。
+`codex-switcher` 做的事情其实不复杂：给每个账号分一个独立目录（`~/.codex-profiles/<profile>`），然后在你执行命令或启动 App 时自动切到对应目录。这样每个账号的数据都各管各的，切换也就稳定了。
 ## 安装
@@ -30,28 +26,28 @@
 ```bash
 npm i -g @wangxt0223/codex-switcher
-codex-sw check
+codex-switcher check
 ```
 ### 方式 B：源码安装
 ```bash
 ./scripts/install.sh
-codex-sw check
+codex-switcher check
 ```
 ## 快速开始
 ```bash
-codex-sw add work
-codex-sw add personal
+codex-switcher add work
+codex-switcher add personal
-codex-sw use work --sync
-codex-sw login --sync
-codex-sw exec -- login status
+codex-switcher use work --sync
+codex-switcher login --sync
+codex-switcher exec -- login status
-codex-sw switch personal --sync
-codex-sw app use personal
+codex-switcher switch personal --sync
+codex-switcher app use personal
 ```
 ## 同步选项
@@ -62,9 +58,33 @@ codex-sw app use personal
 ## 命令参考
-详见插件文档：
-- 中文：`plugins/codex-switcher/README.md`
-- English: `plugins/codex-switcher/README.en.md`
+命令默认用 `codex-switcher`，你也可以继续使用兼容别名 `codex-sw`。
+| 分类 | 命令 | 说明 |
+| --- | --- | --- |
+| Profile 管理 | `codex-switcher add <profile>` | 新建 profile |
+| Profile 管理 | `codex-switcher remove <profile> [--force]` | 删除 profile |
+| Profile 管理 | `codex-switcher list` | 列出所有 profile |
+| Profile 管理 | `codex-switcher current [cli\|app]` | 查看当前 CLI / App profile |
+| Profile 管理 | `codex-switcher status` | 查看当前 profile 登录状态 |
+| Profile 管理 | `codex-switcher use <profile> [--sync\|--no-sync]` | 切换当前 CLI profile |
+| Profile 管理 | `codex-switcher switch <profile> [--sync\|--no-sync]` | `use` 的等价命令 |
+| 数据迁移 | `codex-switcher import-default <profile> [--with-auth] [--force]` | 从 `~/.codex` 导入数据到 profile |
+| CLI 登录态 | `codex-switcher login [profile] [--sync\|--no-sync]` | 登录指定或当前 CLI profile |
+| CLI 登录态 | `codex-switcher logout [profile]` | 登出指定或当前 CLI profile |
+| CLI 登录态 | `codex-switcher exec -- <codex args...>` | 在当前 CLI profile 下执行 codex 命令 |
+| CLI 登录态 | `codex-switcher env [profile]` | 输出指定 profile 的 `CODEX_HOME` |
+| App 控制 | `codex-switcher app open [profile]` | 用指定 profile 启动 App |
+| App 控制 | `codex-switcher app use <profile>` | 切换 App profile（等价于 open） |
+| App 控制 | `codex-switcher app logout [profile]` | 登出 App profile |
+| App 控制 | `codex-switcher app status` | 查看 App 运行状态 |
+| App 控制 | `codex-switcher app stop` | 停止由工具启动的 App 进程 |
+| App 控制 | `codex-switcher app current` | 查看当前 App profile |
+| 系统维护 | `codex-switcher check` | 基础环境与状态检查 |
+| 系统维护 | `codex-switcher doctor [--fix]` | 诊断并可选自动修复 |
+| 系统维护 | `codex-switcher recover [--dry-run]` | 恢复损坏的 current 指针 |
+| 系统维护 | `codex-switcher init [--shell zsh\|bash] [--dry-run]` | 初始化 PATH 与快捷命令 |
+| 系统维护 | `codex-switcher upgrade [--dry-run]` | 升级到最新版本 |
 ## 开发
@@ -82,7 +102,7 @@ npm run release:npm
 ## 升级
 ```bash
-codex-sw upgrade
+codex-switcher upgrade
 ```
 ## 文档

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@wangxt0223/codex-switcher",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Profile-based account switcher for Codex CLI and Codex App using isolated CODEX_HOME directories.",
   "license": "MIT",
   "author": "wangxt",

package/plugins/codex-switcher/.codex-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "codex-switcher",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Profile-based account switcher for Codex CLI and Codex App without modifying upstream source.",
   "author": {
     "name": "wangxt",

package/plugins/codex-switcher/README.en.md CHANGED Viewed

@@ -1,4 +1,4 @@
-# codex-sw
+# codex-switcher
 [中文](README.md) | English
@@ -14,45 +14,45 @@ Profile-based account switcher for Codex CLI and Codex App.
 ## Commands
 ```bash
-codex-sw add <profile>
-codex-sw remove <profile> [--force]
-codex-sw list
-codex-sw import-default <profile> [--with-auth] [--force]
-codex-sw use <profile> [--sync|--no-sync]
-codex-sw switch <profile> [--sync|--no-sync]
-codex-sw current [cli|app]
-codex-sw status
-codex-sw exec -- <codex args...>
-codex-sw login [profile] [--sync|--no-sync]
-codex-sw logout [profile]
-codex-sw env [profile]
-codex-sw app open [profile]
-codex-sw app use <profile>
-codex-sw app logout [profile]
-codex-sw app status
-codex-sw app stop
-codex-sw init [--shell zsh|bash]
-codex-sw upgrade [--dry-run]
-codex-sw recover
-codex-sw check
-codex-sw doctor [--fix]
+codex-switcher add <profile>
+codex-switcher remove <profile> [--force]
+codex-switcher list
+codex-switcher import-default <profile> [--with-auth] [--force]
+codex-switcher use <profile> [--sync|--no-sync]
+codex-switcher switch <profile> [--sync|--no-sync]
+codex-switcher current [cli|app]
+codex-switcher status
+codex-switcher exec -- <codex args...>
+codex-switcher login [profile] [--sync|--no-sync]
+codex-switcher logout [profile]
+codex-switcher env [profile]
+codex-switcher app open [profile]
+codex-switcher app use <profile>
+codex-switcher app logout [profile]
+codex-switcher app status
+codex-switcher app stop
+codex-switcher init [--shell zsh|bash]
+codex-switcher upgrade [--dry-run]
+codex-switcher recover
+codex-switcher check
+codex-switcher doctor [--fix]
 ```
 ## Typical flow
 ```bash
-codex-sw add work
-codex-sw add personal
+codex-switcher add work
+codex-switcher add personal
-codex-sw use work --sync
-codex-sw login --sync
-codex-sw exec -- login status
+codex-switcher use work --sync
+codex-switcher login --sync
+codex-switcher exec -- login status
-codex-sw switch personal --sync
-codex-sw app use personal
+codex-switcher switch personal --sync
+codex-switcher app use personal
 ```
 ## Migrate Existing App/CLI Data
@@ -60,14 +60,14 @@ codex-sw app use personal
 If your existing data is in `~/.codex`, import it into a profile first:
 ```bash
-codex-sw import-default work
+codex-switcher import-default work
 ```
 This copies records/projects/history but excludes `auth.json` by default.
 If you want to carry login state too:
 ```bash
-codex-sw import-default work --with-auth
+codex-switcher import-default work --with-auth
 ```
 ## Sync Behavior
@@ -79,27 +79,27 @@ codex-sw import-default work --with-auth
 Examples:
 ```bash
-codex-sw login work --sync
-codex-sw switch personal --sync
-codex-sw use work --no-sync
+codex-switcher login work --sync
+codex-switcher switch personal --sync
+codex-switcher use work --no-sync
 ```
 ## Upgrade
 ```bash
-codex-sw upgrade
+codex-switcher upgrade
 ```
 ## Notes
 - Codex App is single-instance on macOS; switching App profile requires restart.
-- `codex-sw app stop` only stops app instances started and tracked by `codex-sw`.
-- `codex-sw app open/use <profile>` requires that profile already exists and is logged in.
+- `codex-switcher app stop` only stops app instances started and tracked by `codex-switcher`.
+- `codex-switcher app open/use <profile>` requires that profile already exists and is logged in.
 - `--sync` uses overwrite strategy (not merge): source overwrites target for all files except `auth.json`.
-- `codex-sw status` exit codes:
+- `codex-switcher status` exit codes:
   - `0`: both current profiles logged in
   - `1`: at least one current profile not logged in
-  - `2`: pointer/profile integrity issue (run `codex-sw recover`)
+  - `2`: pointer/profile integrity issue (run `codex-switcher recover`)
 ## Validation
@@ -109,4 +109,4 @@ codex-sw upgrade
 ## Compatibility command
-`codex-switcher` is kept as a compatibility entrypoint and maps to the same implementation.
+`codex-sw` is kept as a compatibility entrypoint and maps to the same implementation.

package/plugins/codex-switcher/README.md CHANGED Viewed

@@ -1,4 +1,4 @@
-# codex-sw
+# codex-switcher
 中文 | [English](README.en.md)
@@ -14,45 +14,45 @@
 ## 命令
 ```bash
-codex-sw add <profile>
-codex-sw remove <profile> [--force]
-codex-sw list
-codex-sw import-default <profile> [--with-auth] [--force]
-codex-sw use <profile> [--sync|--no-sync]
-codex-sw switch <profile> [--sync|--no-sync]
-codex-sw current [cli|app]
-codex-sw status
-codex-sw exec -- <codex args...>
-codex-sw login [profile] [--sync|--no-sync]
-codex-sw logout [profile]
-codex-sw env [profile]
-codex-sw app open [profile]
-codex-sw app use <profile>
-codex-sw app logout [profile]
-codex-sw app status
-codex-sw app stop
-codex-sw init [--shell zsh|bash]
-codex-sw upgrade [--dry-run]
-codex-sw recover
-codex-sw check
-codex-sw doctor [--fix]
+codex-switcher add <profile>
+codex-switcher remove <profile> [--force]
+codex-switcher list
+codex-switcher import-default <profile> [--with-auth] [--force]
+codex-switcher use <profile> [--sync|--no-sync]
+codex-switcher switch <profile> [--sync|--no-sync]
+codex-switcher current [cli|app]
+codex-switcher status
+codex-switcher exec -- <codex args...>
+codex-switcher login [profile] [--sync|--no-sync]
+codex-switcher logout [profile]
+codex-switcher env [profile]
+codex-switcher app open [profile]
+codex-switcher app use <profile>
+codex-switcher app logout [profile]
+codex-switcher app status
+codex-switcher app stop
+codex-switcher init [--shell zsh|bash]
+codex-switcher upgrade [--dry-run]
+codex-switcher recover
+codex-switcher check
+codex-switcher doctor [--fix]
 ```
 ## 典型流程
 ```bash
-codex-sw add work
-codex-sw add personal
+codex-switcher add work
+codex-switcher add personal
-codex-sw use work --sync
-codex-sw login --sync
-codex-sw exec -- login status
+codex-switcher use work --sync
+codex-switcher login --sync
+codex-switcher exec -- login status
-codex-sw switch personal --sync
-codex-sw app use personal
+codex-switcher switch personal --sync
+codex-switcher app use personal
 ```
 ## 迁移已有数据
@@ -60,14 +60,14 @@ codex-sw app use personal
 如果你原本在 `~/.codex` 下使用 Codex，可先导入到某个 profile：
 ```bash
-codex-sw import-default work
+codex-switcher import-default work
 ```
 默认会迁移记录/项目等数据，但不包含 `auth.json`。
 如需连登录态一起导入：
 ```bash
-codex-sw import-default work --with-auth
+codex-switcher import-default work --with-auth
 ```
 ## 同步行为
@@ -79,27 +79,27 @@ codex-sw import-default work --with-auth
 示例：
 ```bash
-codex-sw login work --sync
-codex-sw switch personal --sync
-codex-sw use work --no-sync
+codex-switcher login work --sync
+codex-switcher switch personal --sync
+codex-switcher use work --no-sync
 ```
 ## 升级
 ```bash
-codex-sw upgrade
+codex-switcher upgrade
 ```
 ## 说明
 - macOS 下 Codex App 是单实例；切换 App profile 需要重启。
-- `codex-sw app stop` 仅停止由 `codex-sw` 启动并跟踪的 App 进程。
-- `codex-sw app open/use <profile>` 要求该 profile 已存在且已登录。
+- `codex-switcher app stop` 仅停止由 `codex-switcher` 启动并跟踪的 App 进程。
+- `codex-switcher app open/use <profile>` 要求该 profile 已存在且已登录。
 - `--sync` 为覆盖策略（不是合并）：源目录覆盖目标目录，`auth.json` 除外。
-- `codex-sw status` 返回码：
+- `codex-switcher status` 返回码：
   - `0`：当前 CLI/App profile 均已登录
   - `1`：至少一个当前 profile 未登录
-  - `2`：指针或 profile 完整性异常（可执行 `codex-sw recover`）
+  - `2`：指针或 profile 完整性异常（可执行 `codex-switcher recover`）
 ## 验证
@@ -109,4 +109,4 @@ codex-sw upgrade
 ## 兼容命令
-`codex-switcher` 作为兼容入口保留，行为与 `codex-sw` 一致。
+`codex-sw` 作为兼容入口保留，行为与 `codex-switcher` 一致。