Konsol

Command-line client for configuring the konsol Frappe app.

All configuration goes through konsol — never dbt or ClickHouse directly.

Install

cd konsol_cli
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Optional MCP server:

pip install -e ".[mcp]"

Two ways to connect

1. Local Docker (default)

Talks to konsol by running bench execute inside your Docker stack.

konsol dimension list --compose-file ../repo/docker-compose.yml

2. Remote HTTP API

Talks to any running konsol site over the Frappe API. Use this from your laptop against a remote server, in CI, or with MCP.

First, create API keys in Frappe:

1. Log into the site as an EPM Admin user
2. Go to User → your user → Settings tab → API Access
3. Click Generate Keys and save the key + secret

Then run commands:

konsol --backend api \
  --url http://localhost:8069 \
  --site konsolidat.local \
  --api-key YOUR_KEY \
  --api-secret YOUR_SECRET \
  dimension list

When connecting to localhost:8069, keep --site set — the CLI sends it as the Host header so Frappe routes to the right site.

Optional config file — copy config.example.toml to ~/.config/konsol/config.toml (connection settings only).

Credentials (pick one, never commit):

cp secrets.example.env ~/.config/konsol/secrets.env && chmod 600 ~/.config/konsol/secrets.env
# or: secrets.example.toml → ~/.config/konsol/secrets.toml

The CLI loads secrets.env first, then secrets.toml. Shell env vars take precedence.

Grok MCP — configs use ${KONSOL_API_KEY} placeholders. Before starting Grok:

source scripts/load-konsol-secrets.sh   # exports vars, does not print them
grok mcp doctor konsol

See .grok/config.toml (project-scoped, safe to commit) — not plaintext secrets.

Commands

# Dimensions
konsol dimension list
konsol dimension show dim_cost_center
konsol dimension create dim_project --source-column Project --label "Project"
konsol dimension publish dim_project
konsol dimension unpublish dim_project

# Measures
konsol measure list
konsol measure create period_headcount --expression "sum(headcount)" --label "Headcount"
konsol measure unpublish period_headcount

# Fact tables
konsol fact list
konsol fact show headcount
konsol fact create my_fact --label "My Fact" --source-type Statistical \
  --clickhouse-table epm_staging.fact_x --scenario-key statistical
konsol fact publish my_fact
konsol fact unpublish my_fact

# Connectors & ERP sources
konsol connector list
konsol connector show CONN-00001
konsol connector create --name "ERPNext Demo" --erp-type erpnext --entity-id ENT01
konsol connector delete CONN-00001
konsol source list

# Config (GitOps YAML)
konsol config export -o model.yaml
konsol config diff model.yaml
konsol config apply model.yaml [--publish] [--prune] [--dry-run]

# Schema
konsol schema apply
konsol schema status

MCP (AI clients)

Install the optional extra, then add mcp.example.json to your MCP client config (Cursor, Claude Desktop, etc.):

pip install -e ".[mcp]"

Set KONSOL_URL, KONSOL_SITE, KONSOL_API_KEY, and KONSOL_API_SECRET in the server env block, then run konsol-mcp (stdio transport).

Connector Airbyte tools (v0.10.0+): test_connector_writeback, provision_connector_airbyte — require the matching konsol app endpoints on your site.

Debug with the MCP Inspector:

npx @modelcontextprotocol/inspector konsol-mcp

Environment variables

Variable	Purpose
KONSOL_BACKEND	bench (default) or api
KONSOL_SITE	Frappe site name
KONSOL_URL	Site URL for api backend
KONSOL_API_KEY	Frappe API key
KONSOL_API_SECRET	Frappe API secret
KONSOL_COMPOSE_FILE	Path to docker-compose.yml for bench backend

Docker deploy note

bench get-app installs konsol from git HEAD, not uncommitted files. Commit konsol changes before docker compose build frappe_backend.

Architecture

konsol-cli / konsol-mcp
  → bench execute  or  HTTP /api/method/konsol.cli_api.*
  → konsol.config_service  →  Frappe DocTypes
  → publish / apply_schema  →  dbt vars, ClickHouse DDL, Pipeline Build Request

Tests

cd konsol_cli && .venv/bin/python -m pytest tests/ -q
cd repo/docker/frappe/konsol && PYTHONPATH=konsol .venv/bin/python -m pytest konsol/tests/test_config_service.py -q