Dashboard Compiler CLI¶

The kb-dashboard-cli CLI tool allows you to compile YAML dashboard configurations to Kibana's NDJSON format and optionally upload them directly to Kibana.

Prerequisites¶

uv (recommended) - Enables running the CLI via uvx with zero setup
Or Python 3.12+ with pip for traditional installation

Note: When using uvx, Python and all dependencies are handled automatically. The VS Code Extension does not require Python either - it includes a bundled binary. See VS Code Extension Documentation for zero-configuration setup.

When to Use the CLI¶

Use the CLI when:

✅ Building CI/CD pipelines for dashboard deployment
✅ Batch processing multiple dashboards
✅ Scripting dashboard generation (e.g., templates, dynamic data)
✅ Integrating with other automation tools
✅ Running in headless/server environments without GUI
✅ Using Docker containers or serverless functions

Use the VS Code Extension when:

✅ Developing dashboards interactively
✅ Learning the YAML schema
✅ Making frequent visual adjustments
✅ Needing live preview and validation

See: VS Code Extension Documentation for interactive development workflow.

Installation¶

Using uvx (Recommended)¶

Run the CLI directly without cloning or installing anything:

uvx kb-dashboard-cli compile --help

This downloads and runs the published package automatically. No Python environment setup required!

Development Installation¶

For contributors or development workflows, clone the repository:

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

See DEVELOPING.md for full development setup.

Basic Usage¶

Compile Dashboards¶

Compile YAML dashboards to NDJSON format:

uvx kb-dashboard-cli compile

This will:

Find all YAML files in inputs/ (by default)
Compile them to Kibana JSON format
Output NDJSON files to output/ directory
Create individual NDJSON files per scenario
Create a combined compiled_dashboards.ndjson file

Compile a Single File¶

Compile a specific YAML file without scanning a directory:

uvx kb-dashboard-cli compile --input-file ./dashboards/example.yaml

When --input-file is provided, --input-dir is ignored.

Export Individual JSON Files¶

For workflows that require one JSON file per dashboard, choose the format based on your target workflow:

# Generic per-dashboard JSON export
uvx kb-dashboard-cli compile --format json --output-dir ./output

# Elastic integrations/Fleet package workflow (recommended for integrations)
uvx kb-dashboard-cli compile --format elastic-integrations --output-dir ./output

Format differences:

--format json: Pretty-printed JSON files named by dashboard ID, with nested saved-object fields (for example panelsJSON/optionsJSON) kept as JSON strings.
--format elastic-integrations: JSON files named by dashboard ID with nested saved-object fields unwrapped as JSON objects/arrays, matching Elastic integrations packaging expectations.

Migration guidance for Fleet/integration workflows:

If your pipeline currently uses --format json for Elastic integrations assets, switch to --format elastic-integrations.
--elastic-package-name is deprecated for filename generation and is ignored with --format elastic-integrations (filenames are dashboard-ID-based).

CI Sync Detection¶

Use the --exit-non-zero-on-change flag to detect when YAML and JSON files are out of sync in CI pipelines:

uvx kb-dashboard-cli compile --format elastic-integrations --output-dir ./dashboards --exit-non-zero-on-change
if [ $? -ne 0 ]; then
    echo "Dashboard JSON files are out of sync with YAML sources"
    exit 1
fi

When this flag is enabled, the exit code equals the number of files that changed (capped at 125). By default, the command exits with code 0 on success regardless of whether files changed.

Compile and Upload to Kibana¶

Compile dashboards and upload them directly to Kibana:

uvx kb-dashboard-cli compile --upload

This will compile the dashboards and upload them to a local Kibana instance.

Screenshot Dashboards¶

Generate a PNG screenshot of a dashboard:

uvx kb-dashboard-cli screenshot --dashboard-id <id> --output <file.png>

This will use Kibana's Reporting API to take a screenshot.

Export Dashboard for Issue¶

Export a dashboard from Kibana and create a pre-filled GitHub issue:

uvx kb-dashboard-cli export-for-issue --dashboard-id <id>

This will export the dashboard and open your browser with a pre-filled GitHub issue containing the dashboard NDJSON export.

