CLI コマンド¶
本ドキュメントでは、OWL CLI のよく使用するコマンドについて説明します。設定と認証、ツールカタログの同期、ツールの表示、実行前検証、ツールの実行、キャッシュ管理、データファイル管理、およびエージェント向けのケイパビリティネゴシエーションとスキーマ出力が含まれます。
コマンドライン補完¶
Bash¶
Bash 3.2 および Bash 4/5 をサポートし、Linux、macOS、Windows Git Bash、WSL で利用できます。WSL では Linux 版 OWL を使用します。Git Bash では Windows 版 owl.exe を使用し、owl または owl.exe を入力できます。
Bash バージョンに互換性のある bash-completion をインストールして読み込みます。Bash 3.2 では互換性のある 1.x バージョン、Bash 4/5 では対応する 2.x バージョンを使用します。現在のターミナルで OWL 補完を有効にします:
永続的に有効にする場合は、同じ行を ~/.bashrc 内の bash-completion を読み込むコードの後に追加します。ログインターミナルが ~/.bash_profile のみを読み込む場合は、それが ~/.bashrc を読み込むことを確認してください。設定は一度だけでよく、重複して追記しないでください。
ここでは eval を使用して OWL が生成したスクリプトを読み込みます。一部の macOS Bash 3.2 環境で source <(...) がサイレントに読み込まれない問題を避けるためです。以下のようにスクリプトをファイルに保存してから source することもできます。
インストールスクリプトは引き続き生成された補完スクリプトを ~/.local/share/bash-completion/completions/owl に書き込みます。現在の bash-completion がこのディレクトリを自動で読み込む場合、上記の起動コマンドを設定する必要はありません。OWL 更新後、既存の静的補完ファイルは再生成が必要です:
mkdir -p ~/.local/share/bash-completion/completions
owl completion bash > ~/.local/share/bash-completion/completions/owl
source ~/.local/share/bash-completion/completions/owl
PowerShell¶
Windows PowerShell 5.1 と PowerShell 7 は専用の補完スクリプトを使用し、同じローカルツール候補ロジックを共有します。現在のターミナルで有効にします:
永続的に有効にする場合は、この行を $PROFILE に追加できます。既存の Windows インストールスクリプトはすでに Completions\owl.ps1 を生成し、インストール時に使用する $PROFILE で読み込みます。設定済みのユーザーは重複して追加する必要はありません。PowerShell のバージョンやホストによって異なる profile を使用する場合があるため、実際に使用するターミナルで有効にしてください。
CMD は今回の補完サポート対象外です。
補完内容とキャッシュ¶
まず通常のコマンドでツール定義を同期します:
以下の例の <Tab> は Tab キーを押すことを表します:
owl exec owl.met<Tab> → owl.metric.list
owl exec owl.metric.list --mo<Tab> → --mode
owl exec owl.metric.list mo<Tab> → mode=
owl exec owl.metric.list --mode s<Tab> → source
owl exec owl.metric.list --mode=s<Tab> → --mode=source
owl exec owl.metric.list mode=s<Tab> → mode=source
- ツール名の直後に Tab を押すと、デフォルトで
--参数名が一覧表示されます。通常の名前プレフィックスを入力した場合は、参数名=が一覧表示されます。 exec、validate、および対応するtool/toolsエントリをサポートします。showはツール名補完、--categoryはカテゴリ補完、--formatは形式補完をサポートします。- パラメータ値はスキーマ内の文字列、数値、またはブール列挙に由来します。ブールパラメータでは
true/falseがヒント表示されます。自由テキスト、配列、オブジェクト、および-p/--params後の JSON 内容は補完されません。 - 入力済みのツールパラメータは再度ヒント表示されません。ワークスペース、メトリクスソース、フィールドなどのリアルタイム業務データは照会しません。
- Tab は現在の設定で選択されているローカルキャッシュのみを読み取り、ネットワークに接続せず、ツールを実行せず、標準入力を読み取らず、設定を書き込まず、古いキャッシュを移行しません。
OWL_DIRとコマンド前の--confで設定とキャッシュを選択できます。 - Profile の別名は
owl switch <Tab>、owl profile rename/remove <Tab>、owl --profile <Tab>、およびowl exec --profile=<Tab>などツール名より前のオプションをサポートします。新しい別名およびリネーム後の新しい名前はユーザーが入力し、ファイルは候補表示されません。profile add --fromは設定ファイル補完を維持します。 - ツール候補は現在の Profile の設定とキャッシュの分離に従います。
--profile、OWL_PROFILE、および切り替え済みのデフォルト Profile がすべて有効になります。owl exec --profile <名称> <工具名>もサポートします。ツール名以降の--profileは引き続きツールパラメータに属します。 - キャッシュが空、または設定を読み取れない場合でも、基本コマンドと固定オプションの補完は可能です。ツール定義の補完は
owl syncの成功後に利用できます。同期完了後に補完スクリプトを再読み込みする必要はありません。
Bash で _get_comp_words_by_ref: command not found が表示された場合、bash-completion がまだ読み込まれていません。ツール名またはパラメータ候補のみが欠けている場合は、まず現在の設定で owl list と owl show <工具名> がツール定義を読み取れることを確認し、次に owl sync を実行してキャッシュを更新してください。
ソースからビルドした直後の場合は、まず command -v owl で現在のターミナルが新しいバージョンを呼び出していることを確認してください。make build は build/owl のみを生成し、既存のインストールを上書きしません。補完スクリプトを読み込んでも実行ファイルは置き換わりません。リポジトリルートから export PATH="$PWD/build:$PATH" と hash -r を実行してから、有効化コマンドを実行してください。complete -p owl で Bash に補完が登録されているか確認できます。
DPoP ログイン¶
OWL CLI 1.9.0 以降を使用し、所属サイトが DPoP をサポートしていることを確認してください。owl init はサイトの HTTPS Endpoint を保存します。owl login --dpop はプロンプトに従って Studio の一時認可コードを読み取り、本機にバインドされた認証情報を保存します。ワークスペースを切り替える必要がある場合は、owl workspace use <workspace_uuid> を実行します。
既存の API Key 設定では引き続き owl login、OWL_TOKEN、または OWL_API_KEY を使用できます。環境変数方式は、旧設定モードまたは --conf を単独で使用する場合にのみアイデンティティを上書きし、OWL_API_KEY は OWL_TOKEN より優先されます。DPoP ログインを使用する前に、API Key モードの選択に使用するアイデンティティ環境変数を解除してください。
--from ではファイル内のサイトアドレス、タイムアウトなどのアイデンティティ以外の設定を引き継げますが、新しいアカウントの一時認可コードでログインする必要があります。ソースファイル内の API Key、token_file、DPoP バインディングは新しい Profile にコピーされず、ソースファイルは変更されません。複数の Profile を使用する。
設定と認証¶
OWL CLI では以下の一般的な設定を使用します:
| 設定項目 | 説明 |
|---|---|
OWL_REGISTRY_ENDPOINT |
ワークスペースが所属するサイトに対応する OWL CLI Endpoint |
OWL_REGISTRY_INSECURE_SKIP_VERIFY |
true に設定すると Registry の HTTPS 証明書検証をスキップします。ローカル開発または自己署名証明書環境でのみ使用してください |
OWL_REGISTRY_REQUEST_TIMEOUT |
Registry HTTP リクエストの合計タイムアウト。単位はミリ秒、デフォルトは 150000 |
OWL_TOKEN |
旧版認証環境変数。対応する DF-API-KEY;旧設定モードまたは --conf を単独で使用する場合にのみアイデンティティを上書き |
OWL_API_KEY |
認証 API Key 環境変数。ユースケースは OWL_TOKEN と同じで、同時に設定した場合は OWL_TOKEN より優先されます |
OWL_TEMP_CODE |
Studio のワンタイム一時認可コード。インストールスクリプトと owl login --dpop で使用 |
OWL_DIR |
デフォルトの設定/キャッシュ/データルートディレクトリを上書き。デフォルトは $HOME/.owl、~ を展開可能 |
OWL_PROFILE |
今回のプロセス用に保存済み Profile を選択。優先度は --profile より低く、永続化された選択より高い |
よく使用するコマンド:
複数の独立した設定を保存し、別名で選択できます:
owl profile add customer-a
owl switch customer-a
owl profile add customer-b --from ./customer-b.yaml
owl profile list
owl --profile customer-b exec owl.data.show_dql_namespace
owl profile current -f json
B を追加した後も、デフォルトアカウントは A のままです。--profile customer-b は現在のコマンドにのみ B を選択します。owl switch customer-b を実行すると、以降のコマンドで B を使用できます。アカウントの追加にはオンラインで一時コードを交換する必要があり、切り替えはローカル設定のみを確認します。
Profile を選択すると、Endpoint と認証情報はその Profile から取得され、アイデンティティ環境変数では上書きされません。アイデンティティ以外の環境設定は引き続き有効です。OWL_PROFILE が設定されている場合は、その変数を解除してから owl switch を実行する必要があります。リクエスト失敗時に自動で他の Profile に切り替わることはありません。複数の Profile を使用する。
CLI の --conf <path> は非推奨となり、ヘルプから非表示になっています。互換期間中は引き続き指定ファイルを読み書きし、環境変数による上書きを維持します。--profile と同時に指定するとエラーになります。profile add <alias> --from <path> でインポートした後に --profile を使用することを推奨します。Registry の --config は引き続き使用できます。
ローカル開発環境の Registry が自己署名証明書を使用している場合は、明示的に証明書検証を無効にできます:
owl config set registry.insecure_skip_verify true
# または現在のプロセスのみに適用
export OWL_REGISTRY_INSECURE_SKIP_VERIFY=true
この設定のデフォルトは false です。有効にすると OWL は Registry のアイデンティティを検証できず、中間者攻撃を受ける可能性があるため、本番環境では使用しないでください。
| コマンド | 説明 |
|---|---|
owl init |
OWL CLI Endpoint を書き込む |
owl login --dpop |
Studio の一時コードでログインし、本機にバインドされた認証情報を保存 |
owl logout |
現在の DPoP 認証情報を失効 |
owl login |
API Key モード |
owl config show |
現在の設定を表示 |
owl config set <配置项> <值> |
指定した設定項目を変更 |
owl profile add <alias> [--from <file>] |
Studio の一時コードを使用して DPoP アカウントを追加。--from はサイトおよびアイデンティティ以外の設定のみを提供 |
owl profile list |
ローカル Profile、実際の選択、永続化されたデフォルトを一覧表示 |
owl profile current |
実際に有効な Profile、アイデンティティソース、および cache/data パスを表示 |
owl switch <alias> |
以降のコマンドで使用するデフォルト Profile を保存 |
owl profile rename <old> <new> |
別名を変更し、設定とクエリファイルのパスを保持 |
owl profile remove <alias> [--purge] |
ローカル Profile を削除。デフォルトでは cache/data を保持。認証情報を失効するには先にその Profile の logout を実行 |
owl workspace list |
API Key モード: 現在のアカウントで利用可能なワークスペースの一覧を取得し、各ワークスペースの名前と workspace_uuid を出力 |
owl workspace use <workspace_uuid> |
DPoP モードで対象ワークスペース UUID を検証して選択を保存。API Key モードでは対象スペースの Key を取得して保存 |
owl workspace current |
現在のワークスペースコンテキストを表示 |
owl workspace key get <workspace_uuid\|workspace_name> |
API Key モード: 指定したワークスペースのアクセスキーを取得(デフォルトではマスク表示、--show-secret を追加すると元のキーを出力) |
owl workspace profile list |
選択した設定の workspaces エントリを一覧表示 |
owl workspace profile current |
選択した設定内で現在一致するワークスペースエントリを表示 |
owl workspace profile use <profile_name> |
API Key モード: 指定したワークスペースエントリの Endpoint/Key を選択した設定に書き込み、トップレベル Profile の選択は変更しない |
owl workspace same-org list |
同一組織内のワークスペースを一覧表示(詳細は後述) |
workspaceコマンドは別名workspacesとしても記述できます。
アクセストークンを設定する場合、api-key と token という 2 つのキー名は等価であり、どちらに書き込んでも同じアクセストークンが更新されます。ワークスペースレベルのトークンも同じ等価ルールに従います。
owl workspace same-org list¶
現在のアカウントと同一組織(same-org)のワークスペースを一覧表示します。サポートされるフラグ:
| フラグ | 説明 |
|---|---|
--page-size <n> |
1 ページあたりの件数。値は 1〜100、デフォルトは 20。範囲外の場合はエラー |
--before-id <id> |
ページングカーソル。id がこの値より小さいワークスペースのみを返します。カーソル値はサーバーから返され、配列のインデックスから推測できません |
--uuid <uuid> |
workspace_uuid でフィルタ。複数回指定可能 |
--all |
サーバーから返されるカーソルに従って自動的にページをめくり、すべてのページを返す |
ページングルール:
- デフォルトでは 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
Profile を選択していない旧設定モード、または非推奨の --conf を使用する場合にのみ、OWL_REGISTRY_ENDPOINT、OWL_API_KEY、OWL_TOKEN は設定ファイルより優先されます。OWL_API_KEY は OWL_TOKEN より優先されます。Profile を選択した後は、Endpoint/Key のセット全体がその Profile から取得されます。
カテゴリとツールカタログ¶
カテゴリとツールを表示する前に、まず一度同期を実行することを推奨します:
カテゴリとツールの表示コマンド:
| コマンド | 説明 |
|---|---|
owl category list |
すべてのカテゴリを表示 |
owl category show <分类ID> |
カテゴリの詳細とカテゴリ内のツールを表示 |
owl list |
すべてのツールを表示 |
owl list -c <分类ID> |
特定のカテゴリ内のツールを表示 |
owl show <工具名> |
ツールの詳細とパラメータ定義を表示 |
owl validate <工具名> [参数] |
ツールパラメータとツール固有の構文を検証しますが、ツールは実行しません |
owl capabilities |
CLI がサポートする機械可読なケイパビリティを出力 |
ツール実行¶
owl exec を使用してツールを実行します。
ツール名は owl list に表示される名前と一致している必要があります。実行前に owl show <工具名> でパラメータ定義を確認できます。
パラメータの渡し方¶
owl exec は以下の 4 つのパラメータ渡し方をサポートします。
--key value を使用する¶
等号でパラメータ名と値を連結する形式もサポートします。たとえば owl exec owl.metric.list --mode=source --start_time=1792548000000 --end_time=1792551600000 です。
key=value を使用する¶
-p で JSON を渡す¶
標準入力から JSON を読み取る¶
echo '{"mode":"source","start_time":1792548000000,"end_time":1792551600000}' | owl exec owl.metric.list --stdin
実行ルール¶
ツールを実行する際は以下に注意してください:
- ツール名は
owl listに表示される名前と一致している必要があります - 必須パラメータはすべて指定する必要があります
- パラメータ名はツール定義と一致している必要があります
- パラメータ型はツール定義と一致している必要があります
- 返却結果を表示できるかどうかは、
OWL_TOKENに対応する API Key の権限によって決まります - DQL クエリで返されるフィールドの意味については、返却フィールドの説明を参照してください。
例: メトリクスソースをクエリする¶
owl show owl.metric.list
owl exec owl.metric.list --mode source --start_time 1792548000000 --end_time 1792551600000
例: イベント一覧をクエリする¶
owl show owl.event.list
owl exec owl.event.list --start_time 1712505600000 --end_time 1712592000000 --limit 20
実行前検証とケイパビリティネゴシエーション¶
1.2.0 以降では、本実行前に owl validate を使用してツール呼び出しを 1 回検証できます。このコマンドは owl exec と同じ 4 つのパラメータ形式を受け付けますが、ツールの存在、パラメータスキーマ、ツール固有の構文のみを検証し、対象ツールは実行しません:
owl validate owl.metric.list --mode source --start_time 1792548000000 --end_time 1792551600000
owl validate owl.data.query -p '{"dql_namespace":"L","query_text":"L::re(`.*`):(count(*))","query_mode":"dql","start_time":1792548000000,"end_time":1792551600000}' -f json
JSON 結果には以下が含まれます:
valid: 呼び出しが検証に合格したかどうかtool: 検証したツール名request_executed: 固定でfalse。対象ツールが実行されていないことを確認するために使用issues: 構造化された問題リスト。不明なツール、パラメータ不足、型エラー、不明なパラメータ、DQL 構文問題を含む場合があります。
検証に合格しない場合(valid: false)、コマンドプロセスは引き続きステータスコード 0 で終了します。エージェントは 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 も本リクエスト前に同じパラメータスキーマ検証を実行します。エージェントランタイムが現在の CLI で事前検証をサポートしているか判断する必要がある場合は、以下を実行できます:
現在のケイパビリティ応答バージョンは owl.capabilities/v1、事前検証ケイパビリティ識別子は tool.validate/v1 です。owl tool validate、owl tools validate、owl tool capabilities、owl tools capabilities は対応する名前空間別名です。
v1.6.0 時間検証と実行結果¶
v1.6.0 では 13 桁の整数ミリ秒タイムスタンプを統一的に検証し、終了時間が開始時間より大きいことを要求します。ペアで指定する必要があるパラメータは片方だけを渡すことはできません。必須要件と最大スパンは各ツールのスキーマに従います。owl.data.query の時間範囲は最長 7 日間です。
owl.data.query の DQL ではインライン時間ウィンドウを省略でき、start_time / end_time でクエリウィンドウを提供します。インラインの絶対ウィンドウは外部ウィンドウと一致している必要があり、相対ウィンドウは拒否されます。PromQL の範囲セレクタはルックバック期間を表し、クエリウィンドウとしては扱われず、DQL 検証にも入りません。Registry には利用可能な dqlcheck が必要です。検証が利用できない場合、DQL クエリは実行されません。リクエストウィンドウは、バックエンドで実際に実行された時間範囲や結果がカバーする時間範囲と同一ではありません。
owl validate は引き続き valid で事前検証に合格したかどうかを示し、valid: false 自体はその終了コードの約束を変更しません。owl exec -f json のパラメータ事前検証が失敗した場合は JSON を出力し、非ゼロのステータスコードで終了します。issues に従ってパラメータを修正してから再実行してください。
owl sync はいずれかのカテゴリのダウンロードに失敗した場合に失敗を返し、失敗したカテゴリの既存キャッシュとローカルバージョンを保持します。初回の自動同期に失敗すると、以降の実行がブロックされます。キャッシュの有効期限切れ後の自動同期に失敗した場合は、既存の動作どおり警告し、既存キャッシュを使用します。
設定ファイルと優先度¶
デフォルトの設定ファイルパス:
| OS | 設定ファイルパス |
|---|---|
| Windows | %USERPROFILE%\.owl\config.yaml |
| Linux / macOS | $HOME/.owl/config.yaml |
設定ファイル例:
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
Profile 選択機能を使用しない場合、または非推奨の --conf を単独で使用する場合、設定の優先度は高い順に次のとおりです:
- 環境変数
--confで指定した設定ファイル(このパラメータを設定した場合)${OWL_DIR}/config.yaml(--confを設定していない場合)
Profile の選択優先度は --profile > OWL_PROFILE > 永続化された選択です。Profile が有効になった後は、Endpoint/認証情報の環境変数による上書きは無視されます。旧ルート設定はそのまま default として使用されます。
registry.request_timeout は単一の Registry HTTP リクエストの合計タイムアウトを制御し、単位はミリ秒です。デフォルト値 150000 はデータクエリツールの 130 秒のサーバー側期限より高く、レスポンスのエンコードとネットワーク転送のための時間を確保します。上流のクエリ所要時間を明確に把握している場合にのみ調整してください。
キャッシュと同期¶
owl sync は Guance のカテゴリとツールメタデータをローカルキャッシュディレクトリに同期します。
以下のシナリオでは owl sync を再実行する必要があります:
- 初回インストール完了後
- プラットフォームが新しいツールを公開した場合
- プラットフォームが既存ツールのパラメータまたは説明を更新した場合
- ローカルキャッシュの内容を更新する必要がある場合
よく使用する同期とキャッシュのコマンド:
| コマンド | 説明 |
|---|---|
owl sync |
すべてのカテゴリとツールを同期 |
owl sync -c <分类ID> |
指定したカテゴリのみを同期 |
owl cache status |
キャッシュ状態を表示 |
owl cache clear |
すべてのキャッシュをクリア |
owl cache clear -c <分类ID> |
指定したカテゴリのキャッシュをクリア |
バージョン更新の通知¶
インストーラで更新チャネルを設定した場合、owl exec は最大 24 時間に 1 回、新しいバージョンを確認します。新しいバージョンが見つかると、JSON 結果に notice フィールドが追加され、既存の success、output、file などのフィールドは変更されません。確認に失敗してもツールの実行はブロックされません。
以下のコマンドで現在の更新チャネルに従ってアップグレードできます:
自動確認を無効にする必要がある場合は、設定ファイルで update.check: false を設定できます。更新チャネルが設定されていないインストールでは確認は実行されず、通知も出力されません。
データ結果ファイル¶
ツール定義の出力タイプが data の場合、OWL CLI は結果ファイルを自動的にローカルの data/ ディレクトリに保存し、ファイルインデックスと構造情報を記録します。1.2.1 以降、新規ファイルは 22 桁の URL-safe ランダム ID を使用し、エージェントが参照しやすく、長いファイル名のリスクを低減します。安定した 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 に渡してください。
よく使用するデータファイルコマンド:
| コマンド | 説明 |
|---|---|
owl data list |
データファイル一覧を表示 |
owl data show <file-id> |
指定したデータファイルの詳細を表示 |
owl data rm <file-id> |
指定したデータファイルを削除 |
owl data clean --days <天数> |
指定した日数より前の履歴ファイルをクリーンアップ |
owl data stats |
データファイルの統計情報を表示 |
エージェント向けスキーマ出力¶
OWL CLI をカスタムエージェントに接続する必要がある場合は、関数呼び出しスキーマをエクスポートできます:
指定したカテゴリのみをエクスポート:
owl schema の出力には以下が含まれます:
owl_exec: 任意の OWL ツールを統一的に実行owl_list_categories: カテゴリを一覧表示owl_list_tools: ツールを一覧表示- 現在同期済みのツール定義
エージェントに接続する前に、一度 owl sync を実行し、ローカルスキーマがプラットフォームの現在のツールカタログと一致していることを確認することを推奨します。
対象クライアントが MCP をサポートしている場合は、MCP Server クイックスタートのリモート MCP Server 接続方式を優先して使用してください。
ヘルプコマンド¶
OWL CLI のヘルプを表示:
指定したコマンドのヘルプを表示: