hanectl

このページでは、定義とプロジェクトを操作する CLI hanectl の使い方を説明します。hanectl は公開 API を呼ぶ CLI で、マニフェストの検証には Hane のサーバーと同じ検査を使います。hanectl --help ですべてのコマンドを表示できます。

入れる

配る実行ファイルは単一のファイルで、Node.js は要りません。

ファイル	動く環境
hanectl-darwin-arm64	Apple Silicon の macOS
hanectl-darwin-x64	Intel の macOS
hanectl-linux-arm64	arm64 の Linux（glibc）
hanectl-linux-x64	x64 の Linux（glibc）。Windows は WSL2 で

shasum -a 256 -c SHA256SUMS --ignore-missing
install -m 755 hanectl-darwin-arm64 ~/.local/bin/hanectl
hanectl version

注意

macOS の実行ファイルは公証していません。ブラウザで取ると Gatekeeper に止められることがあります。Alpine などの musl の Linux では動きません。

ログインと context

hanectl は、組織・プロジェクト・環境の組を context として ~/.config/hanectl/config.json に保存します。環境変数 HANECTL_CONFIG で場所を替えられます。

# サービスアカウントの API キーで（CI など）
hanectl login --api-key "$HANE_API_KEY" --org acme --project fleet --env dev --server https://<入口の URL>

# IdP が出した id_token で（HANECTL_ID_TOKEN でも渡せる）
hanectl login --id-token "$ID_TOKEN" --org acme --project fleet --env dev --server https://<入口の URL>

hanectl config get-contexts
hanectl config use-context acme/fleet/prod
hanectl token        # 今の context のアクセストークンを出す（スクリプト用）

• id_token でログインしたアクセストークンは 15 分で切れます。切れたらログインし直します。
• どのコマンドも --context <名前> で、今の context 以外を指定できます。
• 入口の前に Cloudflare Access がある環境へ自動化で送るときは、HANE_ACCESS_CLIENT_ID と HANE_ACCESS_CLIENT_SECRET（Access のサービストークン）を環境変数で渡します。

定義を入れる

コマンド	すること
hanectl validate -f <dir>	手元で形と参照を確かめる（ログイン不要）
hanectl diff -f <dir> [--prune] [-o json]	apply で何が変わるかを見る
hanectl apply -f <dir> [--prune]	draft として保存する。すぐ効く設定はこの時点で効く
hanectl get <kind> [name] [-o yaml|json]	draft を表示する
hanectl get --at <時刻>	その時点の有効な ReleaseBundle と設定を表示する

--prune を付けると、ディレクトリにない定義を廃止の扱いにします。diff の出力は、+ が追加、~ が変更、- が廃止、! が範囲を広げる変更です。

apply は、リポジトリ・コミット・パスを出どころとして記録します。コミットしていない変更があるときと、HEAD を push していないときはコミットを記録せず、警告を出します。

ReleaseBundle を作って有効にする

hanectl release create -f definitions/bundle.yaml --activate
hanectl release list
hanectl release show <release_id>
hanectl release activate <release_id>

stage と prod へ昇格する

dev で確かめた ReleaseBundle を、別の環境の context へ写します。stage と prod の有効化には、そのバージョンの評価（EvalSuite）がすべて通っていることが要ります。

hanectl release promote <release_id> --to acme/fleet/stage

• prod の有効化・戻す・カナリアは、人が自分のログインで行います。CI の API キーで有効にしようとした ReleaseBundle は pending に残って人を待ちます。
• AI に承認を任せる範囲を広げる ReleaseBundle と、stage と prod で Agent に新しい外への操作のツールを持たせる ReleaseBundle は、作った人と別の人が hanectl release review <id> --comment <理由> で確かめるまで有効にできません。
• 環境ごとに違う名前（Connection・送信の名義・秘密値）は EnvironmentBinding に書き、その環境の context で apply します。

一部の新しい案件で試す

hanectl release canary <release_id> --percent 10
hanectl release canary promote   # 有効にする
hanectl release canary abort     # やめる

状態を見て戻す

hanectl rollout status     # 有効な ReleaseBundle と、人を待っているもの
hanectl rollout history
hanectl rollout undo       # 1 つ前の ReleaseBundle に戻す
hanectl rollout undo <kind> <name>   # 設定を 1 つ前のリビジョンに戻す

項目の名前や型を変える Migration を含む ReleaseBundle は、有効にする前に backfill を流せます。戻せない Migration があると、そこで戻すのが止まります。

hanectl migrate status <release_id>
hanectl migrate backfill <release_id>

Git から同期する

コミットごとに 1 つの ReleaseBundle を作ります。同じコミットからは作り直しません。

hanectl git sync . --ref main --path definitions --activate
hanectl git hook install . --path definitions   # コミットとマージの後に同期する

Hane に Git を取りに行かせる場合は、GitSource を apply して登録します。登録したプロジェクトでは apply は拒否され、Git だけが入力になります（hanectl git source list|show|sync|pause|resume|delete|webhook）。

そのほかのコマンド

コマンド	すること
hanectl import <Type> -f <file.csv> [--state estimated] [--label <名前>]	CSV を取り込む
hanectl schedules list・trigger <name>	スケジュールを見る・今日の日付で発火する
hanectl runs list [--agent <name>] [--case <id>]・show <id>・cancel <id>	AgentRun を見る・止める
hanectl documents facts・stats・eval ...	抽出の候補、確認の結果の数え、評価セット
hanectl ontology resolve・query・actions	オントロジーの言葉と関係をたどる
hanectl subscriptions list・deliveries <id>・resume <id>	購読と webhook の配信の記録を見る、再開する
hanectl app create・deploy・build・image ...	Hane が配信するアプリを作る（プレビュー）

多くのコマンドは -o json で JSON を出します。失敗すると終了コード 1 を返すので、CI でそのまま使えます。

次に読む

マニフェストを書く定義の種類と書き方

定義とリリースdraft・ReleaseBundle・昇格