Disassemble Dashboards¶

Break down a Kibana dashboard JSON into components for easier LLM-based conversion:

uvx kb-dashboard-cli disassemble dashboard.ndjson -o output_dir

This will extract the dashboard into separate files:

metadata.json - Dashboard metadata (id, title, description, version)
options.json - Dashboard display options
controls.json - Control group configuration
filters.json - Dashboard-level filters
references.json - Data view references
panels/ - Individual panel JSON files

For a comprehensive guide on using this tool to convert dashboards from JSON to YAML, see the Dashboard Decompiling Guide.

Decompile Dashboards¶

Generate a YAML dashboard stub from Kibana NDJSON output:

uvx kb-dashboard-cli decompile dashboard.ndjson -o dashboard.yaml

This command emits:

Dashboard metadata (name/id/description where available)
Panel stubs with id, title, size, and position
TODO comments containing original panel JSON for non-trivial manual conversion

Upgrade Legacy YAML Schema¶

Upgrade legacy dashboard YAML from 0.2.7 format to canonical 0.4.0 schema:

uvx kb-dashboard-cli upgrade --input-dir ./dashboards --write

Run in check mode (no writes) and fail CI if upgrades are needed:

uvx kb-dashboard-cli upgrade --input-dir ./dashboards --fail-on-change

kb-dashboard upgrade targets 0.2.7 -> 0.4.0 only; 0.3.x compatibility is intentionally not preserved.

Configuration¶

Environment Variables¶

The CLI supports configuration via environment variables:

export KIBANA_URL=http://localhost:5601
export KIBANA_USERNAME=elastic
export KIBANA_PASSWORD=changeme
export KIBANA_SPACE_ID=my-space  # Optional: target a specific Kibana space
# OR use API key instead
export KIBANA_API_KEY=your-api-key-here

Then simply run:

uvx kb-dashboard-cli compile --upload

Command-Line Options¶

All options can also be specified on the command line:

uvx kb-dashboard-cli compile \
  --upload \
  --kibana-url http://localhost:5601 \
  --kibana-username elastic \
  --kibana-password changeme

To upload to a specific Kibana space:

uvx kb-dashboard-cli compile --upload --kibana-space-id production

Or with environment variables:

export KIBANA_SPACE_ID=staging
uvx kb-dashboard-cli compile --upload

Command Reference¶

The following commands are available in the kb-dashboard-cli CLI. For detailed information about each command and its options, see the auto-generated reference below.

kb-dashboard¶

Kibana Dashboard Compiler - Compile YAML dashboards to Kibana format.

This tool helps you manage Kibana dashboards as code by compiling YAML configurations into Kibana's NDJSON format and optionally uploading them to your Kibana instance.

\b Common workflows: 1. Compile dashboards: kb-dashboard compile 2. Compile and upload: kb-dashboard compile --upload 3. Take a screenshot: kb-dashboard screenshot --dashboard-id ID --output file.png 4. Export for issue: kb-dashboard export-for-issue --dashboard-id ID 5. Disassemble dashboard: kb-dashboard disassemble dashboard.ndjson -o output_dir 6. Decompile dashboard: kb-dashboard decompile dashboard.ndjson -o dashboard.yaml 7. Compare disassembly: kb-dashboard compare original_disassembled compiled_disassembled 8. Upgrade YAML schema: kb-dashboard upgrade --input-dir ./dashboards --write

\b Authentication: Use either username/password OR API key (not both): - Basic auth: --kibana-username USER --kibana-password PASS - API key: --kibana-api-key KEY (recommended for production)

Use environment variables (KIBANA_URL, KIBANA_USERNAME, KIBANA_PASSWORD, KIBANA_API_KEY) to avoid passing credentials on the command line.

Usage:

