Data & Entities

These commands store, read, search, and reshape structured data, from quick JSON queries to the platform’s entity/datastore layer. If you haven’t read Entities & datastores in Core Concepts, skim it first; it explains the data model these commands operate on.

kis find

What it is. Searches a directory of JSON files and returns the ones matching a query expression.

Why it exists. When you have hundreds of JSON result files (classifications, extractions, test outputs), you need a fast way to answer “which ones failed?” or “which scored below 0.9?” without writing a script each time. find is grep for structured JSON.

When to reach for it. Filtering a folder of JSON by predicate. To aggregate or reshape their contents instead, use query.

How to use it. Expressions use the expr language, so you get real comparisons, logic, and functions:

# Comparisons (= and == both work)
kis find -i ./input "confidence > 0.95"
kis find -i ./input "document_type = '1003'"
kis find -i ./input "status != 'failed'"

# Recursive, logic, nested fields
kis find -r -i ./input "status = 'failed'"
kis find -i ./input "status == 'done' and confidence > 0.9"
kis find -i ./input "metadata.pages > 10"

# Strings, membership, nil, arrays
kis find -i ./input "error_message contains 'timeout'"
kis find -i ./input "status in ['pending', 'processing']"
kis find -i ./input "errors != nil"
kis find -i ./input "len(pages) > 5"
kis find -i ./input "any(pages, {.confidence > 0.9})"

Flag	Meaning
-i, --input	Directory to search (default .)
-r, --recursive	Recurse into subdirectories
-p, --pattern	File pattern (default *.json)
-c, --count	Print only the count of matches
-q, --quiet	Print only filenames
-v, --show-value	Print the full JSON on match
-m, --meta	Inject _filename and _path into the expression context

kis query

What it is. Runs predefined or custom jq queries over JSON results, with output as JSON, CSV, table, TSV, or raw.

Why it exists. Where find selects files, query aggregates and reshapes their contents, totals, breakdowns, exports for a spreadsheet, using the full power of jq plus a library of named queries.

When to reach for it. Summarizing or exporting across many JSON files. Start with --list to see what’s already built in.

kis query --list                                   # list available queries
kis query summary -i ./quality                     # run a named query
kis query totals -i ./quality -o totals.json       # save to a file
kis query by-doctype -i ./quality -o breakdown.csv # export CSV
kis query -i ./quality --raw '[.[] | .total_pages] | add'   # raw jq
kis query my-query -i ./quality --queries ./my-queries.yaml # custom query file

Flag	Meaning
-i, --input	JSON file or directory (default .)
--list	List available queries
-r, --raw	Run a raw jq query directly
-o, --output	Output file (default stdout)
-f, --format	json, csv, table, raw, tsv
--queries	Custom queries YAML file
-m, --meta	Inject _filename/_doctype from the source filename

kis write-entity

What it is. Writes JSON record(s), shaped by an entity definition, into a database described by a dbpool file.

Why it exists. It’s the platform’s “insert” for structured, validated data: your entity definition enforces the shape, the dbpool file says where it lands, and the tenant/schema flags scope whose data it is.

When to reach for it. Persisting records that conform to an entity. Pair it with read-entity to get them back.

kis write-entity \
  --definition entities/faq.yaml \
  --dbpool dbpool.yaml \
  --file record.json \
  --schema system:system:system:system \
  --tenant my-tenant

Flag	Meaning
-d, --definition	Entity definition file
-p, --dbpool	dbpool file (connection config)
-f, --file	JSON file with the record(s)
-s, --schema	Schema path (default system:system:system:system)
-t, --tenant	Tenant key
--cert / --key / --rootca	TLS material
--cluster / --datacenter / --sid	Deployment identifiers
--config	Path to a config file

Note

The four colon-separated segments in --schema (system:system:system:system) are the CPET identity, customer:product:environment:tenant, the same shape as kis script run --cpet. See Identity & Access, CPET.

kis read-entity

