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

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