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）

若要将已验证的访问令牌显示到 stdout（例如，用于管道传入脚本或环境变量），而不是持久保存到配置文件，请传入 --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 Schema（--describe-body）

在 API 命令中传入 --describe-body，即可输出请求正文的正式 JSON Schema。它会列出所有允许的参数、数据类型、字段说明、只写标志和允许的值（x-looker-values）：

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

示例：检查创建项目的 Schema

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>
查看请求 Schema	looker-cli api <group> <endpoint> --describe-body
生成 JSON 模板	looker-cli api <group> <endpoint> --template