Scripts

A script is automation written as a function. You call it, it computes, it returns a value.

function main(name) {
  return { greeting: `hello, ${name}` };
}

kis script run greet.js world

The same file runs inside a flow’s script: task, unchanged — same entry point, same arguments, same result. That is the point of the CLI: a fast edit-run loop while you are working, then the finished thing moves into automation without a rewrite.

The shape

One entry point. The default is main; --func picks another. A bare return at file scope is a syntax error — the body must be inside a function.

Arguments come in two channels. Positional arguments become function arguments; --vars and --env become bare globals. Both are available at once, and they mean different things — see Calling convention.

The return value is the result. In a flow it lands in setvar; at the CLI it is printed with --debug.

Atoms arrive as namespaces. shell.execute(), s3.download(), db.query() — the same operations a flow reaches as tasks. See What a script can reach.

Running one

kis script run report.js                       # call main()
kis script run report.js acme 30               # call main("acme", 30)
kis script run report.js --func summarise 7    # call summarise(7)
kis script run report.js --vars env=staging    # bare global 'env'
kis script run report.js --debug               # print the return value
kis script run report.js --timeout 30000       # 30 seconds instead of 5

Without --debug you see only the timing line. The return value is there — it is just not printed unless you ask, because a script in production is usually returning to a caller rather than to a terminal.

$ kis script run report.js --debug
File: report.js
Language: javascript
Function: main
Timeout: 5000ms

Compiled in 188.159µs
Execution time: 2.773142ms
Result: {"count":14,"total":983040}

The other commands

Command	Use
kis script run	Execute a script
kis script validate	Check that it parses and compiles — no input needed
kis script compile	Test compilation against a specific runtime
kis script bench	Measure execution time over many iterations
kis script rules	Run one script over a directory of JSON files

validate is the one to wire into CI. It needs no arguments and no data, so it catches a syntax error before the script reaches anything that matters. See Commands.

Languages

Seven, chosen by file extension:

Extension	Language
.js	JavaScript
.lua	Lua
.star	Starlark
.go	Go
.expr	expr
.cel	CEL
.wasm	WebAssembly

JavaScript is the default choice and the one most examples use. The rest exist for specific reasons — a sandbox with no ambient authority, an expression that must be provably terminating, a compiled artifact. Choosing a language says when each is worth reaching for.

What is in this section

Page	Covers
Languages	The seven runtimes and when to use each
Calling convention	Entry points, arguments, globals, return values
What a script can reach	Namespaces, the always-present base set, and restricting reach
Commands	run, validate, compile, bench, rules

For the atoms a script can call, see the atom reference. For when a flow is the better tool, see Flows and scripts.