mcpField
H
helix-cli

helix-cli

github.com/helixdbクラウド・DevOps4244 回インストール4 日前に更新
リポジトリ

helix-cli について

Helix CLIは、Helixのローカルおよびクラウドインスタンスを操作するランタイム兼コントロールプレーンクライアントです。ローカルでのクエリやシェル操作、クラウド認証、検出、リンクに対応し、`.hx`ファイルのコンパイルやデプロイは行いません。

主な機能

  1. 01ローカルインスタンスの起動と停止
  2. 02クエリの実行とシェルの起動
  3. 03ローカルストレージ設定
  4. 04Helix Cloudへの認証
  5. 05クラウドインスタンスの検出とリンク

活用シーン

  1. 01ローカルのHelix開発インスタンスを起動
  2. 02ファイルからローカルインスタンスをクエリ
  3. 03インスタンスのシェルを起動
  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 を要求または設定しないでください。Cloud の変更操作を再試行しないでください。クライアントが再試行できるのは、ハンドラーのディスパッチ前に WFE が明示的にセッションを拒否した場合に限り、1 回だけです。

ターゲットの解決

明示的な --workspace、--project、cluster:<id>、または tenant:<id> を優先します。query と shell では、明示的に指定したインスタンスを優先します。指定がない場合は、ローカルの dev、次にリンク済みのインスタンスが 1 つだけならそのインスタンスを使用します。複数のインスタンスが残る場合は一覧表示し、明示的なインスタンスの指定を求めます。その他の Cloud コマンドでは、曖昧さがない場合に限り、現在の 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

Cloud の読み取り／書き込みエンベロープには、独立した 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、エージェントへの指示、ソース管理、コマンド履歴に含めないでください。

削除および対象外の機能

push、sync、auth create-key、workspace switch、クエリバンドル、専用クラスターのライフサイクル、ネットワーキング、リージョン／SKU、ブランチ／バックアップ、スキーマのイントロスペクション、実行のポーリング／キャンセル、ウェブフック、プロジェクトの更新は使用または推奨しないでください。

正確なコマンド／設定については REFERENCE.md を、安全なセッションについては EXAMPLES.md を参照してください。v3 リクエスト本文を作成するには、helix-query-* スキルを使用してください。

コメント

Markdown 対応