kb-dashboard [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--version`	boolean	Show the version and exit.	`False`
`--loglevel`	choice (`DEBUG` \| `INFO` \| `WARNING` \| `ERROR`)	Set logging verbosity level for compilation output.	`WARNING`
`--help`	boolean	Show this message and exit.	`False`

compare¶

Compare two disassembled dashboard directories for panel count/type mismatches.

ORIGINAL_DIR and COMPILED_DIR should each be output from kb-dashboard disassemble.

Usage:

kb-dashboard compare [OPTIONS] ORIGINAL_DIR COMPILED_DIR

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

compile¶

Compile YAML dashboard configurations to NDJSON format.

This command finds all YAML files in the input directory (or compiles a single file provided via --input-file), compiles them to Kibana's JSON format, and outputs them as NDJSON files.

Optionally, you can upload the compiled dashboards directly to Kibana using the --upload flag.

The --format option controls output format: - ndjson (default): Groups dashboards by directory into NDJSON files - json: Creates individual pretty-printed JSON files named by dashboard ID - elastic-integrations: Creates individual JSON files with nested saved-object JSON fields unwrapped

By default, the command exits with code 0 on success. Use --exit-non-zero-on-change to enable CI sync detection mode, where the exit code equals the number of files that changed (capped at 125).

\b Examples: # Compile dashboards from default directory kb-dashboard compile

# Compile a single dashboard file
kb-dashboard compile --input-file ./dashboards/example.yaml

# Compile with custom input and output directories
kb-dashboard compile --input-dir ./dashboards --output-dir ./output

# Compile to individual JSON files per dashboard
kb-dashboard compile --format json --output-dir ./output

# Compile and upload to Kibana using basic auth
kb-dashboard compile --upload --kibana-url https://kibana.example.com \
    --kibana-username admin --kibana-password secret

# Compile and upload using API key (recommended)
kb-dashboard compile --upload --kibana-url https://kibana.example.com \
    --kibana-api-key "your-api-key-here"

# Use environment variables for credentials
export KIBANA_URL=https://kibana.example.com
export KIBANA_API_KEY=your-api-key
kb-dashboard compile --upload

Usage:

kb-dashboard compile [OPTIONS]

Options:

Name	Type	Description	Default
`--input-dir`	directory	Directory containing YAML dashboard files to compile.	`/home/runner/work/kb-yaml-to-lens/kb-yaml-to-lens/packages/kb-dashboard-cli/inputs`
`--input-file`	file	Path to a single YAML dashboard file to compile. When provided, --input-dir is ignored.	None
`--output-dir`	directory	Directory where compiled NDJSON files will be written.	`/home/runner/work/kb-yaml-to-lens/kb-yaml-to-lens/packages/kb-dashboard-cli/output`
`--output-file`	text	Filename for the combined output NDJSON file containing all dashboards.	`compiled_dashboards.ndjson`
`--format`	choice (`ndjson` \| `json` \| `elastic-integrations`)	Output format: "ndjson" for combined files (default), "json" for individual pretty-printed files named by dashboard ID, or "elastic-integrations" for individual JSON files with unwrapped nested JSON fields (panelsJSON/optionsJSON/etc).	`ndjson`
`--elastic-package-name`	text	Deprecated for filename generation. elastic-integrations output filenames are now based on dashboard IDs.	None
`--upload`	boolean	Upload compiled dashboards to Kibana immediately after compilation.	`False`
`--kibana-url`	text	Kibana base URL. Example: https://kibana.example.com (env: KIBANA_URL)	`http://localhost:5601`
`--kibana-username`	text	Kibana username for basic authentication. Must be used with --kibana-password. Mutually exclusive with --kibana-api-key. (env: KIBANA_USERNAME)	`Sentinel.UNSET`
`--kibana-password`	text	Kibana password for basic authentication. Must be used with --kibana-username. Mutually exclusive with --kibana-api-key. (env: KIBANA_PASSWORD)	`Sentinel.UNSET`
`--kibana-api-key`	text	Kibana API key for authentication (recommended for production). Mutually exclusive with --kibana-username/--kibana-password. (env: KIBANA_API_KEY)	`Sentinel.UNSET`
`--kibana-space-id`	text	Kibana space ID to upload dashboards to. If not specified, uses the default space. (env: KIBANA_SPACE_ID)	`Sentinel.UNSET`
`--kibana-no-ssl-verify`	boolean	Disable SSL certificate verification (useful for self-signed certificates in local development).	`False`
`--no-browser`	boolean	Prevent browser from opening automatically after successful upload.	`False`
`--overwrite` / `--no-overwrite`	boolean	Whether to overwrite existing dashboards in Kibana (default: overwrite).	`True`
`--exit-non-zero-on-change`	boolean	Exit with non-zero code when files change (useful for CI sync detection).	`False`
`--help`	boolean	Show this message and exit.	`False`

decompile¶

Decompile a Kibana dashboard NDJSON file into YAML stubs.

This command generates a YAML dashboard skeleton from a Kibana dashboard NDJSON export. It preserves panel structure (types, size, position, title) and adds TODO comments with original panel JSON where manual conversion is still required.

\b Examples: # Decompile a dashboard NDJSON file to YAML kb-dashboard decompile dashboard.ndjson -o dashboard.yaml

# Read from stdin
cat dashboard.ndjson | kb-dashboard decompile -o dashboard.yaml

Usage:

kb-dashboard decompile [OPTIONS] [INPUT_FILE]

Options:

Name	Type	Description	Default
`-o`, `--output`	path	Output YAML file path for decompiled dashboard stubs.	`Sentinel.UNSET`
`--help`	boolean	Show this message and exit.	`False`

disassemble¶

Disassemble a Kibana dashboard NDJSON file into components.

This command breaks down a Kibana dashboard JSON file (in NDJSON format) into separate files for easier processing by LLMs. This enables incremental conversion of large dashboards to YAML format.

The dashboard is split into: - metadata.json: Dashboard metadata - options.json: Dashboard display options - controls.json: Dashboard control group configuration - filters.json: Dashboard-level filters - references.json: Data view and index pattern references - panels/: Directory containing individual panel JSON files

\b Examples: # Disassemble a dashboard NDJSON file kb-dashboard disassemble dashboard.ndjson -o output_dir

# Read from stdin
cat dashboard.ndjson | kb-dashboard disassemble -o output_dir

# Download and disassemble directly
curl -u user:pass http://localhost:5601/api/saved_objects/dashboard/my-id | \
    kb-dashboard disassemble -o output_dir

Usage:

kb-dashboard disassemble [OPTIONS] [INPUT_FILE]

Options:

Name	Type	Description	Default
`-o`, `--output`	path	Output directory for component files.	`Sentinel.UNSET`
`--help`	boolean	Show this message and exit.	`False`

docs¶

Access bundled LLM documentation.

\b Examples: kb-dashboard docs list-guides # List available guides kb-dashboard docs llms-full # Output full documentation kb-dashboard docs llms-full | pbcopy # Copy to clipboard (macOS) kb-dashboard docs guide otel-dashboard-guide # Get specific guide

Usage:

kb-dashboard docs [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

guide¶

Output a specific workflow guide.

NAME is the guide name (with or without .md extension).

\b Examples: kb-dashboard docs guide otel-dashboard-guide kb-dashboard docs guide breaking-changes kb-dashboard docs guide esql-language-reference kb-dashboard docs guide dashboard-style-guide

Usage:

kb-dashboard docs guide [OPTIONS] NAME

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

list-guides¶

List available workflow guides.

Displays names of bundled guides that can be accessed with the 'guide' subcommand.

Usage:

kb-dashboard docs list-guides [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

llms-full¶

Output bundled llms-full documentation content.

Usage:

kb-dashboard docs llms-full [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

export-for-issue¶

Export a dashboard from Kibana and create a pre-filled GitHub issue.

This command downloads a dashboard export (NDJSON) from Kibana and generates a GitHub issue URL with the dashboard NDJSON pre-filled in the body. You can then submit the issue to request support for compiling the dashboard from YAML.

\b Examples: # Export dashboard and open pre-filled issue in browser kb-dashboard export-for-issue --dashboard-id my-dashboard-id

# Export with API key authentication
kb-dashboard export-for-issue --dashboard-id my-dashboard-id \
    --kibana-api-key "your-api-key"

# Export and print URL without opening browser
kb-dashboard export-for-issue --dashboard-id my-dashboard-id --no-browser

Usage:

kb-dashboard export-for-issue [OPTIONS]

Options:

Name	Type	Description	Default
`--dashboard-id`	text	Kibana dashboard ID to export. Find this in the dashboard URL.	`Sentinel.UNSET`
`--kibana-url`	text	Kibana base URL. Example: https://kibana.example.com (env: KIBANA_URL)	`http://localhost:5601`
`--kibana-username`	text	Kibana username for basic authentication. Must be used with --kibana-password. Mutually exclusive with --kibana-api-key. (env: KIBANA_USERNAME)	`Sentinel.UNSET`
`--kibana-password`	text	Kibana password for basic authentication. Must be used with --kibana-username. Mutually exclusive with --kibana-api-key. (env: KIBANA_PASSWORD)	`Sentinel.UNSET`
`--kibana-api-key`	text	Kibana API key for authentication (recommended for production). Mutually exclusive with --kibana-username/--kibana-password. (env: KIBANA_API_KEY)	`Sentinel.UNSET`
`--kibana-space-id`	text	Kibana space ID to upload dashboards to. If not specified, uses the default space. (env: KIBANA_SPACE_ID)	`Sentinel.UNSET`
`--kibana-no-ssl-verify`	boolean	Disable SSL certificate verification (useful for self-signed certificates in local development).	`False`
`--no-browser`	boolean	Do not open browser automatically with pre-filled issue.	`False`
`--help`	boolean	Show this message and exit.	`False`

extract-sample-data¶

Extract data from Elasticsearch to NDJSON format.

This command queries Elasticsearch and exports the results to an NDJSON file that can be used as sample data for dashboards. Each line in the output file is a separate JSON document.

\b Examples: # Extract logs data kb-dashboard extract-sample-data --index logs-* --output sample-logs.ndjson

# Extract with custom query
kb-dashboard extract-sample-data --index metrics-* --output sample-metrics.ndjson \
    --query 'host.name:server01'

# Extract limited number of documents
kb-dashboard extract-sample-data --index logs-* --output sample.ndjson --max-docs 100

# With authentication
kb-dashboard extract-sample-data --index logs-* --output sample.ndjson \
    --es-url https://es.example.com --es-api-key "your-api-key"

Usage:

kb-dashboard extract-sample-data [OPTIONS]

Options:

Name	Type	Description	Default
`--index`	text	Elasticsearch index pattern to extract data from (e.g., logs-, metrics-).	`Sentinel.UNSET`
`--output`	path	Path where the NDJSON file will be saved.	`Sentinel.UNSET`
`--query`	text	Elasticsearch query to filter documents (default: * for all documents).	`*`
`--max-docs`	integer	Maximum number of documents to extract (default: 1000).	`1000`
`--es-url`	text	Elasticsearch base URL. Example: https://elasticsearch.example.com (env: ELASTICSEARCH_URL)	`http://localhost:9200`
`--es-username`	text	Elasticsearch username for basic authentication (env: ELASTICSEARCH_USERNAME)	`Sentinel.UNSET`
`--es-password`	text	Elasticsearch password for basic authentication (env: ELASTICSEARCH_PASSWORD)	`Sentinel.UNSET`
`--es-api-key`	text	Elasticsearch API key for authentication (env: ELASTICSEARCH_API_KEY)	`Sentinel.UNSET`
`--es-no-ssl-verify`	boolean	Disable SSL certificate verification for Elasticsearch connections.	`False`
`--help`	boolean	Show this message and exit.	`False`

fetch¶

Fetch a dashboard from Kibana and save it to a file.

This command retrieves a dashboard's NDJSON from Kibana using a dashboard URL or ID. The dashboard and all its dependent objects (panels, data views) are exported and saved to the specified output file.

URL_OR_ID can be: - A Kibana dashboard URL (e.g., https://kibana.example.com/app/dashboards#/view/my-id) - A plain dashboard ID (e.g., my-dashboard-id)

\b Examples: # Fetch using dashboard URL kb-dashboard fetch "https://kibana.example.com/app/dashboards#/view/my-id" \ --output dashboard.ndjson

# Fetch using plain dashboard ID
kb-dashboard fetch my-dashboard-id --output dashboard.ndjson

# Fetch with API key authentication
kb-dashboard fetch my-dashboard-id --output dashboard.ndjson \
    --kibana-api-key "your-api-key"

# Fetch from specific space
kb-dashboard fetch my-dashboard-id --output dashboard.ndjson \
    --kibana-space-id "my-space"

Usage:

kb-dashboard fetch [OPTIONS] URL_OR_ID

Options:

Name	Type	Description	Default
`-o`, `--output`	path	Output file path for the dashboard NDJSON.	`Sentinel.UNSET`
`--kibana-url`	text	Kibana base URL. Example: https://kibana.example.com (env: KIBANA_URL)	`http://localhost:5601`
`--kibana-username`	text	Kibana username for basic authentication. Must be used with --kibana-password. Mutually exclusive with --kibana-api-key. (env: KIBANA_USERNAME)	`Sentinel.UNSET`
`--kibana-password`	text	Kibana password for basic authentication. Must be used with --kibana-username. Mutually exclusive with --kibana-api-key. (env: KIBANA_PASSWORD)	`Sentinel.UNSET`
`--kibana-api-key`	text	Kibana API key for authentication (recommended for production). Mutually exclusive with --kibana-username/--kibana-password. (env: KIBANA_API_KEY)	`Sentinel.UNSET`
`--kibana-space-id`	text	Kibana space ID to upload dashboards to. If not specified, uses the default space. (env: KIBANA_SPACE_ID)	`Sentinel.UNSET`
`--kibana-no-ssl-verify`	boolean	Disable SSL certificate verification (useful for self-signed certificates in local development).	`False`
`--help`	boolean	Show this message and exit.	`False`

load-sample-data¶

Load sample data bundled with dashboards into Elasticsearch via Kibana.

This command scans the input directory for YAML dashboard configurations that include sample data, and loads that data into Elasticsearch through Kibana's console proxy API. The sample data will be automatically transformed so the maximum timestamp becomes "now", making the data appear as if it just happened.

\b Examples: # Load sample data from default directory kb-dashboard load-sample-data

# Load with custom input directory
kb-dashboard load-sample-data --input-dir ./dashboards

# Load with Kibana authentication
kb-dashboard load-sample-data --kibana-url https://kibana.example.com \
    --kibana-username admin --kibana-password secret

# Use API key (recommended)
kb-dashboard load-sample-data --kibana-url https://kibana.example.com \
    --kibana-api-key "your-api-key-here"

# Load to a specific Kibana space
kb-dashboard load-sample-data --kibana-url https://kibana.example.com \
    --kibana-api-key "your-api-key" --kibana-space-id "my-space"

Usage:

kb-dashboard load-sample-data [OPTIONS]

Options:

Name	Type	Description	Default
`--input-dir`	directory	Directory containing YAML dashboard files with sample data.	None
`--kibana-url`	text	Kibana base URL. Example: https://kibana.example.com (env: KIBANA_URL)	`http://localhost:5601`
`--kibana-username`	text	Kibana username for basic authentication. Must be used with --kibana-password. Mutually exclusive with --kibana-api-key. (env: KIBANA_USERNAME)	`Sentinel.UNSET`
`--kibana-password`	text	Kibana password for basic authentication. Must be used with --kibana-username. Mutually exclusive with --kibana-api-key. (env: KIBANA_PASSWORD)	`Sentinel.UNSET`
`--kibana-api-key`	text	Kibana API key for authentication (recommended for production). Mutually exclusive with --kibana-username/--kibana-password. (env: KIBANA_API_KEY)	`Sentinel.UNSET`
`--kibana-space-id`	text	Kibana space ID to upload dashboards to. If not specified, uses the default space. (env: KIBANA_SPACE_ID)	`Sentinel.UNSET`
`--kibana-no-ssl-verify`	boolean	Disable SSL certificate verification (useful for self-signed certificates in local development).	`False`
`--help`	boolean	Show this message and exit.	`False`

lsp¶

Start the Language Server Protocol (LSP) server for IDE integration.

The LSP server provides real-time compilation, validation, and code completion for YAML dashboard files in supported IDEs like VS Code.

This server communicates via stdin/stdout using the Language Server Protocol specification.

Usage:

kb-dashboard lsp [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

screenshot¶

Generate a PNG screenshot of a Kibana dashboard.

This command uses Kibana's Reporting API to generate a screenshot of the specified dashboard. You can optionally specify a time range for the dashboard data.

Examples: # Screenshot with default settings kb-dashboard screenshot --dashboard-id my-dashboard --output dashboard.png

# Screenshot with custom time range
kb-dashboard screenshot --dashboard-id my-dashboard --output dashboard.png \
    --time-from "2024-01-01T00:00:00Z" --time-to "2024-12-31T23:59:59Z"

# Screenshot with relative time range
kb-dashboard screenshot --dashboard-id my-dashboard --output dashboard.png \
    --time-from "now-7d" --time-to "now"

# Screenshot with custom dimensions
kb-dashboard screenshot --dashboard-id my-dashboard --output dashboard.png \
    --width 3840 --height 2160

Usage:

kb-dashboard screenshot [OPTIONS]

Options:

Name	Type	Description	Default
`--dashboard-id`	text	Kibana dashboard ID to capture. Find this in the dashboard URL.	`Sentinel.UNSET`
`--output`	path	Path where the PNG screenshot will be saved. Example: ./dashboard.png	`Sentinel.UNSET`
`--time-from`	text	Start time for dashboard data range. Accepts ISO 8601 format ("2024-01-01T00:00:00Z") or relative time ("now-7d", "now-24h", "now-1M"). If omitted, uses dashboard default.	`Sentinel.UNSET`
`--time-to`	text	End time for dashboard data range. Accepts ISO 8601 format ("2024-12-31T23:59:59Z") or relative time ("now", "now-1h"). If omitted, uses dashboard default.	`Sentinel.UNSET`
`--width`	integer range (`1` and above)	Screenshot width in pixels. Standard resolutions: 1920 (Full HD), 3840 (4K). Default: 1920	`1920`
`--height`	integer range (`1` and above)	Screenshot height in pixels. Standard resolutions: 1080 (Full HD), 2160 (4K). Default: 1080	`1080`
`--browser-timezone`	text	Browser timezone for rendering time-based data. Examples: "UTC", "America/New_York", "Europe/London". Default: UTC	`UTC`
`--timeout`	integer range (`1` and above)	Maximum time in seconds to wait for screenshot generation. Increase for complex dashboards. Default: 300	`300`
`--kibana-url`	text	Kibana base URL. Example: https://kibana.example.com (env: KIBANA_URL)	`http://localhost:5601`
`--kibana-username`	text	Kibana username for basic authentication. Must be used with --kibana-password. Mutually exclusive with --kibana-api-key. (env: KIBANA_USERNAME)	`Sentinel.UNSET`
`--kibana-password`	text	Kibana password for basic authentication. Must be used with --kibana-username. Mutually exclusive with --kibana-api-key. (env: KIBANA_PASSWORD)	`Sentinel.UNSET`
`--kibana-api-key`	text	Kibana API key for authentication (recommended for production). Mutually exclusive with --kibana-username/--kibana-password. (env: KIBANA_API_KEY)	`Sentinel.UNSET`
`--kibana-space-id`	text	Kibana space ID to upload dashboards to. If not specified, uses the default space. (env: KIBANA_SPACE_ID)	`Sentinel.UNSET`
`--kibana-no-ssl-verify`	boolean	Disable SSL certificate verification (useful for self-signed certificates in local development).	`False`
`--help`	boolean	Show this message and exit.	`False`

upgrade¶

Upgrade dashboard YAML schema from 0.2.7 to 0.4.0.

This command only targets the 0.2.7 -> 0.4.0 migration path. 0.3.x compatibility is intentionally not preserved.

Usage:

kb-dashboard upgrade [OPTIONS]

Options:

Name	Type	Description	Default
`--input-dir`	directory	Directory containing dashboard YAML files.	`inputs`
`--input-file`	file	Single YAML dashboard file to upgrade. When provided, --input-dir is ignored.	None
`--write`	boolean	Write changes in-place. Without this flag, runs in check mode.	`False`
`--fail-on-change`	boolean	Exit with non-zero status if upgrades are needed.	`False`
`--help`	boolean	Show this message and exit.	`False`

Justfile Shortcuts (Development)¶

For contributors working from a cloned repository, the project includes convenient justfile targets:

# Compile only
just cli compile

# Compile and upload (uses environment variables for Kibana config)
just cli upload

See DEVELOPING.md for the full development workflow.

Authentication¶

The CLI supports two authentication methods:

Basic Authentication¶

Use username and password:

uvx kb-dashboard-cli compile \
  --upload \
  --kibana-username elastic \
  --kibana-password changeme

Or via environment variables:

export KIBANA_USERNAME=elastic
export KIBANA_PASSWORD=changeme
uvx kb-dashboard-cli compile --upload

API Key Authentication¶

Use a Kibana API key:

uvx kb-dashboard-cli compile \
  --upload \
  --kibana-api-key "your-base64-encoded-key"

Or via environment variable:

export KIBANA_API_KEY="your-base64-encoded-key"
uvx kb-dashboard-cli compile --upload

To create an API key in Kibana:

Go to Stack Management → API Keys
Click "Create API key"
Give it a name and set appropriate privileges
Copy the encoded key and use it with the CLI

Troubleshooting¶

Connection Refused¶

If you get a connection refused error:

Verify Kibana is running: curl http://localhost:5601/api/status
Check the Kibana URL is correct
Ensure there are no firewall rules blocking the connection

Authentication Failed¶

If you get authentication errors:

Verify your credentials are correct
Check that the user has appropriate permissions
For API keys, ensure the key hasn't expired

Upload Errors¶

If objects fail to upload:

Check the Kibana logs for detailed error messages
Verify the NDJSON format is valid
Use --no-overwrite if you want to preserve existing objects

Dashboard Linter CLI¶

The kb-dashboard-lint CLI tool checks YAML dashboard configurations for best practices and common issues.

Basic Usage¶

Check a single dashboard file:

uvx kb-dashboard-lint check --input-file ./dashboards/example.yaml

Check all dashboards in a directory:

uvx kb-dashboard-lint check --input-dir ./dashboards

Severity Levels¶

The linter reports issues at three severity levels:

Level	Description
error	Critical issues that should be fixed
warning	Problems that may affect usability
info	Suggestions for improvement

By default, the linter exits with code 0 for info-only results. Use --severity-threshold to fail on warnings:

uvx kb-dashboard-lint check --input-file dashboard.yaml --severity-threshold warning

List Available Rules¶

See all lint rules and their descriptions:

uvx kb-dashboard-lint list-rules

Configuration¶

Create a .dashboard-lint.yaml file to customize rule behavior:

uvx kb-dashboard-lint check --config .dashboard-lint.yaml

Output Formats¶

Get machine-readable output for CI integration:

uvx kb-dashboard-lint check --input-dir ./dashboards --format json

Linter Command Reference¶

kb-dashboard-lint¶

Dashboard Linter - Check YAML dashboards for best practices.

This tool analyzes dashboard configurations and flags potentially problematic patterns based on configurable rules.

Usage:

kb-dashboard-lint [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--version`	boolean	Show the version and exit.	`False`
`--help`	boolean	Show this message and exit.	`False`

check¶

Check dashboard YAML files for issues.

Examples: kb-dashboard-lint check --input-dir ./inputs

kb-dashboard-lint check --input-file dashboard.yaml

kb-dashboard-lint check --config .dashboard-lint.yaml

Usage:

kb-dashboard-lint check [OPTIONS]

Options:

Name	Type	Description	Default
`--input-dir`	directory	Directory containing YAML dashboard files.	None
`--input-file`	file	Single YAML file to check.	None
`--config`	file	Path to lint configuration file.	None
`--severity-threshold`	choice (`error` \| `warning` \| `info`)	Exit non-zero if violations at this severity or higher are found.	`warning`
`--format`	choice (`text` \| `json`)	Output format.	`text`
`--help`	boolean	Show this message and exit.	`False`

list-rules¶

List all available lint rules.

Usage:

kb-dashboard-lint list-rules [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`