Metadata-Version: 2.4
Name: kater-cli
Version: 0.1.7
Summary: Kater command-line interface
Requires-Python: >=3.12
Requires-Dist: kater>=0.11.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: pathspec>=0.12.1
Requires-Dist: pydantic-settings>=2.6.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=13.9.0
Requires-Dist: structlog>=25.0.0
Requires-Dist: typer>=0.12.0
Requires-Dist: watchfiles>=0.21.0
Requires-Dist: websockets>=12.0
Description-Content-Type: text/markdown

# kater-cli

The official command-line interface for [Kater](https://kater.ai) — 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

```bash
pipx install kater-cli
```

Requires Python 3.12+.

## Quick start

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

# Create an account, then authenticate this CLI
kater signup

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

```bash
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.

```bash
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.

```bash
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 signup` / `kater login` / `kater logout` / `kater status`

Browser-based signup and OAuth 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 |
| `KATER_SIGNUP_URL`          | `https://kater.ai/signup?plan=pro&billing=yearly&product_line=cloud` | Signup URL opened by the CLI |

## Links

- [Kater documentation](https://docs.kater.ai)
- [kater.ai](https://kater.ai)