What it is. Reads records of a given entity back out of the database.

When to reach for it. Fetching stored entity records, the read side of write-entity.

kis read-entity \
  --definition entities/faq.yaml \
  --dbpool dbpool.yaml \
  --entity faq

Same connection flags as write-entity, plus --entity to choose which entity to query.

kis db

What it is. Lifecycle management for databases: create, destroy, export, import, update.

When to reach for it. Provisioning or migrating a database the platform uses, or moving a dump between environments.

kis db create  -n mydb -u admin -p secret -i postgres -s init.sql
kis db update  -n mydb -u admin -p secret -i postgres -s migrate.sql
kis db export  -n mydb -u admin -p secret -i postgres -o dump.sql
kis db import  -n mydb -u admin -p secret -i postgres -f dump.sql
kis db destroy -n mydb -u admin -p secret -i postgres

Shared flags: -n/--name, -u/--user, -p/--password, -i/--infra. create/update also take -s/--scripts; export takes -o; import takes -f. Each subcommand has a one-letter alias (c, d, e, i, u).

Caution

kis db destroy is destructive and not undoable, it drops the database. The one-letter alias makes kis db d -n prod … dangerously terse. Double-check -n before you run it, and kis db export first if the data matters.

kis datapipes

What it is. Runs a data-pipeline workflow defined in YAML, a task graph focused on moving and transforming data, with built-in tenant/cluster awareness.

Why it exists. It’s flow specialized for data movement: it auto-loads environment files and carries the tenant/cluster/service identifiers that data jobs need.

When to reach for it. ETL-style jobs and batch data movement. For general automation (not data-shaped), use flow instead.

kis datapipes -f pipeline.yaml -s start -v batch=2026-06 -e env.yaml

Flag	Meaning
-f, --flow	Flow YAML file
-s, --start	Start task
-v, --vars	Variables (key=value)
-e, --env	Env YAML (auto-loads ./env.yaml)
--dotenv	Dotenv file (auto-loads ./.env)
-n, --name	Environment name (default default)
-w, --workers	Worker count (default 1)
-t, --tenantkey	Custom tenant key
--cluster / --datacenter / --sid	Deployment identifiers

Note

Value precedence, highest to lowest: --vars › env.yaml › .env › vars baked into the flow file. If a value looks “wrong,” check whether a higher-precedence source is overriding it.

kis yaml

What it is. Format-preserving YAML editing, read, set, and delete values by path, with atomic writes and optional schema validation.

Why it exists. Editing YAML config from scripts with sed corrupts formatting and is error-prone. kis yaml understands the document structure, writes atomically (the file is either fully updated or left untouched), and is idempotent (a no-op if the value already matches), safe to run in automation.

When to reach for it. Programmatic config edits (CI, deploy scripts, Kong/Gateway configs) where you must not mangle the rest of the file.

How to use it. Paths use a $.a.b[0].c expression syntax.

# Read
kis yaml get --file config.yml --path '$.database.host'
kis yaml get --file kong.yml --path '$.certificates[0].snis[0].name'

# Set (preview with --dry-run, keep a backup with --backup)
kis yaml set --file config.yml --path '$.database.host' --value 'db.example.com'
kis yaml set --file config.yml --path '$.version' --value '1.2.3' --style double
kis yaml set --file kong.yml --path '$.cert' --value-from-file cert.pem --style literal

# Delete
kis yaml delete --file config.yml --path '$.deprecated_setting' --backup

# Validate against a schema (exit 0 = ok, 3 = errors)
kis yaml validate --file config.yml --schema schema.json --all-errors

Useful set/delete flags: --dry-run (print without writing), --backup (timestamped .bak), --audit-log (append an audit trail), --style (auto|plain|single|double|literal|folded), --chomp (block-scalar chomping).

Recommended

Use --dry-run first on anything generated or production-bound, then re-run without it. Add --backup when overwriting a file you can’t easily regenerate.