CLI コマンド¶

本ドキュメントでは、OWL CLI のよく使うコマンドについて説明します。設定と認証、ツールカタログの同期、ツールの表示、実行前の検証、ツールの実行、キャッシュ管理、データファイル管理、および Agent 向けの能力交渉と Schema 出力をカバーします。

設定と認証¶

OWL CLI では以下のよく使う設定を使用します。

よく使うコマンド：

owl init
owl login
owl config show
owl config set registry.endpoint "your-owl-endpoint"

グローバルパラメータ --conf <path> を使用すると、単一コマンドに対して別の既存の設定ファイルを選択できます。異なる認証情報やエンドポイント間での切り替えに適しています。

owl --conf ~/.owl/prod.yaml config show
owl --conf ~/.owl/prod.yaml sync
owl --conf ~/.owl/testing.yaml exec owl.metric.list --mode source

init、login、config set、workspace use などの書き込み操作は、--conf で指定されたファイルに書き戻されます。このパラメータを指定しない場合、OWL は ${OWL_DIR}/config.yaml を引き続き使用します。デフォルトのパスは $HOME/.owl/config.yaml です。

ローカル開発環境の Registry が自己署名証明書を使用している場合は、証明書検証を明示的に無効にできます。

owl config set registry.insecure_skip_verify true
# または現在のプロセスにのみ有効
export OWL_REGISTRY_INSECURE_SKIP_VERIFY=true

この設定のデフォルトは false です。有効にすると OWL は Registry の身元を検証できなくなり、中間者攻撃を受ける可能性があるため、本番環境では使用しないでください。

workspace コマンドは、別名 workspaces でも記述できます。

アクセストークンを設定する際、api-key と token のキー名は同等です。どちらかに書き込むと、同じアクセストークンが更新されます。ワークスペースレベルのトークンも同様の等価ルールに従います。

owl workspace same-org list¶

現在のアカウントと同じ組織（same-org）のワークスペースを一覧表示します。対応するフラグ：

ページネーションルール：

• デフォルトでは 1 ページのみ返します。さらに結果がある場合、テキスト出力は More results available. Fetch the next page with --before-id <id> と表示します。ここで <id> はサーバーから返された次のページのカーソルです。
• --all を指定すると、CLI はサーバーから返されるカーソルに従って自動的に次のページを取得し、結果がなくなるまで繰り返します。カーソルがそれ以上進めない場合は停止し、異常なサーバーによる無限ループを回避します。

例：

owl workspace same-org list
owl workspace same-org list --page-size 50
owl workspace same-org list --before-id 12345
owl workspace same-org list --uuid wksp_xxx --uuid wksp_yyy
owl workspace same-org list --all

環境変数はローカル設定ファイルよりも優先されます。現在のターミナルで OWL_REGISTRY_ENDPOINT、OWL_API_KEY、または OWL_TOKEN がすでに設定されている場合、OWL CLI は環境変数の値を優先して使用します。OWL_API_KEY と OWL_TOKEN が両方存在する場合は、OWL_API_KEY が優先されます。

カテゴリとツールカタログ¶

カテゴリとツールを表示する前に、最初に一度同期を実行することをお勧めします。

owl sync

カテゴリとツールを表示するコマンド：

owl category list
owl category show metric
owl list
owl list -c metric
owl show owl.metric.list

ツールの実行¶

owl exec を使用してツールを実行します。

owl exec <ツール名> [パラメータ]

ツール名は owl list で表示される名前と一致している必要があります。実行前に owl show <ツール名> でパラメータ定義を確認できます。

パラメータの渡し方¶

owl exec は以下の 4 つのパラメータ渡し方法をサポートしています。

--key value を使用¶

owl exec owl.metric.list --mode source

key=value を使用¶

owl exec owl.metric.list mode=source

-p で JSON を渡す¶

owl exec owl.metric.list -p '{"mode":"source"}'

標準入力から JSON を読み込む¶

echo '{"mode":"source"}' | owl exec owl.metric.list --stdin

実行ルール¶

ツールを実行する際の注意点：

• ツール名は owl list で表示される名前と一致している必要があります
• 必須パラメータはすべて指定する必要があります
• パラメータ名はツール定義と一致している必要があります
• パラメータの型はツール定義と一致している必要があります
• 結果の表示可否は、OWL_TOKEN に対応する API Key の権限に依存します

例：メトリクスソースのクエリ¶

owl show owl.metric.list
owl exec owl.metric.list --mode source

例：イベント一覧のクエリ¶

owl show owl.event.list
owl exec owl.event.list --start_time 1712505600000 --end_time 1712592000000 --limit 20

実行前の検証と能力交渉¶

1.2.0 以降、正式な実行前に owl validate を使用してツール呼び出しを検証できます。このコマンドは owl exec と同じ 4 つのパラメータ形式を受け付けますが、ツールの存在、パラメータスキーマ、およびツール固有の構文のみを検証し、対象のツールは実行しません。

owl validate owl.metric.list --mode source
owl validate owl.data.query -p '{"query_text":"L::re(`.*`):(count(*)) [5m]","query_mode":"dql"}' -f json

JSON 結果に含まれるもの：

• valid：呼び出しが検証に合格したかどうか
• tool：検証されたツール名
• request_executed：常に false。対象のツールが実行されなかったことを確認するため
• issues：構造化された問題リスト。未知のツール、パラメータ不足、型エラー、未知のパラメータ、または DQL 構文の問題を含む可能性があります

