Execution

Running commands, containers and code, locally, over SSH, and on Kubernetes. Every parameter with its type, default and description, plus worked examples.

Shell

Execute shell scripts with templating and environment support.

Parameters

Parameter	Type	Required	Default	Description
script	string	Yes	-	Shell script to execute (supports multiline)
shell	string	No	bash	Shell to use (bash, sh, zsh)
workingdir	string	No	./	Working directory for command execution
user	string	No	-	User to run the command as (requires privileges)
env	map	No	-	Environment variables to inject (also available in Liquid templates as {{VAR}})
inheritenv	bool	No	true	Inherit parent process environment
interactive	bool	No	false	Run in interactive mode (-il flag)
history	bool	No	false	Enable shell history recording
fork	bool	No	false	Run in separate process group (survives parent Ctrl+C)
setvar	string	No	-	Variable to store stdout output

Parallel Execution (Map Nodes)

When shell tasks run in parallel via Map nodes, output is automatically buffered per task to prevent interleaving. Each task’s stdout/stderr is captured and flushed as a contiguous block when the command completes. This is handled internally. No configuration is needed.

Examples

Simple Command

name: hello-world
tasks:
  - name: say-hello
    shell: |
      echo "Hello, World!"
      date

With Environment Variables

name: build-project
vars:
  node_env: production
tasks:
  - name: build
    shell:
      script: |
        npm ci
        npm run build
      env:
        NODE_ENV: "{{node_env}}"
        CI: "true"

Capture Output

name: capture-output
list: true
tasks:
  - name: get-hostname
    shell:
      script: hostname
      setvar: server_name

  - name: show-hostname
    print:
      message: "Server: {{server_name}}"

Isolated Environment

Run scripts in an isolated environment without inheriting parent environment variables:

name: isolated-build
tasks:
  - name: clean-build
    shell:
      script: |
        echo "PATH=$PATH"
        echo "BUILD_MODE=$BUILD_MODE"
        ./build.sh
      env:
        PATH: "/usr/bin:/bin"
        BUILD_MODE: "isolated"
      inheritenv: false

With inheritenv: false, only the explicitly defined env variables are available.

Background Process (Fork)

Run a shell process that continues even if the parent is terminated (Ctrl+C):

name: background-daemon
tasks:
  - name: start-daemon
    shell:
      script: |
        nohup ./my-daemon.sh > /tmp/daemon.log 2>&1 &
        echo "Daemon started"
      fork: true

By default (fork: false), shell processes terminate when the parent receives Ctrl+C. Set fork: true for daemon-style processes that should survive parent termination.

Custom Working Directory

Run commands in a specific directory, the task-level workingdir overrides the workflow-level workingdirectory.

name: build-in-dir
list: true
tasks:
  - name: build-frontend
    shell:
      script: |
        npm ci
        npm run build
      workingdir: /app/frontend

  - name: build-backend
    shell:
      script: |
        go build -o server ./cmd/server
      workingdir: /app/backend

Namespace: shell

Local shell execution functions.

Functions

Function	Description
shell.execute()	Execute a shell script
shell.open()	Open a persistent shell session
shell.run()	Run a command in an open session
shell.close()	Close a persistent shell session

Parameters

Parameter	Type	Default	Description
script	string	-	Shell script to execute
shell	string	"bash"	Shell to use
workingDir	string	"./"	Working directory
user	string	-	User to run as
env	map	-	Environment variables (also available in Liquid templates as {{VAR}})
inheritenv	bool	true	Inherit parent environment
interactive	bool	false	Run in interactive mode
history	bool	false	Enable shell history
fork	bool	false	Run in separate process group
templateVars	map	-	Liquid template variables
stream	bool	true	Stream output to stdout/stderr
capture	bool	false	Capture output to return it

Examples

// Simple command (string form)
shell.execute("echo hello")

// With options (map form)
shell.execute({
  script: `
    npm ci
    npm run build
  `,
  env: {
    NODE_ENV: "production",
    CI: "true"
  }
})

// Isolated environment
shell.execute({
  script: "env | wc -l",
  env: { BUILD_MODE: "isolated" },
  inheritenv: false
})

// Capture output
let result = shell.execute({
  script: "hostname",
  capture: true
})
log(result.output)

// Background process
shell.execute({
  script: "nohup ./daemon.sh &",
  fork: true
})

SuperShell

Enhanced shell execution with conditional commands, output extraction, and check expressions.

Aliases: supershell, superbash

Parameters

Parameter	Type	Required	Default	Description
commands	list	Yes	-	List of commands to execute (string or object format)
shell	string	No	bash	Shell to use (bash, sh, zsh)
workingdir	string	No	./	Working directory for command execution
sudo	bool	No	false	Run commands with sudo
onerror	string	No	terminate	Error behavior: terminate, continue
history	bool	No	false	Include command history in output
env	map	No	-	Environment variables to inject (also available in Liquid templates and check expressions as {{VAR}})
inheritenv	bool	No	true	Inherit parent process environment
fork	bool	No	false	Run in separate process group (survives parent Ctrl+C)

Command Object Properties

Property	Type	Description
command	string	The shell command to execute
test	string	Shell test condition (bash [ ]): run only if test succeeds
test!	string	Negated shell test. Run only if test fails
check	string	JavaScript expression (with env object): run only if true
check!	string	Negated JavaScript check. Run only if false
extract	string/map	Extract output to variable(s). String: full output. Map: regex patterns (first capture group if present, otherwise full match)

Condition Types: test vs check

test / test!: Shell test expressions evaluated by bash’s [ ] command:

- command: npm install
  test: -f package.json      # Runs: [ -f package.json ]

Common shell test operators:

• -f file: File exists and is regular file
• -d dir: Directory exists
• -e path: Path exists (file or directory)
• -x file: File is executable
• -s file: File exists and size > 0
• -z str: String is empty
• -n str: String is not empty

check / check!: JavaScript expressions with access to workflow variables via env:

- command: ./deploy.sh
  check: env.environment === 'production' && env.replicas > 2

The env object contains all workflow variables, enabling complex logic, numeric comparisons, and string operations.

When to use which:

• Use test for file/directory checks and simple shell conditions
• Use check for complex logic, numeric comparisons, or accessing nested workflow variables

Examples

Simple Commands

name: supershell-simple
tasks:
  - name: run-commands
    supershell:
      commands:
        - echo "Starting deployment"
        - cd /app && git pull
        - npm install

Conditional Execution with Test

name: supershell-test
tasks:
  - name: conditional-deploy
    supershell:
      commands:
        - command: git pull origin main
          test: -d .git
        - command: npm install
          test: -f package.json
        - command: pip install -r requirements.txt
          test: -f requirements.txt

Negated Test Condition

name: supershell-test-negated
tasks:
  - name: setup-if-missing
    supershell:
      commands:
        - command: git clone https://github.com/user/repo.git
          test!: -d repo
        - command: mkdir -p logs
          test!: -d logs

JavaScript Check Expression

name: supershell-check
vars:
  environment: production
  deploy_enabled: true
tasks:
  - name: conditional-deploy
    supershell:
      commands:
        - command: ./deploy.sh
          check: env.environment === 'production' && env.deploy_enabled === true
        - command: ./notify.sh
          check: env.notify_slack === true

Extract Output to Variables

name: supershell-extract
list: true
tasks:
  - name: get-system-info
    supershell:
      commands:
        - command: hostname
          extract: server_name
        - command: "cat /etc/os-release | grep VERSION_ID"
          extract:
            os_version: 'VERSION_ID="(.+)"'
        - command: free -m | grep Mem
          extract:
            total_memory: 'Mem:\s+(\d+)'
            used_memory: 'Mem:\s+\d+\s+(\d+)'

  - name: show-info
    print:
      message: "Server {{server_name}} running OS {{os_version}} with {{total_memory}}MB RAM"

Continue on Error

