Atoms

Almost everything a platform does between “something happened” and “something changed” is automation: build a service, restore a backup, move a million rows, call a model and act on the answer. kis.ai treats that as a primitive, not a block. Blocks are capabilities a product switches on; operations are how work gets done, and every block uses them.

An operation is one unit of that work — run a shell command, upload to S3, query a database, sign a certificate, embed a document. The platform registers 121 of them across four libraries, and each one is available in two forms.

Two surfaces, one core

You reach an atom either declaratively, as a task in a flow, or imperatively, as a function in a script:

Flow
Script

name: greet
tasks:
  - name: say-hello
    shell: echo "hello"

kis flow -f greet.yaml

hello

function main() {
  return shell.execute({ script: 'echo "hello"' });
}

kis script run greet.js

hello

These are not two implementations that happen to agree. They are two adapters over one function. The shell atom lives in one place; a flow reaches it through a task adapter and a script reaches it through a namespace adapter. Behaviour, parameters and defaults are shared because the code is shared — see Tasks and functions.

That is why the tabs above appear throughout this section. When you see them, you are looking at one atom described twice, not two features to learn.

Which one do I write?

Neither is the advanced version of the other. They answer different questions.

Write a flow when	Write a script when
The work is a sequence of steps you want to see	The work is one computation with logic in it
Steps run on more than one machine	It all happens in one process
You need retries, resume, or restart-where-it-failed	A failure means run it again
Someone will read the YAML to know what ran	Someone will read the code to know what it computed
Fan-out over a list is the point	Branching and arithmetic are the point
An operator, not the author, will run it	You are iterating on it right now

The honest short version: a flow is a plan, a script is a calculation. A flow that has grown a long chain of conditionals wants to be a script. A script that shells out five times in sequence and needs each step to be resumable wants to be a flow.

They compose, so the choice is not final. A flow runs a script with the script: task, and a script that outgrows its shell becomes a flow without being rewritten — the calling convention is the same on both sides.

The engines

Two engines execute what you write.

	Flows	Scripts
CLI	`kis flow`	`kis script`
You write	YAML	JavaScript, Lua, Starlark, Go, expr, CEL, or WebAssembly
Unit of work	a node in a graph	a function call
Atoms arrive as	tasks — `shell:`, `s3:`, `db:`	namespaces — `shell.execute()`, `s3.upload()`
State	persisted per run; resumable	in-memory; one shot
Concurrency	workers, fan-out nodes	whatever the language gives you
Reference	Flows	Scripts

Four flow engines are built on the same core, each with its own task set: Automate, AI Flow, Workflows and Datapipes. They differ in which atoms they expose, not in how they run. See Flow engines.

Where the atoms come from

Atoms are grouped into libraries, and each engine binds its own set. This is the part that surprises people, so it is worth stating plainly: not every engine sees every atom.

Engine	Atoms available
`kis flow` / Automate	The common library, plus infrastructure operations
AI Flow	The common library, plus AI and streaming operations
Workflows	The common library
Datapipes	Pipeline operations only — the common library is not bound
`kis script`	Every namespace registered in the process

A shell: task works in an Automate flow and does not exist in a Datapipe. That is deliberate — a data pipeline moves records and is not a place to run shell commands — but it is the kind of thing you would otherwise discover from an error message. Libraries has the full mapping.

Atoms

Two surfaces, one core

Which one do I write?

The engines

Where the atoms come from

Read next