How to create a script

Generate a starter file with omakure init, or write a supported Bash, PowerShell, Python, or Lua script directly. Omakure discovers it from the selected workspace when the file extension and schema markers are valid.

omakure init tools/hello.sh
omakure --json scripts
omakure --json describe tools/hello.sh
omakure --json run tools/hello.sh --no-prompt

Schema

Put a JSON object between OMAKURE_SCHEMA_START and OMAKURE_SCHEMA_END using the comment prefix for the script extension:

# OMAKURE_SCHEMA_START
# {
#   "Name": "hello",
#   "Description": "Print a greeting",
#   "Tags": ["example"],
#   "Fields": [],
#   "Schedule": { "Cron": "@hourly", "Enabled": true }
# }
# OMAKURE_SCHEMA_END

Fields may contain Name, Prompt, Type, Order, Required, Arg, Default, and Choices. Types are string, number, bool/boolean, and secret; secret fields cannot declare choices. Outputs and Queue are optional metadata used by the CLI/HTTP schema projections. Schedule accepts the cron forms documented in scheduling.md.

Use --schema-json '<json>|@file' with init to validate and embed a schema, and --body-stdin to supply the script body. Existing files require --force.

Script contract

Scripts should parse their declared Arg values and remain usable outside Omakure. Do not assume a form UI or a Lua directory widget exists. A script can emit structured progress from an Omakure run:

omakure trace "started" --level info --data '{"target":"prod"}'

The executor supplies OMAKURE_RUN_ID to direct/queued/scheduled child processes. history traces RUN_ID reads those events. Environment files and secret references are described in environments.md and ai-interface.md.

Comment prefixes

.bash/.sh: #
.ps1: # or ;
.py: #
.lua: --

Minimal Bash script

#!/usr/bin/env bash
set -euo pipefail

# OMAKURE_SCHEMA_START
# { "Name": "hello", "Description": "Print a greeting", "Fields": [] }
# OMAKURE_SCHEMA_END

printf 'hello from omakure\n'

Minimal Lua script

.lua needs no interpreter installed. The Lua runtime is embedded in the omakure binary, so the same script runs on a node with nothing on it.

-- OMAKURE_SCHEMA_START
-- { "Name": "hello", "Description": "Print a greeting", "Fields": [] }
-- OMAKURE_SCHEMA_END

print("hello from omakure")

Field values arrive as environment variables and arguments arrive in arg, exactly as they do for the other kinds.

Note that extensionless names resolve .bash, .sh, .ps1, .py, .lua in that order, so omakure run hello picks hello.sh over hello.lua when both exist. Name the file explicitly if you mean the Lua one.

Validate and run it through named, headless commands:

omakure doctor
omakure --json describe hello.sh
omakure --json run hello.sh --actor local --reason smoke
omakure --json history list --limit 5

FilesExpand file tree

how-to-create-a-script.md

Latest commit

History