Run your first automation

Goal

A piece of automation running, and its result where you can see it.

When you finish you will have the edit-run loop every other guide here builds on, on both surfaces.

Why bother

The alternative to a direct runner is testing your logic by running the thing that uses it.

Without this	With this
To test a five-line transform you run a whole pipeline	You run the five lines
A syntax error surfaces after a deploy	It surfaces in under a second
The feedback loop is minutes	It is milliseconds

Before you start

The kis CLI. Nothing else — no service, no network.

Step 1 — write it

Flow

hello.yaml:

name: hello
tasks:
  - name: greet
    print:
      message: "hello, {{name}}"

A flow is a list of named nodes. This one has a single node that writes into the run log, and {{name}} reads a run variable.

Script

hello.js:

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

The engine calls main by default, and what it returns is the result. A bare return at file scope is a syntax error — the body must be inside a function:

return { greeting: "hello" };   // SyntaxError: Illegal return statement

Step 2 — run it

Flow

kis flow -f hello.yaml -v name=world

hello, world
execution engine instance Status: completed  Completed Nodes: [greet]

-v sets a run variable. The last line is the part worth reading: the engine reports which nodes completed, which is the record a flow keeps and a script does not.

Script

kis script run hello.js world

>> Script: hello.js executed in 0.62ms

It ran, and it did not tell you what it returned. That is the thing everyone hits first.

Step 3 — see the result

Flow

A flow’s output is whatever its nodes write, plus the completion line. To carry a value between nodes, capture it with setvar and read it back with {{ }}:

name: hello
list: true
tasks:
  - name: whoami
    shell:
      script: whoami
      setvar: user

  - name: greet
    print:
      message: "hello, {{user}}"

Note list: true. A flow is a graph and there is no fall-through — without it, or without next: on each node, only the first node runs and the run still reports completed. See Graphs and sequences.

Script

kis script run hello.js world --debug

Compiled in 405.798µs
Execution time: 445.436µs
Result: {"greeting":"hello, world"}
>> Script: hello.js executed in 1.18ms

--debug is what prints Result:. The default is quiet on purpose, so the command composes in a pipeline where the return value goes onward rather than to your terminal.

The two timings are worth separating: compile is paid once per run here, but is amortised when a flow runs the same script repeatedly. Execution is the number that scales with your data.

The same file, both ways

These are not alternatives you must choose between at the start. A script runs unchanged inside a flow, with the same entry point and the same arguments:

name: hello
list: true
tasks:
  - name: greet
    script:
      language: javascript
      file: ./hello.js
      args: ["world"]
      setvar: out

  - name: show
    print:
      message: "{{out.greeting}}"

hello, world
execution engine instance Status: completed  Completed Nodes: [greet show]

That is the working order most people settle on: prototype as a script because the loop is a second long, then move it into a flow when it needs to run somewhere other than your terminal.

Verify

Surface	You should see
Flow	Your message, then Status: completed naming every node you expected
Script	Your object on the Result: line

If the flow reports completed but ran fewer nodes than you wrote, that is the fall-through trap — add list: true or next:. If the script printed a timing line and nothing else, you omitted --debug.

Adapt it

Change	Flow	Script
Pass values in	-v k=v, or -e file.yaml	positional args, or --vars k=v
Choose what runs	-n <flow-name>, -t <nodes>	--func handler
Longer-running work	let the node run; the flow has no wall clock of its own	--timeout ms, default 5000
See more	-l debug	--debug

Related

• Pass data in and get results out
• Validate before you ship
• Flows and scripts — choosing between them