Metadata-Version: 2.5
Name: cortexctl
Version: 0.1.0.dev20260812142720
Summary: Cortex knowledge base CLI (console command: cortex)
Project-URL: Homepage, https://github.com/eeeming/Cortex
Project-URL: Repository, https://github.com/eeeming/Cortex
Project-URL: Documentation, https://github.com/eeeming/Cortex/blob/test/cli/README.md
Requires-Python: >=3.12
Requires-Dist: typer>=0.26.3
Description-Content-Type: text/markdown

# CLI

Cortex CLI 是根级 Python 项目，命令名为 `cortex`。

CLI 是一期一等入口，但不直接写数据库。当前 CLI 仍通过 `/api/v1` 兼容 HTTP 面访问后端；长期方向是复用后端 application service / usecase，远程 CLI 再沉淀独立命令 / 查询协议，始终遵守 Workspace RBAC。

## 当前骨架

```text
cli/
├── cortex_cli/
│   ├── client.py      # 标准库 HTTP API Client
│   ├── config.py      # 本地 CLI state：API URL、token、默认 Workspace
│   ├── main.py        # Typer CLI 入口
│   └── registry.py    # Agent 友好的命令树元数据
└── tests/
    └── test_cli.py
```

## 已实现命令

当前 CLI 已接入 M3 后端 API 纵切：

```bash
cortex auth login --email owner@example.com --password <debug-password> --json
cortex auth whoami --json
cortex auth logout --json
cortex doctor --json

cortex workspace list --json
cortex workspace create --name 产品团队知识库 --json
cortex workspace use <workspace-id>
cortex workspace get --json
cortex workspace update --name 新名称 --json
cortex workspace delete <workspace-id> --json
cortex workspace leave <workspace-id> --json
cortex workspace transfer-owner <workspace-id> --new-owner-id <user-id> --json

cortex workspace invite list --query user@example.com --status pending --json
cortex workspace invite create --email user@example.com --role editor --json
cortex workspace invite revoke <invite-id> --json
cortex workspace invite enter <invite-id> --json
cortex workspace invite reject <invite-id> --json

cortex workspace member list --query "User Name" --json
cortex workspace member set-role <user-id> --role viewer --json
cortex workspace member remove <user-id> --json
```

说明：

- CLI 命令框架使用 Typer，保留 `cortex commands --json` 作为 Agent 发现入口。
- 直接运行 `cortex` 或无子命令的命令组，如 `cortex workspace`，会显示对应 `--help`。
- 当前 `auth login` 默认使用飞书 OAuth device flow + 后端轮询登录，适配远程容器 Agent；`auth login --method loopback` 保留为本机快捷登录；`auth login --email <email> --password <debug-password>` 保留为后端本地调试登录，且要求后端显式启用该能力。
- `auth logout` 会优先调用服务端 revoke 端点撤销 refresh token，再清理本地 state。
- `doctor` 会检查 API URL、`/health`、`/ready`、本地 state、token 和默认 Workspace。
- `workspace invite list` 和 `workspace member list` 支持 `--page`、`--page-size`、`--query`；邀请列表还支持 `--status pending|accepted|revoked|rejected`。
- 默认后端地址为 `http://127.0.0.1:8000/api/v1`，可用 `CORTEX_API_URL` 或全局 `--api-url` 覆盖；该路径是迁移期 CLI 兼容入口，不作为前端公开 OpenAPI 契约。
- API 请求默认超时为 30 秒，测试或慢速 E2E 环境可用 `CORTEX_CLI_REQUEST_TIMEOUT_SECONDS` 覆盖。
- 本地 state 默认写入 `~/.config/cortex/state.json`，保存时会设置为仅当前用户可读写；测试或自动化可用 `CORTEX_CLI_STATE` 覆盖。
- 未显式传 `workspace_id` 的 Workspace 子命令会读取 `cortex workspace use <workspace-id>` 设置的默认 Workspace。

## 向量索引运维

向量索引投影异常不会由普通查询、处理或启动路径自动清空 / 重建向量表。CLI 只提供状态读取和显式 rebuild 入口：

```bash
cortex vector-index status --workspace-id <workspace-id> --json
cortex vector-index rebuild --workspace-id <workspace-id> --dry-run --json
cortex vector-index rebuild --workspace-id <workspace-id> --yes --json
```

`status --json` 会根据后端 Workspace 状态输出 `needs_rebuild`、索引状态和错误摘要字段，方便 Agent 判断是否需要提示用户执行 rebuild。`rebuild` 是写入型运维动作，必须先 dry-run 或传 `--yes`。

## 安装（用户 / Agent，与 Skills 一致）

安装后 PATH 中应有 **`cortex`** 命令。用户侧 Skills（`skills/cortex-upload`、`skills/cortex-search`）假定本机已安装 CLI，直接调用 `cortex …`。