検証に合格しなかった場合（valid: false）でも、コマンドプロセスは終了コード 0 で終了します。Agent は JSON をリクエストして結果を解析する必要があり、valid が true の場合のみ owl exec を実行できます。0 以外の終了コードは検証が完了しなかったことを示し、実行を許可するものと見なせません。

owl.data.query の DQL モードは Registry の DQL 検証機能を呼び出します。PromQL モードは DQL 検証器に入りません。1.2.1 以降、owl.data.simple_query と owl.data.simple_query_file も、簡略化されたパラメータから生成された DQL を検証します。失敗した場合は generated_dql / dql.builderError が返されるため、select_clause、where_clause、または group_by_clause を修正して再試行してください。

owl exec は、正式なリクエストの前にも同じパラメータスキーマ検証を実行します。Agent runtime が現在の CLI が事前チェックをサポートしているかどうかを判断する必要がある場合は、以下を実行します。

owl capabilities -f json

現在の能力応答バージョンは owl.capabilities/v1、事前チェック能力識別子は tool.validate/v1 です。owl tool validate、owl tools validate、owl tool capabilities、owl tools capabilities は対応する名前空間の別名です。

設定ファイルと優先順位¶

デフォルトの設定ファイルのパス：

設定ファイルの例：

registry:
  endpoint: your-owl-endpoint
  insecure_skip_verify: false
  request_timeout: 150000
  sync_interval: 3600

auth:
  token: ""

cache:
  directory: ~/.owl/cache
  ttl: 86400

data:
  directory: ~/.owl/data
  max_age_days: 1

sync:
  parallel: true
  concurrency: 5
  incremental: true

execution:
  default_timeout: 30000
  max_output_size: 10485760

logging:
  level: info
  file: ~/.owl/logs/owl.log

設定の優先順位は高い順に次のとおりです。

1. 環境変数
2. --conf で指定された設定ファイル（設定時）
3. ${OWL_DIR}/config.yaml（--conf 未設定時）

registry.request_timeout は、単一の Registry HTTP リクエストの合計タイムアウトをミリ秒単位で制御します。デフォルト値 150000 は、データクエリツールの 130 秒のサーバー期限よりも高く、応答のエンコードとネットワーク転送の時間を確保します。アップストリームクエリの所要時間を明確に理解している場合にのみ調整してください。

キャッシュと同期¶

owl sync は、Guance のカテゴリとツールのメタデータをローカルキャッシュディレクトリに同期します。

以下のシナリオでは、owl sync を再実行する必要があります。

• 初回インストール完了後
• プラットフォームが新しいツールを公開した場合
• プラットフォームが既存のツールのパラメータや説明を更新した場合
• ローカルキャッシュの内容をリフレッシュする必要がある場合

よく使う同期とキャッシュのコマンド：

バージョン更新通知¶

インストーラーを使用して更新チャンネルを設定した場合、owl exec は最大 24 時間ごとに新しいバージョンを確認します。新しいバージョンが見つかった場合、JSON 結果に notice フィールドが追加されます。既存の success、output、file などのフィールドは変更されません。チェックに失敗してもツールの実行は妨げられません。

以下のコマンドを実行して、現在の更新チャンネルに従ってアップグレードできます。

owl update

自動チェックを無効にするには、設定ファイルで update.check: false を設定します。更新チャンネルが設定されていないインストールでは、チェックは実行されず、通知も出力されません。

データ結果ファイル¶

ツール定義の出力タイプが data の場合、OWL CLI は自動的に結果ファイルをローカルの data/ ディレクトリに保存し、ファイルのインデックスと構造情報を記録します。1.2.1 以降、新しいファイルは 22 文字の URL-safe ランダム ID を使用するため、Agent が参照しやすくなり、長いファイル名のリスクが低減されます。安定した queryKey と既存のインデックス形式は変更されません。

owl exec の JSON 結果の file には、path、absolutePath、format、size のみが含まれ、データファイルの id は含まれません。パスから ID を推測したり推測したりしないでください。owl data list -f json を実行して信頼できる ID を取得し、対応するエントリを見つけてその files[].id を保存し、その値をそのまま owl data show または owl data rm に渡してください。

よく使うデータファイルのコマンド：

Agent 向けの Schema 出力¶

OWL CLI をカスタム Agent に接続する必要がある場合は、関数呼び出し Schema をエクスポートできます。

owl schema

特定のカテゴリのみをエクスポートする場合：

owl schema -c metric

owl schema の出力には以下が含まれます。

• owl_exec：任意の OWL ツールを統一的に実行します
• owl_list_categories：カテゴリを一覧表示します
• owl_list_tools：ツールを一覧表示します
• 現在同期されているツール定義

Agent に接続する前に、最初に owl sync を実行して、ローカル Schema がプラットフォームの現在のツールカタログと一致していることを確認することをお勧めします。

ターゲットクライアントが MCP をサポートしている場合は、MCP Server クイックスタート のリモート MCP Server 接続方法を優先して使用してください。

ヘルプコマンド¶

OWL CLI のヘルプを表示する：

owl --help

指定されたコマンドのヘルプを表示する：

owl help exec
owl help sync
owl help data