Lookerctl

🚀 lookerctl

A comprehensive CLI for large - scale management and optimization of LookML

🚀 Quick Start

# 1. Setup environment
source .env

# 2. Test connection
lookerctl test

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

# 4. Perform static analysis and validation (fast!)
lookerctl validate static ./lookml

# 5. Analyze usage
lookerctl analyze usage

✨ Features

• ⚡ 66x Faster Validation: Local validation takes 600ms, compared to 40s with API for a large - scale Looker instance.
• 🔄 Complete Local Development: Follow an Export → Edit → Validate → Push workflow.
• 📊 Usage Analysis: Understand the fields that users actually use.
• 🧪 Scientific Testing: Conduct A/B testing and golden tests for confidence, complementing Looker's built - in data tests.
• 🔍 Dependency Mapping: Comprehend the impact before making changes.
• 🤖 AI - Ready: All outputs are in JSON for AI consumption.
• 🔌 MCP Server: Offers 20 tools for AI agents via the Model Context Protocol.

📦 Installation

# 1. Install dependencies
uv pip install -r requirements.txt

# 2. Configure credentials (.env file)
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. Test connection
lookerctl test

💻 Usage Examples

Local Development

# Sync with local git branch
lookerctl session sync my-project

# Export to local
lookerctl export project my-project -o ./local

# Make changes
vim ./local/views/users.view.lkml

# Validate (600ms!)
lookerctl validate static ./local

# Push to Looker
lookerctl export push my-project ./local

AB Testing Optimization

# Create baseline BEFORE changes
lookerctl query-test baseline create model.explore \
  -q query.json -o before.json

# Make optimization changes
# ... optimize SQL, add indexes ...

# Compare AFTER changes
lookerctl query-test baseline compare model.explore \
  -b before.json

# Result: ✓ 39% faster with no data changes!

Usage Analysis

# Analyze what's being used
lookerctl analyze usage -o usage.json

# Find unused explores
lookerctl analyze unused

# Build dependency graph
lookerctl deps build ./lookml -o deps.json

MCP Server for AI Agents

# Start MCP server (for Claude Desktop)
lookerctl mcp

# Add to Claude Desktop config:
# {
#   "mcpServers": {
#     "looker": {
#       "command": "/path/tlookerctl",
#       "args": ["mcp"],
#       "env": { ... }
#     }
#   }
# }

# Then ask Claude:
# "List all Looker projects"
# "Find unused explores"
# "Analyze dependencies in ./lookml"

📚 Documentation

Getting Started

• Getting Started Guide: Installation and setup.
• Core Concepts: Understanding the tool.

Reference

• CLI Reference: Complete command reference.
• Query Testing: Baselines and A/B testing.
• Local Validation: Fast local validation.
• AI Integration: AI - driven workflows.
• MCP Server: Model Context Protocol integration for AI agents.

Examples

• Examples Directory: Real working examples and templates.

🔧 Technical Details

Performance

Key Commands

# Session management
lookerctl session sync
lookerctl session workspace dev

# Export/Push
lookerctl export all -o ./lookml
lookerctl export push my-project ./lookml

# Validation
lookerctl validate static ./lookml     # 600ms
lookerctl validate local my-project ./lookml   # 40s, accurate

# Analysis
lookerctl analyze usage
lookerctl deps build ./lookml

# Testing
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

Use Cases

• For Developers: Local development workflow like Looker console, fast validation during iteration, safe refactoring with baselines, and impact analysis before changes.
• For AI Systems: MCP server with 20 tools for AI agents, export all LookML for analysis, programmatic field discovery, automated optimization with validation, and scientific testing of improvements.
• For Teams: Visibility into user - created content, CI/CD integration with golden tests, performance tracking over time, and automated optimization pipelines.

Support

• 📖 Documentation: See docs/
• 🐛 Issues: Report via your team's issue tracker
• ❓ Help: Start with Getting Started

Status

✅ Production Ready

• All features tested end - to - end
• Complete A/B testing workflow validated
• 66x faster local validation
• Comprehensive documentation
• Full error handling

Version: 0.1.0 Last Updated: 2025 - 10 - 11

For complete documentation, see: docs/README.md