**命名说明**

| 概念           | 名称            | 说明                                            |
| -------------- | --------------- | ----------------------------------------------- |
| 控制台命令     | `cortex`        | 用户与 Skills 实际调用的入口                    |
| PyPI / uv 包名 | **`cortexctl`** | 发行名（`cortex-cli` 在 PyPI 已被无关项目占用） |
| 实现源码       | monorepo `cli/` | 与后端同仓开发；业务镜像 **不 COPY `cli/`**     |

**前置**：Python ≥ 3.12，并已安装 [uv](https://docs.astral.sh/uv/)（推荐）或 pipx。

### 推荐：从 PyPI 安装

```bash
# 包名 cortexctl，安装后命令为 cortex
# 默认安装最新「正式版」（不含 .dev 预发布）
uv tool install cortexctl

# 需要测试通道（test 分支自动发布的预发布号，如 0.1.0.dev20260811153045）
uv tool install --prerelease=allow cortexctl
# 或钉死：uv tool install "cortexctl==0.1.0.dev20260811153045"

# 升级正式版
uv tool upgrade cortexctl
```

等价（pipx）：

```bash
pipx install cortexctl
```

**版本通道**

| 来源                            | 版本形态                 | 如何产生           |
| ------------------------------- | ------------------------ | ------------------ |
| `test` 分支变更 `cli/**`        | 预发布 `X.Y.Z.dev时间戳` | CI 自动发布到 PyPI |
| `main` + tag `cortexctl-vX.Y.Z` | 正式 `X.Y.Z`             | 打 tag 后 CI 发布  |
| `main` 仅 push                  | 不自动发布               | 只跑打包冒烟       |

> 若 PyPI 上尚无任何版本，请用下方「从 monorepo 源码 / Git」安装。

### 备选：从 monorepo 源码或 Git 安装（开发 / 未发布时）

```bash
# 本地 monorepo
uv tool install /path/to/Cortex/cli

# 或直接从 GitHub monorepo 的 cli 子目录
uv tool install "git+https://github.com/eeeming/Cortex.git@test#subdirectory=cli"
```

### 安装后自检与登录

```bash
cortex version --json
cortex doctor --json

# 指向你的 Cortex API（默认 http://127.0.0.1:8000/api/v1）
export CORTEX_API_URL="https://<your-host>/api/v1"
# 或：cortex --api-url "https://<your-host>/api/v1" auth whoami --json

cortex auth login
cortex workspace list --json
```

与 Skills 的关系：Agent 执行上传 / 查知识时使用同一套 `cortex` 子命令；请先完成安装与 `auth login` / `workspace use`。

### Docker（可选，非桌面主路径）

CI 会构建 `ghcr.io/eeeming/cortex/cortex-cli:<sha>`（镜像名历史沿用），适合容器内一次性调用，不替代本机 `uv tool install cortexctl`。

```bash
docker run --rm -e CORTEX_API_URL=https://<your-host>/api/v1 \
  ghcr.io/eeeming/cortex/cortex-cli:test version --json
```

---

## 分发与服务端精简

| 形态                   | 用户如何得到 `cortex`                  | 服务端 / 镜像                                                 |
| ---------------------- | -------------------------------------- | ------------------------------------------------------------- |
| **PyPI（推荐）**       | `uv tool install cortexctl`            | monorepo `cli/` 为真相源；backend/frontend **不 COPY `cli/`** |
| **Git / 源码（备选）** | monorepo `subdirectory=cli` 或本地路径 | 同上                                                          |
| **独立公开仓**         | 已弃用（不再作为安装主路径）           | —                                                             |

### PyPI / `uv publish`

- 分发包名：**`cortexctl`**；命令：**`cortex`**。
- `project.urls.Repository` → `https://github.com/eeeming/Cortex`（主仓）。
- 维护者：

```bash
cd cli
uv build
# 配置 PyPI token 或 Trusted Publisher 后：
uv publish
```

CI：

- 每次改 `cli/**`：build + wheel 安装 + `cortex version` 冒烟。
- 可选发布：`workflow_dispatch` 勾选 publish，或推送 tag `cortexctl-v*`（需 `UV_PUBLISH_TOKEN` / Trusted Publishing）。

未配置密钥时 CI **不会**假装已上传到 PyPI。

### 服务端精简镜像

- 生产 compose 只部署 backend-api / worker / frontend（及中间件）。
- `docker/backend/Dockerfile` 与 `docker/frontend/Dockerfile` **不得** `COPY cli/`。
- 用户 CLI 走本机 `cortexctl`（PyPI）；运维可选独立 GHCR CLI 镜像。

---

## 本地开发运行

```bash
cd cli
uv run cortex version --json
uv run cortex commands --json
uv run cortex auth login
uv run cortex auth login --email owner@example.com --password <debug-password> --json
uv run pytest
```
