CLI コマンド¶

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

設定と認証¶

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

よく使われるコマンド：

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

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 キーの権限に依存します

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

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 ランタイムが現在の 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
  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. config.yaml

キャッシュと同期¶

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 以降、新しいファイルは URL-safe な22桁のランダム 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 に接続する必要がある場合は、関数呼び出しスキーマをエクスポートできます。

owl schema

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

owl schema -c metric

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

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

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

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

ヘルプコマンド¶

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

owl --help

特定のコマンドのヘルプを表示する：

owl help exec
owl help sync
owl help data