Route desktop through clovapi CLI and unify Codex detection.

Electron calls top-level profiles, switch, auth, and proxy commands instead of bespoke bridges; add CODEX_HOME-aware config and broader Codex install discovery for CLI and app.

Author: joohw

README.en.md

@@ -24,8 +24,12 @@ clovapi --help
 
 | Command | Description |
 |---------|-------------|
-| `clovapi list` | Show profiles and CLI matrix (aliases `profiles` / `ls`) |
-| `clovapi add --name NAME` | Save upstream profile and probe ( `set` / `new`) |
-| `clovapi switch [--cli KIND]` | Apply profile to one CLI (`use`) |
-| `clovapi proxy` | Built-in local proxy (`start` / `status` / `config`) |
+| `clovapi list` | Show profiles and active CLI bindings (alias `ls`) |
+| `clovapi profiles` | JSON API for load/save/test/catalog (`--json`; see `core/README.md`) |
+| `clovapi add --name NAME` | Save upstream profile and probe (`set` / `new`) |
+| `clovapi switch [--cli KIND]` | Apply binding to one CLI (`use`; add `--json` for scripts) |
+| `clovapi auth` | Subscription OAuth (`status` / `login` / `logout`; `--json`) |
+| `clovapi proxy` | Built-in local proxy (`start` / `stop` / `status` / `health`; `--json` where supported) |
 | `clovapi reset` | Clear all profiles and bindings (`--yes`) |
+
+Details: [core/README.md](core/README.md).

README.md

@@ -24,8 +24,12 @@ clovapi --help
 
 | 命令 | 说明 |
 |------|------|
-| `clovapi list` | 展示 profiles 与 CLI 矩阵（别名 `profiles` / `ls`） |
+| `clovapi list` | 展示 profiles 与各 CLI 的 active 绑定（别名 `ls`） |
+| `clovapi profiles` | 加载/保存/测试 profiles 的 JSON API（`--json`；详见 `core/README.zh.md`） |
 | `clovapi add --name NAME` | 保存上游 profile 并测连通（`set` / `new`） |
-| `clovapi switch [--cli KIND]` | 将 profile 应用到某一 CLI（`use`） |
-| `clovapi proxy` | 内置本地代理（`start` / `status` / `config`） |
-| `clovapi reset` | 清空全部 profile 与绑定（`--yes`） |
+| `clovapi switch [--cli KIND]` | 将绑定应用到某一 CLI（`use`；脚本可加 `--json`） |
+| `clovapi auth` | 订阅 OAuth（`status` / `login` / `logout`；支持 `--json`） |
+| `clovapi proxy` | 内置本地代理（`start` / `stop` / `status` / `health` 等） |
+| `clovapi reset` | 清空全部 profile 与绑定（`--yes`） |
+
+详细说明见 [core/README.zh.md](core/README.zh.md)。

core/README.md

@@ -16,13 +16,40 @@ For **Claude Code**, env wiring matches community **cc-switch** / **ccswitch**;
 
 | Command | Description |
 |--------|-------------|
-| `clovapi list` | Show saved profiles, CLI ↔ API-style matrix, and last-applied CLIs (aliases: **`profiles`**, **`ls`**) |
+| `clovapi list` | Show saved profiles and active CLI bindings (alias: **`ls`**) |
+| `clovapi profiles` | Load/save/test profiles and vendor helpers for scripts and the desktop UI (see below) |
 | `clovapi add --name NAME` | Save one upstream profile (CLI is chosen at switch time); connectivity test before persist (`--name` required, aliases: **`set`**, **`new`**) |
 | `clovapi remove <name>` | Remove one saved profile (aliases: **`rm`**, **`delete`**) |
-| `clovapi switch [--cli KIND] [VENDOR/MODEL]` | Apply a vendor model binding to one CLI (`--vendor` + `--model`, or interactive vendor → model). Alias **`use`** |
-| `clovapi proxy` | Run and inspect the built-in local proxy core (`start`, `status`, `config`) |
+| `clovapi switch [--cli KIND] [VENDOR/MODEL]` | Apply a provider/model binding to one CLI (`--provider` + `--model`, `--vendor` + `--model`, or interactive). Alias **`use`**. Add **`--json`** for machine-readable output |
+| `clovapi auth` | Claude/Codex subscription OAuth (`status`, `login`, `logout`; **`--json`** on each) |
+| `clovapi proxy` | Run and inspect the built-in local proxy (`start`, `stop`, `status`, `health`, `config`, `logs`, …; **`--json`** on `status` / `health`) |
 | `clovapi reset` | Clear all saved profiles and bindings (`--yes` / `-y` skips prompt) |
 
