kb-dashboard-cli

CLI, LSP, and future MCP server for the kb-yaml-to-lens dashboard compiler.

This package provides command-line tools and language server capabilities for building Kibana dashboards from YAML definitions. It converts human-friendly YAML dashboard definitions into Kibana NDJSON format:

Features

• YAML-based Dashboard Definition – Define dashboards, panels, filters, and queries in simple YAML
• Rich Panel Support – Lens visualizations including metric, pie, XY (line, bar, area), gauge, heatmap, datatable, tag cloud, waffle, mosaic, and treemap — plus ES|QL variants of each
• Advanced Controls – Control groups with options lists, range sliders, and time sliders with chaining
• Filter Support – Exists, phrase, range, and custom DSL with AND/OR/NOT operators
• Direct Upload – Optional direct upload to Kibana with authentication support
• Full CLI Toolkit – Commands for compile, upgrade, decompile, disassemble, compare, fetch, screenshot, and LSP server

Prerequisites

For ⭐ VS Code Extension (Recommended):

• VS Code 1.85.0+ or compatible editor (Cursor, VSCodium, etc.)
• No Python installation required - bundled binary included!

For CLI (Automation/CI):

• uv for running via uvx (recommended - no Python setup required)
• Or Python 3.12+ with pip/uv for traditional installation

Quick Start

Option 1: ⭐ VS Code Extension (Recommended for Getting Started)

Best for: Interactive dashboard development, visual editing, live preview

The VS Code extension is the fastest way to start building Kibana dashboards. It includes:

• Pre-built snippets for quick dashboard scaffolding
• Live preview as you type
• Visual drag-and-drop grid editor
• One-click upload to Kibana
• No Python installation required - LSP server binary is bundled

Installation

From Open VSX Registry (Cursor, VS Code forks):

1. Open Extensions view (Ctrl+Shift+X)
2. Search for "Kibana Dashboard Compiler"
3. Click Install

Manual VSIX Install: Download platform-specific .vsix from releases page

Verify Installation

After installation, verify the extension is working:

1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Type "YAML Dashboard" - you should see all extension commands
3. Create a test file: test-dashboard.yaml
4. Type dashboard and press Tab - a snippet should insert

If commands don't appear, restart VS Code and check the Output panel (View → Output → "Dashboard Compiler LSP").

Your First Dashboard in VS Code

1. Create a new file: my-dashboard.yaml
2. Start typing dashboard and press Tab to insert snippet
3. Save (Ctrl+S) - auto-compiles in background
4. Run command (Ctrl+Shift+P): "YAML Dashboard: Preview Dashboard"
5. Configure Kibana URL in settings, then run: "YAML Dashboard: Open in Kibana"

Learn more: VS Code Extension Documentation

Option 2: CLI (Best for Automation & CI/CD)

Best for: Scripting, CI/CD pipelines, batch processing, programmatic usage

The CLI provides multiple installation methods:

uvx kb-dashboard-cli compile --help

# Pull the pre-built image
docker pull ghcr.io/strawgate/kb-yaml-to-lens/kb-dashboard-compiler:latest

# Or build locally (from repo root)
just cli docker-build

git clone https://github.com/strawgate/kb-yaml-to-lens
cd kb-yaml-to-lens
just cli install

Compile Your First Dashboard (CLI)

1. Create a YAML dashboard file in inputs/ directory:

dashboards:
- name: My First Dashboard
  description: A simple dashboard with markdown
  panels:
    - title: Welcome
      size: { w: 24, h: 15 }        # Size on 48-column grid
      position: { x: 0, y: 0 }     # Position on the grid
      markdown:
        content: |
          # Welcome to Kibana!

          This is my first dashboard compiled from YAML.

2. Compile to NDJSON:

If using uvx: uvx kb-dashboard-cli compile --input-dir inputs --output-dir output

If using Docker:

docker run --rm -v $(pwd)/inputs:/inputs -v $(pwd)/output:/output \
  ghcr.io/strawgate/kb-yaml-to-lens/kb-dashboard-compiler:latest \
  compile --input-dir /inputs --output-dir /output

If using standalone binary: ./kb-dashboard-<platform> compile --input-dir inputs --output-dir output

3. (Optional) Upload directly to Kibana:

Add --upload --kibana-url http://localhost:5601 --kibana-username elastic --kibana-password changeme to the compile command above.

The --upload flag will automatically open your dashboard in the browser upon successful upload.

Learn more: CLI Documentation

Documentation

Getting Started

• VS Code Extension Guide - Visual dashboard development (recommended for beginners)
• CLI Reference - Command-line compilation and automation
• Complete Examples - Real-world dashboard examples you can copy

Deep Dive

• Full Documentation Site - Complete user guide and API reference
• Programmatic Usage Guide - Create dashboards entirely in Python code
• Architecture - Technical design and data flow overview
• Contributing Guide - How to contribute and add new capabilities

License

MIT

Support

For issues and feature requests, please refer to the repository's issue tracker.