CLI

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

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

当前骨架

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 纵切：

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 入口：

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 …。

命名说明

前置：Python ≥ 3.12，并已安装 uv（推荐）或 pipx。

推荐：从 PyPI 安装

# 包名 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）：

pipx install cortexctl

版本通道

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

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

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

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

安装后自检与登录

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。

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

分发与服务端精简

PyPI / uv publish

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

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 镜像。

本地开发运行

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