mcpField
H
helix-cli

helix-cli

github.com/helixdb云与 DevOps4244 次安装4 天前更新
代码仓库

关于 helix-cli

Helix CLI 是用于操作 Helix 本地实例和云端实例的运行时及控制平面客户端，支持本地查询与 Shell 工作流，以及云端认证、发现和关联；它不编译或部署 `.hx` 文件。

主要功能

  1. 01启动和停止本地实例
  2. 02运行查询并打开 Shell
  3. 03配置本地存储选项
  4. 04认证 Helix Cloud
  5. 05发现并关联云端实例

适用场景

  1. 01运行本地 Helix 开发实例
  2. 02从文件查询本地实例
  3. 03打开实例的 Shell
  4. 04将项目关联到云端实例

MCP 相关

README 提到可通过 `helix service-credential create` 创建无头 API/MCP 令牌，并说明 CLI 不会存储或使用这些令牌。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/helixdb/skills --skill helix-cli

安装后在 Claude Code 中输入/helix-cli确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

EXAMPLES.md
REFERENCE.md
agents/
openai.yaml

详细介绍

Helix CLI

将 CLI 用作运行时和控制平面客户端。它不会编译 .hx 文件、部署查询包、推送源代码或同步网关元数据。

选择执行边界

  • 本地 [local.<name>]：Docker/Podman、禁用身份验证的本地 /v2/query。
  • 云端 [enterprise.<name>]：稳定的 tenant:<id> 或专用的 cluster:<id> 关联。
  • 云端 query 和 shell：通过后端查询代理，绝不直接请求网关。
  • 直接访问应用网关：不在 CLI 身份验证范围内；需显式创建数据库密钥。

本地镜像和存储

使用 ghcr.io/helixdb/helixdb:v0.0.5。在启动现有项目或使用默认版本较旧的 CLI 之前，在相关的 [local.<name>] 配置块中设置 tag = "v0.0.5"。服务会在端口 8080 上提供 /healthz、/readyz 和 /v2/query；CLI 默认使用主机端口 6969，并等待 /healthz。

默认使用内存，停止或重启后数据会丢失。CLI 的 --disk 使用 MinIO；--storage-uri 用于选择现有的 S3 兼容存储。直接使用 Docker 原生持久化时，通过 HELIX_DATA_DIR 指定可写的挂载目录。HELIX_DATA_DIR 和 S3_BUCKET 不能同时设置；内存模式下两者都不设置。S3 标志请参阅 REFERENCE.md，不同的存储设置请参阅 EXAMPLES.md。

云端身份验证

仅使用：

helix auth login
helix auth status
helix auth logout

登录采用 WorkOS PKCE。CLI 通过 WFE 轮换会话。绝不要索要或设置 Cloud API 密钥、旧版管理员/用户密钥、服务凭证、自定义授权标头或网关 URL。不要重试云端变更操作：只有 WFE 在处理程序分发前明确拒绝会话时，客户端才可重试一次。

目标解析

优先使用显式的 --workspace、--project、cluster:<id> 或 tenant:<id>。对于 query 和 shell，如果指定了实例则优先使用；否则使用本地 dev，然后使用唯一关联的实例。如果仍有多个实例，请列出并要求显式指定实例。其他云端命令仅在目标明确无误时，才使用当前 helix.toml 中关联的数据库/项目。没有全局工作区选择，也没有 workspace switch。

主要工作流

# Local
helix init local
helix start dev
helix query dev --file examples/request.json
helix shell dev
helix stop dev

# Cloud discovery and linkage
helix auth login
helix workspace list
helix project list --workspace-id <workspace>
helix database list --project <project>
helix project link <project>
helix add cloud --name production --database tenant:<tenant>
helix query production --file request.json

云端读写请求封装分别需要独立的 database.query.read / database.query.write 权限。管理操作的 read/write 权限不代表具有查询权限。

密钥生命周期

  • helix database create 会创建默认的读写应用密钥，并只显示一次其令牌；CLI 不会保存或使用该令牌。
  • helix database key create ... --access read-only|read-write 会只显示一次应用令牌；CLI 不会保存或使用该令牌。
  • helix service-credential create 会只显示一次无头 API/MCP 令牌；CLI 不会保存该令牌，也不会使用它进行身份验证。
  • 绝不要将任何令牌放入 helix.toml、Agent 指令、源代码管理或命令历史记录中。

已移除和排除的功能

不要使用或推荐 push、sync、auth create-key、workspace switch、查询包、专用集群生命周期管理、网络、区域/SKU、分支/备份、架构内省、执行轮询/取消、Webhooks 或项目更新。

精确命令和配置请参阅 REFERENCE.md，安全会话请参阅 EXAMPLES.md。使用 helix-query-* 技能编写 v3 请求正文。

评论

支持 Markdown