kawa-dsl
Terraform-like CLI for managing KAWA 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
pip install kawa-dsl
After installation, kawa is available on your PATH:
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:
KAWA_API_URL=https://kawa.mycompany.com
KAWA_API_KEY=ka_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Quick start
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 |
kawa export --no-data |
Schema only: no file-datasource blob (CSV, Excel, …) and no editable rows travel; non-data assets (widget images) still do |
kawa export --anonymize-data |
The data travels with every value replaced and every column's KAWA type preserved (text/integer/decimal/boolean/date/date_time re-infer identically on import). Exclusive with --no-data |
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 |
# 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.
1 maintainer
Metadata
1 maintainer
Release files for kawa-dsl 2.4.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| kawa_dsl-2.4.4.tar.gz | 722.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| kawa_dsl-2.4.4-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.5 MB
Release files / kawa_dsl-2.4.4.tar.gz
| Download URL | kawa_dsl-2.4.4.tar.gz |
|---|---|
| Size | 722.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9d0dfe19cce467d1fd47f5c313fb3fc088944a7e38c09443c110b60ab7d4e47e
|
|
BLAKE2b-256 checksum How to use checksums |
2e3f7edf646527109717e57c0f740181241bc61cf3fba60c1c0eecbee7ece724
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.0
|
Release files / kawa_dsl-2.4.4-py3-none-any.whl
| Download URL | kawa_dsl-2.4.4-py3-none-any.whl |
|---|---|
| Size | 782.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
64f98d2a63dbdf7da355f0e96271424f30c41c4e18f02e605ffd0b24d315a9bb
|
|
BLAKE2b-256 checksum How to use checksums |
0ded78a0113fbaa01826c134bbec70035e276f947b0f11c404024d8c520b1067
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.0
|
