lookerctl

用于管理和优化大规模LookML的综合CLI工具

快速链接

📚 完整文档 - 从此处开始阅读完整文档

快速入门

# 1. 设置环境
source .env

# 2. 测试连接
lookerctl test

# 3. 导出LookML
lookerctl export all --output-dir ./lookml

# 4. 执行静态分析和验证（快速！）
lookerctl validate static ./lookml

# 5. 分析使用情况
lookerctl analyze usage

主要特性

• ⚡ 验证速度提升66倍 - 对于大型Looker实例，本地验证仅需600毫秒，而通过API则需要40秒
• 🔄 完整本地开发 - 导出 → 编辑 → 验证 → 推送工作流程
• 📊 使用分析 - 了解用户实际使用的字段
• 🧪 科学测试 - A/B测试和黄金测试以增强信心，补充Looker内置的数据测试
• 🔍 依赖关系映射 - 在进行更改之前理解影响
• 🤖 AI就绪 - 所有输出均为JSON格式，便于AI消费
• 🔌 MCP服务器 - 通过模型上下文协议提供20个工具供AI代理使用

文档

入门指南

• 入门指南 - 安装和设置
• 核心概念 - 了解该工具

参考资料

• CLI参考 - 完整命令参考
• 查询测试 - 基线和A/B测试
• 本地验证 - 快速本地验证
• AI集成 - AI驱动的工作流
• MCP服务器 - 模型上下文协议集成供AI代理使用

示例

• 示例目录 - 实际工作的示例和模板

示例工作流

本地开发

# 同步到本地git分支
lookerctl session sync my-project

# 导出到本地
lookerctl export project my-project -o ./local

# 进行更改
vim ./local/views/users.view.lkml

# 验证（600毫秒！）
lookerctl validate static ./local

# 推送到Looker
lookerctl export push my-project ./local

A/B测试优化

# 创建基线（在更改前）
lookerctl query-test baseline create model.explore \
  -q query.json -o before.json

# 进行优化更改
# ... 优化SQL，添加索引 ...

# 比较更改后的情况
lookerctl query-test baseline compare model.explore \
  -b before.json

# 结果：✓ 没有数据变化的情况下，速度提高了39%！

使用分析

# 分析正在使用的项目
lookerctl analyze usage -o usage.json

# 查找未使用的探索
lookerctl analyze unused

# 构建依赖图
lookerctl deps build ./lookml -o deps.json

为AI代理的MCP服务器

# 启动MCP服务器（适用于Claude Desktop）
lookerctl mcp

# 添加到Claude Desktop配置中：
# {
#   "mcpServers": {
#     "looker": {
#       "command": "/path/tlookerctl",
#       "args": ["mcp"],
#       "env": { ... }
#     }
#   }
# }

# 然后询问Claude：
# "列出所有Looker项目"
# "查找未使用的探索"
# "分析./lookml中的依赖关系"

安装

# 1. 安装依赖项
uv pip install -r requirements.txt

# 2. 配置凭据（.env文件）
export LOOKERSDK_BASE_URL=https://your-instance.looker.com:443
export LOOKERSDK_CLIENT_ID=your_client_id
export LOOKERSDK_CLIENT_SECRET=your_client_secret

# 3. 测试连接
lookerctl test

性能

操作	API方法	本地图	加速倍数
验证项目	40秒	600毫秒	66倍更快
字段发现	2秒	100毫秒	20倍更快
依赖检查	5秒	50毫秒	100倍更快

架构

TODO: 填充架构图

关键命令

# 会话管理
lookerctl session sync
lookerctl session workspace dev

# 导出/推送
lookerctl export all -o ./lookml
lookerctl export push my-project ./lookml

# 验证
lookerctl validate static ./lookml     # 600毫秒
lookerctl validate local my-project ./lookml   # 40秒，准确

# 分析
lookerctl analyze usage
lookerctl deps build ./lookml

# 测试
lookerctl query-test baseline create model.explore -q query.json
lookerctl query-test baseline compare model.explore -b baseline.json
lookerctl query-test golden run

使用场景

开发者

• 类似Looker控制台的本地开发工作流
• 迭代过程中的快速验证
• 使用基线进行安全重构
• 更改前的影响分析

AI系统

• 为AI代理提供20个工具的MCP服务器
• 导出所有LookML进行分析
• 程序化字段发现
• 自动优化并验证
• 改进的科学测试

团队

• 用户创建内容的可见性
• 与黄金测试集成的CI/CD
• 时间上的性能跟踪
• 自动优化流水线

支持

• 📖 文档：参见 docs/
• 🐛 问题：通过团队的问题追踪器报告
• ❓ 帮助：从 入门指南 开始

状态

✅ 生产就绪

• 所有功能经过端到端测试
• 完整的A/B测试工作流已验证
• 66倍更快的本地验证
• 完整的文档
• 完整的错误处理

---

版本：0.1.0
最后更新：2025-10-11

完整文档参见：docs/README.md