using-looker-cli

Looker CLI（looker-cli）の使用

このスキルでは、**Looker CLI（looker-cli）**の標準的な操作、セッション管理、探索ワークフロー、API ペイロードツールについて説明します。

---

1. プロファイルの管理

プロファイルを使うと、異なる Looker インスタンス（開発、ステージング、本番環境など）の接続設定（ホスト、ポート、認証情報、トークン）を ~/.config/looker-cli/config.yaml に保存できます。

プロファイルの追加

profile add を使用して、Looker インスタンスの接続設定を追加します。

looker-cli profile add <profile_name> --host <instance_host> --port <port>

プロファイルの作成時に指定できるオプションのフラグ：

• --client-id <id>：Looker API クライアント ID を設定します。
• --client-secret <secret>：Looker API クライアントシークレットを設定します。
• --token <access_token>：事前に取得した API アクセストークンを保存します。
• --refresh-token <refresh_token>：OAuth リフレッシュトークンを保存します。

例：

looker-cli profile add staging --host staging.looker.mycompany.com --port 443

プロファイルの一覧表示

設定済みのすべてのプロファイルを一覧表示します。

looker-cli profile ls

アクティブ（デフォルト）プロファイルにはアスタリスク（*）が付いています。

  dev (dev.looker.mycompany.com:443)
* staging (staging.looker.mycompany.com:443)
  prod (prod.looker.mycompany.com:443)

デフォルトプロファイルの設定

profile use を使用して、特定のプロファイルをデフォルトのアクティブプロファイルに設定します。

looker-cli profile use <profile_name>

例：

looker-cli profile use prod

以降のコマンドは、接続フラグを明示的に指定しなくても、アクティブプロファイルに対して自動的に実行されます。

コマンドごとにプロファイルを上書きする（--profile）

デフォルトのアクティブプロファイル以外のプロファイルに対して単一のコマンドを実行するには、グローバルな --profile フラグを使用します。

looker-cli <command> --profile <profile_name>

例：

# Query current user on production without changing active default profile
looker-cli user me --profile prod

# List projects in dev environment
looker-cli project ls --profile dev

プロファイルの削除

profile rm を使用して、保存済みのプロファイル定義を削除します。

looker-cli profile rm <profile_name>

---

2. 永続セッションログイン（session login）

looker-cli は永続的な認証セッションをサポートしているため、リクエストのたびに認証しなくてもコマンドを実行できます。

基本的な永続ログイン

設定済みの API 認証情報を使って、アクティブプロファイルに定義されたホストに対して認証します。

looker-cli session login

認証に成功すると、アクセス認証情報とセッション状態が ~/.config/looker-cli/config.yaml に保存されます。

OAuth 2.0 PKCE ブラウザーログイン（--oauth）

OAuth 2.0 PKCE を使用したユーザー単位の対話型ログインでは、--oauth フラグを指定します。

looker-cli session login --oauth

ワークフロー：

1. CLI が認証 URL を起動します（ヘッドレス環境では URL を出力します）。
2. ブラウザーで認証を完了し、アクセスを許可します。
3. OAuth アクセストークンとリフレッシュトークンが config.yaml のアクティブプロファイルに自動的に保存されます。

トークンのターミナル出力（--text）

認証済みアクセストークンを設定ファイルに保存する代わりに、標準出力に表示するには（スクリプトや環境変数への受け渡しなど）、--text を指定します。

looker-cli session login --text

アクティブセッションの状態確認

現在のアクティブセッションの詳細（認証済みユーザー ID、セッションワークスペース、有効期限）を表示します。

looker-cli session get

ワークスペースコンテキストの切り替え

永続セッションのコンテキストを、個人用開発ワークスペース（dev）と本番環境（production）の間で切り替えます。

# Switch to personal development mode
looker-cli session update --workspace-id dev

# Switch to production mode
looker-cli session update --workspace-id production

セッションの終了

アクティブな永続セッションを無効化して終了します。

looker-cli session logout

---

3. メタユーティリティによるコマンドの探索

looker-cli には、コマンド階層の確認や利用可能な API エンドポイントの検索に使える meta 探索ユーティリティが含まれています。

コマンドサブツリーの表示（meta tree）

対話型 CLI コマンドツリーを表示します。

looker-cli meta tree