name: supershell-continue
tasks:
  - name: cleanup-tasks
    supershell:
      onerror: continue
      commands:
        - rm -f /tmp/cache/*
        - rm -f /tmp/sessions/*
        - rm -f /tmp/logs/*.old

With Environment Variables

name: supershell-env
vars:
  node_env: production
tasks:
  - name: build-with-env
    supershell:
      env:
        NODE_ENV: "{{node_env}}"
        CI: "true"
        BUILD_ID: "12345"
      commands:
        - echo "Building with NODE_ENV=$NODE_ENV"
        - npm ci
        - npm run build

Isolated Environment

name: supershell-isolated
tasks:
  - name: clean-build
    supershell:
      env:
        PATH: "/usr/bin:/bin"
        HOME: "/tmp/build"
      inheritenv: false
      commands:
        - echo "Running in isolated environment"
        - echo "PATH=$PATH"

Background Process (Fork)

Run supershell commands that continue even if the parent process is terminated:

name: supershell-daemon
tasks:
  - name: start-services
    supershell:
      fork: true
      commands:
        - command: nohup ./service-a.sh > /tmp/service-a.log 2>&1 &
        - command: nohup ./service-b.sh > /tmp/service-b.log 2>&1 &
        - echo "Services started in background"

Namespace: supershell

Interactive shell session functions.

Functions

Function	Description
supershell.execute()	Execute a list of commands with conditions and extraction

Parameters

Parameter	Type	Default	Description
commands	array	-	List of commands (string or object)
shell	string	"bash"	Shell to use
workingDir	string	"./"	Working directory
user	string	-	User to run as
sudo	bool	false	Run with sudo
onError	string	"terminate"	Error handling: "terminate" or "continue"
history	bool	false	Enable shell history
env	map	-	Environment variables (also available in Liquid templates and checks)
inheritenv	bool	true	Inherit parent environment
fork	bool	false	Run in separate process group
templateVars	map	-	Liquid template variables

Command Object Properties

Property	Type	Description
command	string	The shell command to execute
test	string	Shell test condition
testNegated	bool	Negate the test condition
check	string	JavaScript check expression
checkNegated	bool	Negate the check expression
extract	string/map	Extract output to variable(s). String: full output. Map: regex (first capture group if present)

Examples

// Simple commands (string array)
supershell.execute({
  commands: [
    "echo 'Starting'",
    "npm install",
    "npm run build"
  ]
})

// With conditions and extraction
supershell.execute({
  commands: [
    { command: "git pull", test: "-d .git" },
    { command: "npm install", test: "-f package.json" },
    { command: "hostname", extract: "server_name" }
  ]
})

// With environment variables
supershell.execute({
  commands: [
    "echo NODE_ENV=$NODE_ENV",
    "npm run build"
  ],
  env: {
    NODE_ENV: "production",
    CI: "true"
  }
})

// Isolated environment
supershell.execute({
  commands: ["env | wc -l"],
  env: { BUILD_MODE: "isolated" },
  inheritenv: false
})

// Continue on error
supershell.execute({
  commands: [
    "rm -f /tmp/cache/*",
    "rm -f /tmp/old-logs/*"
  ],
  onError: "continue"
})

// Result handling
let result = supershell.execute({
  commands: [
    { command: "hostname", extract: "host" },
    { command: "date", extract: "timestamp" }
  ]
})
log(result.extractedVars.host)
log(result.extractedVars.timestamp)

SSH

Remote command execution over SSH.

Parameters

Connection

Parameter	Type	Required	Default	Description
host	string	Yes	-	SSH server (host:port)
username	string	Yes	-	SSH username
commands	string	Yes	-	Commands to execute

Authentication

Parameter	Type	Required	Description
privatekeypath	string	No	Path to private key file
password	string	No	Password for password auth
keypassphrase	string	No	Passphrase for encrypted key
authmethod	string	No	Auth method: key, password, agent

Jump Host

Parameter	Type	Required	Description
jumphost	string	No	Jump host address (host:port)
jumpusername	string	No	Username for jump host
jumpprivatekeypath	string	No	Private key for jump host
jumpkeypassphrase	string	No	Passphrase for jump host key

Options

Parameter	Type	Default	Description
timeout	string	2m	Connection timeout
pty	bool	false	Request pseudo-terminal
agentforwarding	bool	false	Enable SSH agent forwarding
stricthostkeychecking	bool	false	Enable host key verification

Examples

Basic SSH

name: ssh-basic
tasks:
  - name: run-remote
    ssh:
      host: server.example.com:22
      username: deploy
      privatekeypath: ~/.ssh/id_rsa
      commands: |
        cd /app
        git pull origin main
        npm install
        npm run build

Via Jump Host

name: ssh-jump
tasks:
  - name: run-internal
    ssh:
      host: internal-server.private:22
      username: deploy
      privatekeypath: ~/.ssh/id_rsa
      jumphost: bastion.example.com:22
      jumpusername: admin
      jumpprivatekeypath: ~/.ssh/bastion_key
      commands: hostname

With PTY for sudo

name: ssh-sudo
tasks:
  - name: run-sudo
    ssh:
      host: server.example.com:22
      username: deploy
      privatekeypath: ~/.ssh/id_rsa
      pty: true
      commands: |
        sudo apt-get update
        sudo apt-get upgrade -y

Namespace: ssh

SSH remote execution functions.

Functions

Function	Description
ssh.connect()	Establish SSH connection, returns a clientId handle
ssh.execute()	Execute commands on remote host
ssh.upload()	Upload file to remote host (SCP)
ssh.download()	Download file from remote host (SCP)
ssh.close()	Close SSH connection

ssh.connect() returns a clientId handle that ssh.execute() and ssh.close() can reuse. ssh.upload() and ssh.download() always open and close their own connection; pass the connection parameters directly.

Connection Parameters

Accepted by ssh.connect(), and by ssh.execute() / ssh.upload() / ssh.download() when no clientId is supplied.

Parameter	Type	Default	Description
host	string	-	SSH server (host:port)
user	string	-	SSH username
password	string	-	Password for authentication
keyPath	string	-	Path to private key file
keyPassphrase	string	-	Passphrase for encrypted key
authMethod	string	inferred	"key", "password", or "agent"
timeout	int	-	Connection timeout in seconds
strictHostKeyChecking	bool	false	Verify host keys against known_hosts
knownHostsPath	string	-	Path to known_hosts file
agentForwarding	bool	false	Enable SSH agent forwarding

Execute Parameters

Parameter	Type	Default	Description
clientId	string	-	Handle from ssh.connect() (or pass connection params instead)
commands	string	-	Commands to execute
env	map	-	Environment variables
requestPTY	bool	false	Request pseudo-terminal
ptyTerminal	string	-	Terminal type for PTY (e.g. "xterm")
ptyWidth	int	-	Terminal width
ptyHeight	int	-	Terminal height

Upload/Download Parameters

Accepts the connection parameters above, plus:

Parameter	Type	Default	Description
localPath	string	-	Local file path
remotePath	string	-	Remote file path
recursive	bool	false	Recursive transfer
preserveMode	bool	false	Preserve file permissions

Examples

// Connect, run commands, close
let conn = ssh.connect({
  host: "server.example.com:22",
  user: "deploy",
  keyPath: "~/.ssh/id_rsa"
})

if (conn.success) {
  let result = ssh.execute({
    clientId: conn.clientId,
    commands: `
      cd /app
      git pull origin main
      npm install
    `
  })
  log(result)

  ssh.close({ clientId: conn.clientId })
}

// Upload file (opens its own connection)
ssh.upload({
  host: "server.example.com:22",
  user: "deploy",
  keyPath: "~/.ssh/id_rsa",
  localPath: "./dist/app.tar.gz",
  remotePath: "/opt/deploy/app.tar.gz"
})

// Download file (opens its own connection)
ssh.download({
  host: "server.example.com:22",
  user: "deploy",
  keyPath: "~/.ssh/id_rsa",
  localPath: "./backup.sql",
  remotePath: "/var/backups/db.sql"
})

// Execute with PTY for sudo
ssh.execute({
  clientId: conn.clientId,
  commands: "sudo systemctl restart nginx",
  requestPTY: true,
  ptyTerminal: "xterm"
})

Docker (alias: Podman)

Container operations. Single task with an op: discriminator. Shells out to podman by default; the binary path is configurable per call. The same task is registered under both docker: (primary name, more familiar) and podman: (alias): pick whichever fits your workflow.

The argument shapes work against the docker CLI too, set binary: docker if you need it.

Task: docker (or podman)

Common parameters

Field	Type	Required	Default	Description
op	string	No	"build"	build / push / pull / run / login / tag / inspect / rm
binary	string	No	podman	Container CLI path
setvar	string	No	—	Capture the result map into this workflow variable

Returns (every op)

Field	Type	Description
success	bool	Whether the command exited 0
exitCode	int	Process exit code
output	string	Captured stdout
stderr	string	Captured stderr
error	string	Failure message

Verb-specific: imageId (build/pull), removed (rm), data (inspect when no format).

op: build

- name: build-image
  docker:
    op: build
    context: ./services/api
    dockerfile: build/Dockerfile
    tags: ["ghcr.io/example/api:v1.2.3"]
    buildargs:
      VERSION: "1.2.3"
    platforms: ["linux/amd64", "linux/arm64"]
    push: true
    setvar: build

Parameters: context, dockerfile, tags, buildargs, platforms, target, nocache, pull, push, labels, secrets, env, timeout.

op: push / op: pull

- name: push
  docker:
    op: push
    image: "ghcr.io/example/api:v1.2.3"

- name: pull
  docker:
    op: pull
    image: "alpine:3"
    platform: "linux/arm64"

op: run

- name: run-migrations
  docker:
    op: run
    image: "ghcr.io/example/api:v1.2.3"
    rm: true
    env:
      DATABASE_URL: "{{ db_url }}"
    command: ./bin/migrate
    args: ["--apply"]

Parameters: image, name, command, args, env, mounts, ports, network, workdir, user, entrypoint, labels, detach, rm, interactive, tty, hostenv, timeout.

Mounts are an array of maps:

mounts:
  - source: /host/data
    target: /data
    readonly: false
    type: bind         # or "volume" or "tmpfs"

op: login

- name: login
  docker:
    op: login
    registry: ghcr.io
    username: "{{registry_user}}"
    password: "{{registry_token}}"

The password is sent on stdin (--password-stdin): it never appears on the command line.

op: tag

- name: retag
  docker:
    op: tag
    source: "ghcr.io/example/api:dev"
    target: "ghcr.io/example/api:v1.2.3"

op: inspect

- name: inspect
  docker:
    op: inspect
    target: worker-1
    type: container          # optional
    # format: "{{.State.Status}}"   # optional
    setvar: state

Without format, the raw JSON output is parsed and the first object lands under state.data.

op: rm

- name: cleanup
  docker:
    op: rm
    targets: ["worker-1", "worker-2"]
    force: true
    volumes: true

Namespace: docker (alias: podman)

Same operations as separate functions in the docker namespace, with podman registered as an alias pointing at the same functions. See docs/namespaces/docker.md for the full namespace reference.

Quick example:

docker.login({
  registry: "ghcr.io",
  username: registryUser,
  password: registryToken
})

let build = docker.build({
  context: "./api",
  tags: ["ghcr.io/example/api:" + sha],
  push: true
})
log("built " + build.imageId)

Workflows that prefer the podman name can call podman.build(...), it’s the same function.

K8s (alias: Kubectl)

Kubernetes operations via kubectl. Single task with an op: discriminator. The same task is registered under both k8s: (short) and kubectl: (alias, matches the binary name).

Task: k8s (or kubectl)

Common parameters

Field	Type	Required	Default	Description
op	string	No	"apply"	apply / delete / get / exec / rolloutStatus / logs / scale
binary	string	No	kubectl	kubectl binary path
kubeconfig	string	No	—	--kubeconfig
context	string	No	—	--context
namespace	string	No	—	--namespace
timeout	duration	No	—	Wall-clock cap; also fed to --timeout for rolloutStatus
setvar	string	No	—	Capture result map into a workflow variable

Returns (every op)

Field	Type	Description
success	bool	Exit status
exitCode	int	Process exit code
output	string	Captured stdout
stderr	string	Captured stderr
error	string	Failure message

Plus per-op: applied (apply), deleted (delete), data (get when no format set, parsed JSON).

op: apply

- name: apply
  k8s:
    op: apply
    namespace: app
    file: deploy/app.yaml
    serverside: true
    setvar: applied

Provide one of manifest: (inline YAML, piped to stdin), file: (path), or kustomize: (kustomize dir).

op: delete

- name: cleanup
  k8s:
    op: delete
    namespace: tests
    kind: pod
    selector: "owner=integration-tests"
    ignorenotfound: true

Provide one of (kind + name), selector, file, or manifest.

op: get

- name: list-pods
  k8s:
    op: get
    namespace: app
    kind: pod
    selector: app=api
    setvar: api_pods

When format: is unset, the JSON output is parsed and lands under data, an object for a single resource (name: given) or an array for a list.

op: exec

- name: migrate
  k8s:
    op: exec
    namespace: app
    pod: api-7f9b8c4-xyz
    container: api
    command: ./bin/migrate
    args: ["--apply"]

op: rolloutStatus

- name: wait-for-rollout
  k8s:
    op: rolloutStatus
    namespace: app
    kind: deployment       # default; can also be statefulset / daemonset
    name: api
    timeout: 5m

op: logs

- name: tail
  k8s:
    op: logs
    namespace: app
    pod: api-0
    since: 5m
    tail: 200

⚠️ follow: true blocks the workflow indefinitely (until the pod exits). Pair with a timeout: if you use it.

op: scale

- name: scale-up
  k8s:
    op: scale
    namespace: app
    kind: deployment
    name: api
    replicas: 5
    current: 3      # optional precondition

Namespace: k8s (alias: kubectl)

Same seven atoms as separate Script functions: k8s.apply / k8s.delete / k8s.get / k8s.exec / k8s.rolloutStatus / k8s.logs / k8s.scale. The kubectl namespace points at the same functions.

k8s.apply({
  namespace: "app",
  file: "deploy/app.yaml",
  serverSide: true
})

let pods = k8s.get({ namespace: "app", kind: "pod", selector: "app=api" })
log("api pods: " + pods.data.items.length)

k8s.rolloutStatus({
  namespace: "app",
  name: "api",
  timeout: "5m"
})

// Or via the kubectl alias — same function:
kubectl.scale({ namespace: "app", kind: "deployment", name: "api", replicas: 5 })

See docs/namespaces/k8s.md for the full namespace reference.

Python

Execute Python scripts with optional virtual environment and function invocation.

Parameters

Parameter	Type	Required	Default	Description
path	string	Yes	-	Path to Python script
venv	string	No	-	Path to virtual environment
args	list	No	-	Command-line arguments for the script
function.name	string	No	-	Function to call within the script
function.args	list	No	-	Arguments for the function
setvar	string	No	-	Variable to store output
timeout	int	No	300	Execution timeout in seconds

Examples

Basic Script Execution

name: python-basic
tasks:
  - name: run-script
    python:
      path: ./scripts/process.py
      args:
        - --input=/data/file.csv
        - --output=/data/result.json

With Virtual Environment

name: python-venv
tasks:
  - name: run-with-venv
    python:
      path: ./ml/train.py
      venv: ./ml/venv
      args:
        - --epochs=100
        - --batch-size=32
      setvar: training_result

Call Specific Function

name: python-function
tasks:
  - name: call-function
    python:
      path: ./utils/helpers.py
      function:
        name: calculate_metrics
        args:
          - data: "{{input_data}}"
          - threshold: 0.5
      setvar: metrics

Using Template Variables in Args

name: python-template
vars:
  input_file: /data/input.csv
  output_format: json
tasks:
  - name: process-data
    python:
      path: ./scripts/transform.py
      args:
        - input: "{{input_file}}"
        - format: "{{output_format}}"
      timeout: 600
      setvar: transform_result

From a script

There is no python namespace. A script is the scripting layer, so reaching Python from one means running it as a subprocess:

const r = shell.execute({ script: 'python3 ./analyse.py', capture: true });

Use the task form when Python is a step in a flow; use shell.execute when a script genuinely needs to shell out to it.

Mojo

Execute Mojo scripts with optional virtual environment and function invocation. Mojo is a high-performance language compatible with Python.

Parameters

Parameter	Type	Required	Default	Description
path	string	Yes	-	Path to Mojo script (.mojo or .🔥)
venv	string	No	-	Path to virtual environment
args	list	No	-	Command-line arguments for the script
function.name	string	No	-	Function to call within the script
function.args	list	No	-	Arguments for the function
setvar	string	No	-	Variable to store output
timeout	int	No	300	Execution timeout in seconds

Examples

Basic Mojo Script

name: mojo-basic
tasks:
  - name: run-mojo
    mojo:
      path: ./compute/process.mojo
      args:
        - --threads=8
      setvar: result

High-Performance Computing

name: mojo-compute
vars:
  data_path: /data/large-dataset.bin
tasks:
  - name: parallel-process
    mojo:
      path: ./ml/inference.mojo
      args:
        - input: "{{data_path}}"
        - batch: 1024
      timeout: 1800
      setvar: inference_result

From a script

There is no mojo namespace. Run it through shell.execute when a script needs it, or use the task form as a flow step.

Script

Execute code in JavaScript, Lua, Starlark, CEL, expr, Go, or WebAssembly using the Script plugin engine.

Parameters

Parameter	Type	Required	Default	Description
language	string	No	javascript	Language: javascript, javascript-v8, lua, starlark, cel, expr, go, wasm
code	string	Yes*	-	Inline code to execute (*either code or file required)
file	string	Yes*	-	File path to load code from (*either code or file required)
mode	string	No	code	Execution mode: code (execute and optionally store result) or check (fail if result is falsy)
setvar	string	No	-	Variable name to store result (code mode only)
namespaces	string	No	(default set)	Namespaces to enable: all, none, or comma-separated list
timeout	int	No	5000/100	Execution timeout in ms (default: 5000ms for code, 100ms for check)

Supported Languages

Language	Key	Description
JavaScript (Goja)	javascript	Default. Go-native JS interpreter with full namespace support
JavaScript (V8)	javascript-v8	Chrome V8 engine for higher performance
Lua	lua	Lightweight scripting via GopherLua
Starlark	starlark	Python-like language (deterministic, hermetic)
CEL	cel	Common Expression Language for conditions
expr	expr	Simple expression evaluation
Go	go	Go code via Yaegi interpreter
WebAssembly	wasm	WASM module execution

Namespaces

Scripts have access to utility namespaces that provide functions like http.get(), shell.execute(), file.read(), etc. The namespaces parameter controls which are available.

Value	Description
(omitted)	Default safe set: http, file, shell, hash, id, jq, liquid, glob, vars, extract, crypt
all	All registered namespaces including vault, ssh, db, s3, azureblob, acme, etc.
none	Fully sandboxed. No namespaces available
http,shell	Only the specified namespaces (comma-separated)
http,vault	Example: enable vault access alongside HTTP

Security-sensitive namespaces like vault are not in the default set. Enable explicitly via namespaces: "http,vault" or namespaces: "all".

Examples

JavaScript

name: script-js
tasks:
  - name: process-data
    script:
      language: javascript
      code: |
        function main(input) {
          return {
            greeting: "Hello, " + input.name,
            timestamp: Date.now()
          };
        }
      setvar: result

JavaScript with HTTP Namespace

name: script-http
tasks:
  - name: fetch-data
    script:
      language: javascript
      code: |
        function main() {
          let response = http.get({url: "https://api.example.com/data"});
          return response.body;
        }
      setvar: api_data

CEL Expression

name: script-cel
tasks:
  - name: calculate
    script:
      language: cel
      code: input.price * input.quantity
      setvar: total

Check Mode (Validation)

name: script-check
tasks:
  - name: validate-admin
    script:
      mode: check
      language: cel
      code: input.user.role == "admin" || input.user.permissions.contains("write")

Load Code from File

name: script-file
tasks:
  - name: run-transform
    script:
      file: ./scripts/transform.js
      setvar: transformed

Sandboxed Execution (No Namespaces)

name: script-sandboxed
tasks:
  - name: pure-compute
    script:
      language: javascript
      namespaces: none
      code: |
        function main(input) {
          return input.values.reduce((a, b) => a + b, 0);
        }
      setvar: total

Custom Namespace Selection

name: script-limited
tasks:
  - name: fetch-only
    script:
      language: javascript
      namespaces: http,jq
      code: |
        function main() {
          let resp = http.get({url: "https://api.example.com/data"});
          return jq.query(resp.body, ".items[].name");
        }
      setvar: names

Custom Timeout

name: script-long-running
tasks:
  - name: heavy-compute
    script:
      language: javascript
      timeout: 30000
      code: |
        function main() {
          // Long-running computation...
          return result;
        }
      setvar: result

The other direction

This task is how a flow reaches a script, the subject of this whole reference in reverse. There is no namespace for it, because a script calling a script is just a function call.

What matters here is that the two sides share a calling convention. The args: list becomes positional arguments, namespaces: applies the same grant as --namespaces, and the return value lands in setvar, a file developed with kis script run drops into this task unchanged.

See Calling convention and What a script can reach.

HTTP (http:, alias httpclient:)

HTTP client for REST APIs with secure defaults.

Security Defaults

Setting	Default	Description
insecureskipverify	false	TLS certificate verification enabled
mintlsversion	1.2	Minimum TLS 1.2 required
timeout	30s	Request timeout
retryenabled	true	Automatic retries enabled
retrycount	3	Number of retry attempts
SSRF protection	Enabled	Blocks requests to private/internal networks (localhost, 10., 172.16-31., 192.168.*, link-local)

Parameters

Request Configuration

Parameter	Type	Required	Default	Description
url	string	Yes	-	URL to send request to
method	string	No	GET	HTTP method (GET, POST, PUT, PATCH, DELETE)
headers	map	No	-	HTTP headers
payload	string	No	-	Request body (JSON string)

Authentication

Parameter	Type	Required	Default	Description
authtype	string	No	-	Auth type: basic, bearer, apikey, digest
authusername	string	No	-	Username for basic/digest auth
authpassword	string	No	-	Password for basic/digest auth
authtoken	string	No	-	Token for bearer/apikey auth
authheader	string	No	Authorization	Custom header name for API key

TLS/Security

Parameter	Type	Required	Default	Description
insecureskipverify	bool	No	false	Skip TLS verification (not recommended)
mintlsversion	string	No	1.2	Minimum TLS version
cacertpath	string	No	-	Path to CA certificate
clientcertpath	string	No	-	Path to client certificate (mTLS)
clientkeypath	string	No	-	Path to client key (mTLS)

Response Handling

Parameter	Type	Required	Default	Description
setbody	string	No	-	Variable to store response body
setstatuscode	string	No	-	Variable to store status code
sendheaders	map	No	-	Map of variables to response headers
saveresponsepath	string	No	-	File path to save response

File Upload

Parameter	Type	Required	Default	Description
uploadfile	string	No	-	File path to upload
uploadfiles	list	No	-	Multiple file paths to upload

Options

Parameter	Type	Required	Default	Description
timeout	string	No	30s	Request timeout
retryenabled	bool	No	true	Enable retries
retrycount	int	No	3	Number of retries
failonerror	bool	No	true	Fail on HTTP error (4xx/5xx)

Examples

GET Request

name: rest-get
tasks:
  - name: fetch-data
    http:
      url: "https://api.example.com/data"
      setbody: response_data

POST with JSON

name: rest-post
tasks:
  - name: create-user
    http:
      url: "https://api.example.com/users"
      method: POST
      headers:
        Content-Type: application/json
      payload: '{"name": "John", "email": "[email protected]"}'
      setbody: created_user
      setstatuscode: status

Bearer Token Authentication

name: rest-auth
vars:
  api_token: "your-token-here"
tasks:
  - name: fetch-protected
    http:
      url: "https://api.example.com/protected"
      authtype: bearer
      authtoken: "{{api_token}}"
      setbody: response

Download File

name: rest-download
tasks:
  - name: download
    http:
      url: "https://example.com/file.zip"
      saveresponsepath: "/downloads/file.zip"

Namespace: http

HTTP client functions with SSRF protection.

SSRF Protection: All HTTP functions enforce SSRF protection by default. Requests to private/internal networks (localhost, 127.0.0.1, 10., 172.16-31., 192.168., 169.254.) are blocked.

Functions

Function	Description
http.get()	Perform GET request
http.post()	Perform POST request
http.put()	Perform PUT request
http.patch()	Perform PATCH request
http.delete()	Perform DELETE request
http.request()	Custom request with full control
http.download()	Download file to path
http.upload()	Upload file to URL

Common Parameters

Parameter	Type	Default	Description
url	string	-	Request URL (required)
body	any	-	Request body (for POST/PUT/PATCH)
headers	map	-	Request headers
queryParams	map	-	URL query parameters
formData	map	-	Form data for POST
timeout	int	30	Request timeout in seconds
insecureSkipVerify	bool	false	Skip TLS verification

Authentication Parameters

Parameter	Type	Default	Description
authType	string	-	Auth type: basic, bearer, apikey, digest
authUsername	string	-	Username for basic/digest auth
authPassword	string	-	Password for basic/digest auth
authToken	string	-	Token for bearer/apikey auth
authHeader	string	"Authorization"	Custom header for API key

Examples

// Simple GET request
let result = http.get({
    url: "https://api.example.com/data"
})
log(result.body)

// POST with JSON body
let result = http.post({
    url: "https://api.example.com/users",
    body: { name: "John", email: "[email protected]" },
    headers: { "Content-Type": "application/json" }
})
if (result.success) {
    log("Created user:", result.body)
}

// Bearer token authentication
let result = http.get({
    url: "https://api.example.com/protected",
    authType: "bearer",
    authToken: input.token
})

// Download file
http.download({
    url: "https://example.com/file.zip",
    outputPath: "/downloads/file.zip"
})

// Upload file
http.upload({
    url: "https://api.example.com/upload",
    filePath: "/local/file.txt",
    authType: "bearer",
    authToken: input.token
})

// Custom request with full options
let result = http.request({
    method: "PATCH",
    url: "https://api.example.com/items/123",
    body: { status: "active" },
    headers: { "X-Custom-Header": "value" },
    queryParams: { version: "2" },
    authType: "basic",
    authUsername: "user",
    authPassword: "pass",
    timeout: 60,
    followRedirects: true
})