Metadata-Version: 2.4
Name: kawa-dsl
Version: 2.1.0
Summary: Terraform-like CLI for managing KAWA workspaces as code
Author-email: Kawa Analytics <emmanuel@kawa.ai>
License: MIT License
        
        Copyright (c) 2026 Kawa Analytics
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://www.kawa.ai
Keywords: kawa,dsl,data,dashboard,etl,workflow,cli
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: kywy>=0.37.1
Requires-Dist: tomli-w>=1.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: paramiko>=3.0
Requires-Dist: PyJWT[crypto]>=2.13
Dynamic: license-file

# kawa-dsl

Terraform-like CLI for managing [KAWA](https://www.kawa.ai) workspaces as code — datasources, sheets, views, dashboards, scripts, workflows, agents, artifacts and skills are defined in TOML files under `dsl/` and pushed to KAWA via `kawa commit`.

## Install

```bash
pip install kawa-dsl
```

After installation, `kawa` is available on your PATH:

```bash
kawa --help
```

## Configure

The CLI talks to your KAWA server using two environment variables. Set them in your shell, or drop a `.env` file in the directory you run `kawa` from — it is picked up automatically.

| Variable | Required | Description |
|---|---|---|
| `KAWA_API_URL` | yes | Base URL of your KAWA server, e.g. `https://kawa.mycompany.com`. No trailing slash. |
| `KAWA_API_KEY` | yes | API key from the KAWA UI → *Settings → API keys*. Sent as `Authorization: Bearer <key>`. |
| `KAWA_DSL_HOME` | no | Where local config lives. Defaults to `./.kawa` (cwd-relative). |

Example `.env`:

```env
KAWA_API_URL=https://kawa.mycompany.com
KAWA_API_KEY=ka_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## Quick start

```bash
mkdir my-workspace && cd my-workspace
kawa init                          # creates .kawa/ in cwd
kawa checkout <workspace_id>       # clones the workspace into ./dsl/
# edit files under dsl/
kawa plan                          # preview what would change
kawa commit                        # push changes back to KAWA
```

## Workspace layout

`kawa checkout` materializes the workspace as one TOML file per entity:

```
my-workspace/
├── workspace.toml        # workspace binding
├── dsl/
│   ├── scripts/          # script metadata (source lives in scripts/)
│   ├── datasources/
│   ├── sheets/
│   ├── views/            # one file per view, bound to its sheet by tag
│   ├── dashboards/
│   ├── workflows/
│   ├── agents/
│   ├── artifacts/        # versioned artifact ledgers
│   └── skills/           # versioned skill ledgers
├── scripts/              # Python/SQL source files
├── files/                # file-datasource blobs
└── data/                 # editable-datasource row snapshots (export only)
```

Every entity carries an `immutable_tag` — a rename-proof identity that is stable across servers. Bundles produced by `kawa export` are addressed by tag, which is what makes them portable to any workspace on any server.

## Commands

### Workspace lifecycle

| Command | Description |
|---|---|
| `kawa init` | Initialize `$KAWA_DSL_HOME` and print setup instructions |
| `kawa checkout <ws_id>` | Clone a workspace into `./dsl/` |
| `kawa status` | Show branch, workspace, user, connection checks |
| `kawa app list` | List workspaces accessible to the current user |
| `kawa app create <name>` | Create a new workspace |
| `kawa list` | Show workspace contents as a tree |

### Plan & apply

| Command | Description |
|---|---|
| `kawa plan` | Preview what would change (read-only) |
| `kawa commit` | Refresh + plan + apply (`--yes` to skip the prompt, `--delete` to allow deletions) |
| `kawa refresh` | Rebuild local state from KAWA (never touches `dsl/` files) |
| `kawa pull` | Pull fresh KAWA state, preserving local changes |
| `kawa check` | Dry-run scripts and validate sheet formulas before pushing |

### Transfer between workspaces & servers

| Command | Description |
|---|---|
| `kawa inventory [--json]` | List every entity per kind: name, description, immutable tag, created date, owner |
| `kawa export` | Export the workspace to a portable ZIP bundle (`--no-data` for schema only) |
| `kawa export --tags=t1,t2` | Selective export: the named entities **plus their dependency closure** (sheet → datasource → script, view → sheet, dashboard → sheets, workflow → scripts/sub-workflows, …) |
| `kawa export --tags=t1,t2 --no-deps` | Exactly the named entities, no closure — for targets that already hold the dependencies (tag-matched update-in-place) |
| `kawa import <bundle.zip> --workspace-id=N` | Apply a bundle to any target workspace — `--url`/`--api-key` for another server, `--plan-only` for a dry run, `--yes` to apply without prompting |

```bash
# move two dashboards (and everything they depend on) to another server
kawa inventory --workspace-id=12                  # find the tags
kawa export --workspace-id=12 --tags=sales_ab12cd34ef,ops_cd34ef56ab --output=partial.zip
kawa import partial.zip --workspace-id=7 --url=https://other-kawa.mycompany.com --api-key=ka_live_... --yes
```

### Data

| Command | Description |
|---|---|
| `kawa patch <sheet> --action INSERT\|UPDATE\|DELETE --rows '...'` | Insert / update / delete rows on an editable datasource |
| `kawa run workflow <id-or-name>` | Execute a workflow |
| `kawa run datasource <name>` | Trigger an ETL refresh |
| `kawa datasources status <name>` | Latest ETL sync state |
| `kawa workflows logs\|status <name>` | Workflow execution logs / status |

### Scripts

| Command | Description |
|---|---|
| `kawa scripts init --name "X"` | Start a script draft at `scripts/X.py` |
| `kawa scripts checkout --name "X"` | Pull the live script source for editing |
| `kawa scripts register --name "X"` | Publish (create-or-update, with check gate) |
| `kawa scripts logs\|status <name>` | Execution logs / status |

### Artifacts & files

| Command | Description |
|---|---|
| `kawa artifact init\|checkout\|register` | Draft / edit / publish artifact versions |
| `kawa artifact list\|show\|describe` | Inspect artifacts |
| `kawa artifact query\|patch\|generate '<json>'` | Replay artifact-api calls |
| `kawa artifact workflow run\|status\|definition` | Drive workflows through the artifact API |
| `kawa files put <path>` / `kawa files get <fileId> <path>` | Upload / download files |

### Skills

| Command | Description |
|---|---|
| `kawa skills init --name N --description D` | Start a structured skill draft |
| `kawa skills check <dir>` | Validate a skill directory |
| `kawa skills register --name SLUG` | Publish the draft as a project skill version |
| `kawa skills checkout\|list\|show\|archive` | Edit / inspect / archive project skills |

### Providers (JDBC)

| Command | Description |
|---|---|
| `kawa providers list-databases <provider>` | List reachable databases |
| `kawa providers list-tables <provider> <db>` | List tables |
| `kawa providers describe-table <provider> <db> <table>` | Schema + sample rows |
| `kawa providers test-query <provider> <sql>` | Schema + sample rows for a custom query |

### Topology & governance

| Command | Description |
|---|---|
| `kawa graph [--out g.json] [--html t.html]` | Extract the workspace topology graph |
| `kawa sox snapshot\|promote\|plan\|deploy\|drift\|history` | SOX promotion pipeline (workspace → reviewable tree → governed deploy) |
| `kawa secrets push` | Upsert `K_SECRET_VALUE_*` env secrets into the workspace |

## Common options

| Option | Description |
|---|---|
| `--work-dir=PATH` | Workspace directory override (default: current directory) |
| `--auto-approve` / `--yes` / `-y` | Skip confirmation prompts (`commit`, `import`) |
| `--delete` | (`commit` only) Allow entity deletions — blocked by default |

Every subcommand documents its own flags: `kawa <command> --help`.