特定の名詞に絞り込む（--noun）

特定のリソース名（例：project、dashboard、user、query）に関連するサブコマンドだけをツリーに表示するには、--noun を指定します。

looker-cli meta tree --noun project

出力例：

project
├── branch
├── cat
├── checkout
├── create
├── deploy
│   └── key
├── directory
│   ├── create
│   ├── ls
│   └── rm
├── file
│   ├── cat
│   ├── create
│   ├── ls
│   ├── rm
│   └── update
├── import
├── ls
├── update
└── validate

JSON 出力形式（--output json）

コマンド構造を JSON オブジェクトとして出力します。

looker-cli meta tree --noun query --output json

キーワードによるコマンド検索（meta search）

キーワードを指定して、上位レベルの CLI コマンドと下位レベルの API 操作をすべて検索します。

looker-cli meta search <KEYWORD>

例：

# Search for commands related to projects
looker-cli meta search project

# Search for commands related to users or authentication
looker-cli meta search user

出力例：

Found 63 matching commands:
  looker-cli api project create_project - Create Project
  looker-cli api project deploy_to_production - Deploy To Production
  looker-cli api project validate_project - Validate Project
  looker-cli project create - Create a new project
  looker-cli project validate - Validate a project

---

4. API リクエストボディの確認（--describe-body と --template）

looker-cli は、looker-cli api <group> <endpoint> から低レベルの REST API エンドポイントを公開します。API コマンドを直接実行して Looker リソースを作成または更新する場合は、--describe-body と --template を使って、想定されるパラメーターを確認し、ペイロードファイルの構造を把握してください。

リクエストの JSON スキーマを確認する（--describe-body）

API コマンドに --describe-body を指定すると、リクエストボディの正式な JSON Schema が出力されます。すべての使用可能なパラメーター、データ型、フィールドの説明、書き込み専用フラグ、許可される値（x-looker-values）が一覧表示されます。

looker-cli api <group> <endpoint> --describe-body

例：プロジェクト作成用のスキーマを確認する

looker-cli api project create_project --describe-body

出力例：

{
  "properties": {
    "name": {
      "description": "Project display name",
      "type": "string",
      "x-looker-nullable": false
    },
    "pull_request_mode": {
      "description": "The git pull request policy for this project. Valid values are: \"off\", \"links\", \"recommended\", \"required\".",
      "type": "string",
      "x-looker-nullable": false,
      "x-looker-values": [
        "off",
        "links",
        "recommended",
        "required"
      ]
    }
  }
}

ペイロードのひな形を生成する（--template）

API コマンドに --template を指定すると、書き込み可能なフィールドにデフォルト値または空の値が入力された、簡潔な JSON のひな形が出力されます。

looker-cli api <group> <endpoint> --template

例：接続作成用のひな形を生成する

looker-cli api connection create_connection --template

出力例：

{
  "database": "",
  "db_timezone": "",
  "dialect_name": "",
  "host": "",
  "name": "",
  "port": ""
}

実践的なワークフロー：API ペイロードを使ったリソースの作成

--template をパイプまたはファイルへのリダイレクトと組み合わせて、POST/PUT ペイロードを作成し、送信します。

1. ひな形ファイルを生成して編集する：

   looker-cli api project create_project --template > new_project.json
   

2. new_project.json の必須フィールドに値を入力する：

   {
     "name": "my_new_project",
     "pull_request_mode": "recommended"
   }
   

3. ペイロードファイルを使って API リクエストを実行する：

   looker-cli api project create_project --body new_project.json
   

---

5. クイックリファレンス

タスク	コマンド
プロファイルを追加	looker-cli profile add dev --host dev.looker.com --port 443
プロファイルを一覧表示	looker-cli profile ls
デフォルトのプロファイルを設定	looker-cli profile use dev
プロファイルを上書き	looker-cli project ls --profile prod
ログイン状態を保持	looker-cli session login
OAuth PKCE でログイン	looker-cli session login --oauth
セッションを確認	looker-cli session get
コマンドツリー	looker-cli meta tree
リソース別のツリー	looker-cli meta tree --noun project
コマンドを検索	looker-cli meta search <keyword>
リクエストスキーマを表示	looker-cli api <group> <endpoint> --describe-body
JSON のひな形を生成	looker-cli api <group> <endpoint> --template