kater-cli 0.1.3

Kater command-line interface

kater-cli

The official command-line interface for Kater — a semantic analytics platform that turns parameterized query templates into governed, multi-tenant SQL.

What is Kater?

Kater lets data teams build a small library of composable query templates with slots for metrics, dimensions, filters, and calculations. Those templates combine into hundreds of governed query variations, which product and ops teams can run without writing SQL.

The CLI is how you develop locally: sync your files to the platform, validate your schemas, compile templates to SQL, and execute queries against your warehouse.

Installation

pipx install kater-cli

Requires Python 3.12+.

Quick start

# Initialize a new Kater project in the current directory
kater install

# Log in via browser-based OAuth
kater login

# Sync your local files to the Kater platform (keep this running while you work)
kater dev

# In another terminal: validate your schemas
kater validate

# Compile a query template to SQL
kater compile COMPLIANCE_OVERVIEW

# Execute a query and display results
kater run COMPLIANCE_OVERVIEW

Commands

kater install

Scaffolds a new Kater project in the current directory, creating the standard file structure including config, admin settings, and a getting-started guide.

kater dev

Syncs your local repository files to the Kater platform over a persistent WebSocket connection. File changes are detected and synced automatically. Keep this running in the background while working on your templates.

kater validate

Validates all semantic layer schemas (views, queries, filters, measures) for correctness. On success, writes the dependency graph and tenant schemas back to your local repo.

kater validate                          # validate all connections
kater validate -c snowflake_prod        # validate a specific connection
kater validate --topic compliance -c snowflake_prod
kater validate --branch main            # validate from a git branch

kater compile

Compiles a query template to SQL and writes the output back to your repo via the dev session.

kater compile COMPLIANCE_OVERVIEW
kater compile COMPLIANCE_OVERVIEW --combination 'measure=Compliance Rate,dimension=Department'
kater compile --topic compliance -c snowflake_prod
kater compile COMPLIANCE_OVERVIEW --branch main

kater run

Executes a compiled query against your warehouse and displays results as a table.

kater run COMPLIANCE_OVERVIEW
kater run COMPLIANCE_OVERVIEW --tenant acme_corp
kater run COMPLIANCE_OVERVIEW --limit 20
kater run topics/compliance/queries/ --sample 1   # run one combination per query in folder

kater scaffold topic

Creates a new topic directory with the standard subdirectory structure (queries, query_views, dashboards, reportflows).

kater login / kater logout / kater status

OAuth-based authentication. Credentials are stored securely in the system keychain (macOS Keychain, Windows Credential Locker, Linux Secret Service).

Configuration

The CLI connects to https://api.kater.ai by default. Override with environment variables:

Variable	Default	Description
KATER_API_URL	https://api.kater.ai	Kater API base URL
KATER_OAUTH_AUTH_URL	https://auth.kater.ai/propelauth/oauth/authorize	OAuth authorization endpoint
KATER_OAUTH_TOKEN_URL	https://auth.kater.ai/propelauth/oauth/token	OAuth token endpoint
KATER_OAUTH_CALLBACK_PORT	9876	Local port for OAuth callback

Links

• Kater documentation
• kater.ai