CLI クイックスタート¶
このドキュメントは、OWL CLI を初めて使用するユーザーを対象に、OWL CLI の設定、ツールカタログの同期、および 1 回のツール呼び出しの実行方法を説明します。
Codex、Claude Code、Cursor、Trae、GitHub Copilot(VS Code)、Windsurf などの Agent との対話で直接使用する場合は、先に統一自動インストールフローに従って CLI と付属の Skill をインストールし、初回呼び出しの検証を完了してください。本ページではコマンドを手動で実行するフローを説明します。自動インストールで完了済みの設定と同期の手順を繰り返し実行する必要はありません。
前提条件¶
開始前に以下を確認してください:
- OWL の手動インストール または OWL の自動インストール を完了している
- ワークスペースが所属するサイトに対応する OWL CLI Endpoint を取得済みである(Endpoint 一覧を参照)
- Studio の個人 API キーページで一時認可コードを生成済み、または引き続き使用可能な API Key 設定がある
- 現在のターミナルから OWL CLI Endpoint にアクセスできる
ステップ 1:ログインとワークスペースの設定¶
OWL CLI 1.9.0 以降を使用し、所属サイトが DPoP をサポートしていることを確認してください。owl init はサイトの HTTPS Endpoint を保存します。owl login --dpop はプロンプトに従って Studio の一時認可コードを読み取り、バインドされた資格情報を本機に保存します。ワークスペースを切り替える必要がある場合は、owl workspace use <workspace_uuid> を実行します。
追加と切り替え¶
まずアカウント A で Studio にログインし、「個人 API キー」ページで一時認可コードを生成します。owl profile add customer-a を実行し、プロンプトに従って所属サイトの HTTPS Registry アドレスと一時コードを入力します。次にアカウント B で生成した新しいコードを使って B を追加します。一時コードの入力時、ターミナルでは内容が非表示になります。サイトアドレスを表示
owl profile add customer-a
owl switch customer-a
owl profile add customer-b
owl --profile customer-b sync
B を追加した後も、デフォルトのアカウントは A のままです。--profile customer-b は現在のコマンドに対してのみ B を選択します。owl switch customer-b を実行すると、以降のコマンドで B を使用できます。アカウントの追加にはオンラインで一時コードを引き換える必要がありますが、切り替えはローカル設定を確認するだけです。複数の Profile を使用する。
API Key モード¶
既存の API Key 設定では、引き続き owl login、OWL_TOKEN、または OWL_API_KEY を使用できます。環境変数方式は、旧設定モードまたは --conf を単独で使用する場合にのみ ID を上書きし、OWL_API_KEY は OWL_TOKEN より優先されます。DPoP ログインを使用する前に、API Key モードの選択に使用する ID 環境変数を解除してください。
ステップ 2:ツールカタログの同期¶
OWL CLI を初めて使用する前に、ツールカタログを同期する必要があります:
owl sync は、Guance で現在利用可能なカテゴリとツールのメタデータをローカルキャッシュに同期します。同期が完了すると、ツールの表示と実行が可能になります。
特定のカテゴリのみを同期する場合は、-c でカテゴリを指定できます:
ステップ 3:ツールの表示¶
すべてのツールカテゴリを表示します:
特定のカテゴリ内のツールを表示します:
特定のツールのパラメータ説明を表示します:
ステップ 4:実行前の検証¶
実際のクエリを発行せずに、まずツール呼び出しを検証します:
結果の valid は true、request_executed は false である必要があります。現在の CLI が validate をサポートしていない場合は、1.2.0 以降にアップグレードしてください。
ステップ 5:ツールの実行¶
次のコマンドを実行し、現在のワークスペースがサポートする DQL 名前空間を確認します(これは owl.data.query を使用する前の最初のステップです):
機械可読な出力が必要な場合は、JSON 形式を指定できます:
完全な例 (API Key)¶
成功基準¶
クイックスタートを完了すると、次の結果が得られるはずです:
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 名前空間を返す
認証失敗、ツールが存在しない、結果が空などの問題が発生した場合は、トラブルシューティングを参照してください。