+### `clovapi profiles` (JSON API)
+
+Subcommands mirror what the desktop app and Electron shell call. Pass **`--json`** for structured stdout (stdin JSON for `save`):
+
+| Subcommand | Description |
+|------------|-------------|
+| `load --json` | Read normalized `profiles.json` (vendors, `active`, proxy bind) |
+| `save --json` | Merge payload from stdin and persist |
+| `test --json` | Probe a provider/model via the local proxy (`--provider`, `--model`, optional `--cli`, `--port`) |
+| `list-models --vendor NAME --json` | Fetch and merge models for one vendor |
+| `usage --vendor NAME --json` | Query upstream quota/balance for one API vendor |
+| `catalog --json` | Fixed provider registry and model-adapter catalog |
+
+Legacy **`clovapi desktop profiles|vendor|auth …`** remains for older scripts; prefer the top-level commands above.
+
+Script examples:
+
+```bash
+clovapi profiles load --json
+clovapi profiles save --json < payload.json
+clovapi switch --cli opencode --provider custom-api --model my-model --json
+clovapi auth status --json
+clovapi proxy status --json
+```
+
 ## Build
 
 ```bash
@@ -59,10 +86,9 @@ cd core && go test ./...
 - **Unix** (macOS/Linux): `$XDG_CONFIG_HOME/clovapi` or `~/.config/clovapi`
 - **Windows**: `%APPDATA%\clovapi`
 
-State file: `profiles.json` (0600). It stores **`profiles`** (all saved rows) and **`active`** (last applied profile name per CLI).
-
-`clovapi switch` always targets a single CLI. Use `--cli` for non-interactive scripts. Each CLI adapter picks the appropriate upstream API style internally — you do not need to match styles manually.
+State file: `profiles.json` (0600). It stores **`profiles`** (vendor rows and models), **`active`** (per CLI: `provider_id` + `model_id`), and **`proxy`** (local bind host/port).
 
+`clovapi switch` always targets a single CLI. Use `--cli` for non-interactive scripts. Prefer **`--provider`** + **`--model`** (or **`--vendor`** + **`--model`**) in automation; add **`--json`** when a caller needs structured success/error output.
 ## Apply behavior (summary)
 
 - **claude-code** + `claude`: writes `~/.claude/settings.json` with **`env.ANTHROPIC_AUTH_TOKEN`** and **`ANTHROPIC_BASE_URL`** (same pattern as ccswitch). **`ANTHROPIC_API_KEY` is removed** from `env` so Claude Code does not show “Auth conflict: Both a token and an API key are set”.
@@ -86,11 +112,13 @@ Paths expand correctly on Windows (user profile / AppData).
 
 | clovapi | Alias(es) | Similar to |
 |---------|-----------|------------|
-| `list` | `profiles`, `ls` | `cc-switch list`, `ccswitch list` |
+| `list` | `ls` | `cc-switch list`, `ccswitch list` |
+| `profiles` | _(command group, not a list alias)_ | Desktop/script JSON API for `profiles.json` |
 | `add` | `set`, `new` | One-shot save of upstream binding |
-| `switch [--cli …]` | `use …` | Apply one saved profile into one tool config |
+| `switch [--cli …]` | `use …` | Apply one binding into one tool config |
 | `remove NAME` | `rm`, `delete` | Delete one saved profile |
 
+**Note:** Older docs used `clovapi profiles` as an alias for `list`. That alias was removed when **`profiles`** became its own subcommand group (`load`, `save`, …). Use **`clovapi list`** or **`clovapi ls`** for the human table.
 ### Where state lives
 
 | Tool | Stored profiles |

core/README.zh.md

@@ -16,13 +16,40 @@
 
 | 命令 | 说明 |
 |------|------|
-| `clovapi list` | 展示已保存的 profiles、CLI ↔ API 形态矩阵、上次下发的 CLI（别名：**`profiles`**、**`ls`**） |
+| `clovapi list` | 展示已保存的 profiles 与各 CLI 的 active 绑定（别名：**`ls`**） |
+| `clovapi profiles` | 为脚本与桌面 UI 加载/保存/测试 profiles（见下文） |
 | `clovapi add --name NAME` | 保存一个上游 profile（CLI 在 switch 时再选择）；持久化前先测连通（`--name` 必填，别名：**`set`**、**`new`**） |
 | `clovapi remove <name>` | 删除一条已保存 profile（别名：**`rm`**、**`delete`**） |
-| `switch [--cli KIND] [VENDOR/MODEL]` | 将某个 vendor 下的模型绑定应用到某一 CLI（`--vendor` + `--model`，或交互式选 vendor → model）。别名 **`use`** |
-| `clovapi proxy` | 运行并查看内置本地代理核心（`start`、`status`、`config`） |
+| `clovapi switch [--cli KIND] [VENDOR/MODEL]` | 将 provider/model 绑定应用到某一 CLI（`--provider` + `--model`、`--vendor` + `--model`，或交互选择）。别名 **`use`**。脚本可加 **`--json`** |
+| `clovapi auth` | Claude/Codex 订阅 OAuth（`status`、`login`、`logout`；均可 **`--json`**） |
+| `clovapi proxy` | 运行并查看内置本地代理（`start`、`stop`、`status`、`health`、`config`、`logs` 等；`status` / `health` 支持 **`--json`**） |
 | `clovapi reset` | 清空所有 profile 与绑定记录（**`--yes`** / **`-y`** 跳过确认） |
 
+### `clovapi profiles`（JSON API）
+
+子命令与桌面端 / Electron 调用一致。加 **`--json`** 输出结构化 JSON（`save` 从 stdin 读 JSON）：
+
+| 子命令 | 说明 |
+|--------|------|
+| `load --json` | 读取规范化后的 `profiles.json`（vendors、`active`、proxy 绑定） |
+| `save --json` | 合并 stdin 载荷并写盘 |
+| `test --json` | 经本地代理探测 provider/model（`--provider`、`--model`，可选 `--cli`、`--port`） |
+| `list-models --vendor NAME --json` | 拉取并合并某一 vendor 的模型列表 |
+| `usage --vendor NAME --json` | 查询某一 API vendor 的额度/余额 |
+| `catalog --json` | 固定 provider 注册表与 model adapter 目录 |
+
+旧版 **`clovapi desktop profiles|vendor|auth …`** 仍可用；新脚本请优先用上述顶层命令。
+
+示例：
+
+```bash
+clovapi profiles load --json
+clovapi profiles save --json < payload.json
+clovapi switch --cli opencode --provider custom-api --model my-model --json
+clovapi auth status --json
+clovapi proxy status --json
+```
+
 ## 构建
 
 ```bash
@@ -59,16 +86,16 @@ cd core && go test ./...
 - **Unix**（macOS/Linux）：`$XDG_CONFIG_HOME/clovapi` 或 `~/.config/clovapi`
 - **Windows**：`%APPDATA%\clovapi`
 
-状态文件：`profiles.json`（权限 0600）。内含 **`profiles`**（vendor 与模型列表）和 **`active`**（每个 CLI 的 `@model:Vendor/model-id` 绑定）。
+状态文件：`profiles.json`（权限 0600）。内含 **`profiles`**（vendor 与模型列表）、**`active`**（每个 CLI 的 `provider_id` + `model_id`），以及 **`proxy`**（本地监听 host/port）。
 
 `clovapi switch` 始终只针对单一 CLI。交互流程：**选 CLI → 选 vendor → 选 model**。脚本示例：
 
 ```bash
+clovapi switch --cli codex --provider codex --model gpt-5.5 --json
 clovapi switch --cli codex --vendor "Codex Subscription" --model gpt-5.5
 clovapi switch --cli codex "Codex Subscription/gpt-5.5"
 clovapi switch --cli codex   # 无参数时复用 active 绑定，或进入交互选择
 ```
-
 ## 下发行为摘要
 
 - **claude-code** + `claude`：写入 `~/.claude/settings.json`，设置 **`env.ANTHROPIC_AUTH_TOKEN`** 与 **`ANTHROPIC_BASE_URL`**（与 ccswitch 同款）。从 `env` 中**移除 `ANTHROPIC_API_KEY`**，避免 Claude Code 提示「Auth conflict: Both a token and an API key are set」。
@@ -92,11 +119,13 @@ clovapi switch --cli codex   # 无参数时复用 active 绑定，或进入交
 
 | clovapi | 别名 | 类似 |
 |---------|------|------|
-| `list` | `profiles`、`ls` | `cc-switch list`、`ccswitch list` |
+| `list` | `ls` | `cc-switch list`、`ccswitch list` |
+| `profiles` | _（子命令组，不是 list 的别名）_ | 桌面/脚本的 `profiles.json` JSON API |
 | `add` | `set`、`new` | 一次性保存上游绑定 |
-| `switch [--cli …]` | `use …` | 将单个 profile 推入单一工具 |
+| `switch [--cli …]` | `use …` | 将单个绑定推入单一工具 |
 | `remove NAME` | `rm`、`delete` | 删除单条 profile |
 
+**说明：** 旧文档曾把 `clovapi profiles` 当作 `list` 的别名；现 **`profiles`** 为独立子命令组（`load`、`save` 等）。查看人类可读表格请用 **`clovapi list`** 或 **`clovapi ls`**。
 ### 状态存放位置
 
 | 工具 | 配置存放 |

core/cmd/auth_cmd.go

@@ -0,0 +1,122 @@
+package main
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/clovapi/switcher/internal/desktop"
+)
+
+func cmdAuth() *cobra.Command {
+	c := &cobra.Command{
+		Use:   "auth",
+		Short: "Claude/Codex subscription OAuth login",
+	}
+	c.AddCommand(cmdAuthStatus(), cmdAuthLogin(), cmdAuthLogout())
+	return c
+}
+
+func cmdAuthStatus() *cobra.Command {
+	var jsonFlag bool
+	c := &cobra.Command{
+		Use:   "status",
+		Short: "Report Claude/Codex subscription login status",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			result := desktop.AuthStatus()
+			if jsonFlag {
+				return writeDesktopJSON(result)
+			}
+			return printAuthStatus(result)
+		},
+	}
+	c.Flags().BoolVar(&jsonFlag, "json", false, "Return JSON")
+	return c
+}
+
+func cmdAuthLogin() *cobra.Command {
+	var providerID string
+	var jsonFlag bool
+	c := &cobra.Command{
+		Use:   "login",
+		Short: "Run subscription OAuth login in the browser",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			result := desktop.AuthLogin(cmd.Context(), providerID)
+			if jsonFlag {
+				return writeDesktopJSON(result)
+			}
+			return printAuthLoginResult(result)
+		},
+	}
+	c.Flags().StringVar(&providerID, "provider", "", "Provider id: claude-code|codex")
+	c.Flags().BoolVar(&jsonFlag, "json", false, "Return JSON")
+	return c
+}
+
+func cmdAuthLogout() *cobra.Command {
+	var providerID string
+	var jsonFlag bool
+	c := &cobra.Command{
+		Use:   "logout",
+		Short: "Remove subscription OAuth credentials",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			result := desktop.AuthLogout(providerID)
+			if jsonFlag {
+				return writeDesktopJSON(result)
+			}
+			return printAuthLogoutResult(result)
+		},
+	}
+	c.Flags().StringVar(&providerID, "provider", "", "Provider id: claude-code|codex")
+	c.Flags().BoolVar(&jsonFlag, "json", false, "Return JSON")
+	return c
+}
+
+func printAuthStatus(result desktop.AuthStatusResult) error {
+	if !result.OK {
+		if msg := strings.TrimSpace(result.Error); msg != "" {
+			return fmt.Errorf("%s", msg)
+		}
+		return fmt.Errorf("failed to read subscription status")
+	}
+	for _, item := range result.Items {
+		state := "not logged in"
+		if item.LoggedIn {
+			state = "logged in"
+		}
+		summary := strings.TrimSpace(item.Summary)
+		if summary != "" {
+			fmt.Printf("%s (%s): %s — %s\n", item.Label, item.ID, state, summary)
+		} else {
+			fmt.Printf("%s (%s): %s\n", item.Label, item.ID, state)
+		}
+	}
+	return nil
+}
+
+func printAuthLoginResult(result desktop.AuthLoginResult) error {
+	if result.OK {
+		fmt.Println("Subscription login succeeded.")
+		if url := strings.TrimSpace(result.AuthorizeURL); url != "" {
+			fmt.Println("If the browser did not open, visit:")
+			fmt.Println(url)
+		}
+		return nil
+	}
+	if msg := strings.TrimSpace(result.Error); msg != "" {
+		return fmt.Errorf("%s", msg)
+	}
+	return fmt.Errorf("subscription login failed")
+}
+
+func printAuthLogoutResult(result desktop.AuthLogoutResult) error {
+	if result.OK {
+		fmt.Println("Subscription logout succeeded.")
+		return nil
+	}
+	if msg := strings.TrimSpace(result.Error); msg != "" {
+		return fmt.Errorf("%s", msg)
+	}
+	return fmt.Errorf("subscription logout failed")
+}