CLI クイックスタート¶

本ドキュメントは、初めて OWL CLI を使用するユーザーを対象に、OWL CLI の設定、ツールカタログの同期、およびツールの呼び出し実行方法を説明します。

前提条件¶

開始前に以下を確認してください。

OWL の手動インストールまたは OWL の自動インストールが完了していること
ワークスペースが属するサイトに対応する OWL CLI Endpoint を取得していること（Endpoint 一覧を参照）
アクセストークン OWL_TOKEN または OWL_API_KEY を取得していること（DF-API-KEY を参照）
現在の端末から OWL CLI Endpoint にアクセスできること

ステップ 1：Endpoint とアクセストークンを設定する¶

OWL CLI では、環境変数またはローカル設定ファイルを使用して Endpoint とアクセストークンを設定できます。

OWL_REGISTRY_ENDPOINT には Endpoint のルートアドレスのみを指定し、/api/v1 などのパスを手動で追加しないでください。

方法 1：環境変数を使用する¶

bash / zshPowerShell

export OWL_REGISTRY_ENDPOINT="your-owl-endpoint"
export OWL_TOKEN="your-token"

$env:OWL_REGISTRY_ENDPOINT = "your-owl-endpoint"
$env:OWL_TOKEN = "your-token"

環境変数は現在の端末セッションでのみ有効です。端末を閉じた後に再度使用する場合は、再設定が必要です。

アクセストークンは OWL_API_KEY でも設定できます。OWL_API_KEY と OWL_TOKEN の両方が存在する場合、OWL CLI は OWL_API_KEY を優先します。

方法 2：ローカル設定ファイルに書き込む¶

owl init
owl login

実行手順：

owl init は OWL CLI Endpoint を書き込むために使用します
owl login はアクセストークンを書き込むために使用します

ローカル設定は OWL CLI の設定ディレクトリに書き込まれ、新しい端末を開いた後も引き続き使用できます。

環境変数は設定ファイルよりも優先されます。現在の端末で環境変数が設定されている場合、OWL CLI は環境変数の値を優先して使用します。

ステップ 2：ツールカタログを同期する¶

初めて OWL CLI を使用する前に、ツールカタログを同期する必要があります。

owl sync

owl sync は、Guance で現在利用可能なカテゴリとツールのメタデータをローカルキャッシュに同期します。同期が完了すると、ツールの表示と実行が可能になります。

特定のカテゴリのみを同期する場合は、-c でカテゴリを指定します。

owl sync -c data

ステップ 3：ツールを表示する¶

すべてのツールカテゴリを表示する。

owl category list

特定のカテゴリ配下のツールを表示する。

owl list -c data

特定のツールのパラメータ説明を表示する。

owl show owl.data.query

ステップ 4：実行前の検証¶

実際のクエリを実行せずに、ツールの呼び出しを検証します。

owl validate owl.data.show_dql_namespace -f json

結果の valid が true、request_executed が false であることを確認してください。現在の CLI が validate をサポートしていない場合は、バージョン 1.2.0 以降にアップグレードしてください。

ステップ 5：ツールを実行する¶

以下のコマンドを実行して、現在のワークスペースでサポートされている DQL 名前空間を表示します（これは owl.data.query を使用する前の最初のステップです）。

owl exec owl.data.show_dql_namespace

機械可読な出力が必要な場合は、JSON 形式を指定します。

owl exec owl.data.show_dql_namespace -f json

完全な例¶

bash / zshPowerShell

export OWL_REGISTRY_ENDPOINT="your-owl-endpoint"
export OWL_TOKEN="your-token"

owl sync
owl category list
owl list -c data
owl show owl.data.query
owl validate owl.data.show_dql_namespace -f json
owl exec owl.data.show_dql_namespace -f json

$env:OWL_REGISTRY_ENDPOINT = "your-owl-endpoint"
$env:OWL_TOKEN = "your-token"

owl sync
owl category list
owl list -c data
owl show owl.data.query
owl validate owl.data.show_dql_namespace -f json
owl exec owl.data.show_dql_namespace -f json

成功基準¶

クイックスタートが完了したら、以下の結果が得られることを確認してください。

owl sync が正常に完了し、認証エラーやネットワークエラーが返されないこと
owl category list でツールカテゴリが表示されること
owl list -c data で data カテゴリ配下のツールが表示されること
owl validate owl.data.show_dql_namespace -f json が valid: true と request_executed: false を返すこと
owl exec owl.data.show_dql_namespace が現在のワークスペースでサポートされている DQL 名前空間を返すこと

認証失敗、ツールが存在しない、結果が空などの問題が発生した場合は、トラブルシューティングを参照してください。