run

run executes .lil workflows with variables, conditions, captured results, nested scripts, previews and packed files through the same lil-terminal command path used interactively. It never invokes an operating-system shell.

AutomationVersion 1.2.4Stable
lil-terminal

Overview

Put recurring maintenance commands in a .lil file. run executes them in order; start with -n to preview.

Automation stays inside lil-terminal

Each executable statement is resolved as a normal lil-terminal command. Dependencies must be installed beforehand, @command is rejected inside workflows, -n previews expanded commands without executing them, and -x is required for privileged non-interactive commands such as php or ses.

Syntax

lil-terminal
run <file.lil|[script]> [-n|-v|-k|-x] · run -p <source.lil> [target.lil]

Reference

run task.lil

execute a plain or packed .lil script

run [md backup | copy public backup/public]

execute an inline script; an unquoted | separates statements

run <script> -n

validate and show expanded commands without executing them

run <script> -v

show complete command output

run <script> -k

continue after failures; the default stops on the first failure

run <script> -x

allow privileged non-interactive commands such as php and ses

run -p <source.lil> [target.lil]

create a checksum-protected packed script

lil <script>

alias for run

plain .lil

UTF-8 text with one statement per line

packed .lil

@LIL1 header with SHA-256 and DEFLATE data

setup.lil

run once after authorization and remove after success

autoload.lil

run once per authorized session

@<command>

automatic installation is interactive-only and is rejected in scripts

#lil file

core-linear script: ordinary terminal commands only; run it by path or with <

run workflow

use run when variables, conditions, nesting, capture or other workflow logic is required

Practical use

If you repeat a maintenance task, save the terminal commands in a .lil text file and execute them with run. They run sequentially through lil-terminal, not through the operating-system shell.

Start with run sandbox/scripts/workflow.lil -n to preview without executing. Remove -n to perform the steps. For a short task, use run [pwd | pwd], where | separates script statements.

Put one statement per line. set saves a variable, capture stores command output, if and else choose a branch, and run calls a child script. The sample if file ${source} checks the file before proceeding.

-v shows every command output. Execution normally stops on the first error; -k continues subsequent steps, but the workflow still reports Stopped when a failure occurred. A preview cannot guarantee later success.

A file beginning with #lil runs as a simple linear sequence directly through Base Core. Full run handles variables, conditions and nested scripts. Minimum is designed for a single file argument. A one-token inline form such as run [pwd] may also work, but multi-command inline scripts and advanced flags require Base.

setup.lil next to lil.php runs after authorization and is removed only after success; autoload.lil runs once per authorized session. -p packs into @LIL1 using SHA-256 and DEFLATE, but **does not encrypt** the script.

Scripts run with PHP process permissions. Interactive actions and @install are blocked; php and ses require explicit -x. Limits: 256 KiB plain text, 384 KiB packed file, 1000 statements, 10 levels and 60 seconds. There is no automatic rollback of completed file changes.

Conditions

The supported conditions are ok, fail, exists, file, dir, empty, eq, ne and command. Prefix a condition with not to invert it.

Packed format

A packed file starts with @LIL1, the original byte length and a SHA-256 checksum. The remaining payload is URL-safe base64 over raw DEFLATE data. Packing is not encryption and is not a security boundary.

Startup files

setup.lil is checked beside lil.php after authorization and is removed only after every statement succeeds. autoload.lil is checked beside lil.php once per session and is not removed.

Automatic installation

The @command convenience belongs to the interactive core, not to the automation language. A .lil script that starts a command with @ is rejected. Install script dependencies explicitly before automation so a workflow never changes its executable module set implicitly.

Safety

Startup files must be regular readable .lil files beside lil.php; symlinks are rejected. Plain content is limited to 256 KiB, packed input to 384 KiB, scripts to 1000 statements, nesting to 10 levels and execution to 60 seconds. Interactive commands are blocked. php and ses require -x.

Core-linear scripts and Run

A file beginning with #lil is intentionally simpler than a Run workflow: every non-comment line is an ordinary terminal command, top-level | separators are executed from left to right, and processing stops after the first failure. Run the file directly by path or with < file.lil. Use run when the script needs variables, conditions, nested scripts, capture, dry-run controls or other workflow features.

A workflow, including all nested scripts, is limited to 1000 non-comment statements. Preview mode (-n) reports Stopped instead of Checked when validation fails; preview never executes commands.

Interactive sandbox preview

Run the prepared examples directly on the page. Their results are prebuilt and shown in the browser; no terminal command is executed on the server.

Execute a plain or packed .lil script

Install and manage

Install the current compatible version. Choose Base for the complete feature set or Minimum for the reduced package; use upgrade to update a module that is already installed.

Base and Minimum are two packages of the same current module release, not separate command versions.

Base package

Install the complete package with local command reference and every published mode.

install run
Minimum package

Install the reduced package. Local reference is omitted; help <cmd> -i opens the current server reference.

install run -m
Exact public version

Install exactly this published version.

install run -v 1.2.4
Check or update

Ask upgrade to check compatibility and replace the installed block only when needed.

upgrade run
Remove module

Remove the extension block while leaving the core and unrelated modules intact.

install run -u

Examples

Examples are copyable command lines, not actions executed by this website. Review paths, permissions and destructive flags before running them on a real project.

Execute a plain or packed .lil script
run sandbox/scripts/workflow.lil
001 + pwd
002 + pwd
Completed: 2
Show complete command output
run sandbox/scripts/workflow.lil -v
001 + pwd
    sandbox
002 + pwd
    sandbox
Completed: 2
Validate and show expanded commands without executing them
run sandbox/scripts/workflow.lil -n
001 · pwd
002 · pwd
Checked: 2
Validate and show expanded commands without executing them
run sandbox/scripts/workflow.lil -n -v
001 · pwd
002 · pwd
Checked: 2
Alias for run
lil sandbox/scripts/workflow.lil
001 + pwd
002 + pwd
Completed: 2

lil is the short alias of run; saved .lil workflows and pasted automation use the same command execution path.

Execute an inline script; an unquoted | separates statements
run [pwd | pwd]
001 + pwd
002 + pwd
Completed: 2
Run · name
run [set name demo | if eq demo demo | pwd | else | stop mismatch | end]
001 + pwd
Completed: 1
Run · file
run [if file sandbox/data/sample.txt | pwd | end]
001 + pwd
Completed: 1
Run · not
run [if not exists sandbox/missing.txt | pwd | end]
001 + pwd
Completed: 1
Run · location
run [capture location pwd | pwd] -v
001 + pwd
    sandbox
002 + pwd
    sandbox
Completed: 2
Use run when variables, conditions, nesting, capture or other workflow logic is required
run sandbox/scripts/nested.lil -v
001 + pwd
    sandbox
002 + pwd
    sandbox
Completed: 2
Execute a plain or packed .lil script
run [upload | pwd]
001 – upload
    Command is not allowed in scripts
Stopped: 1
Continue after failures; the default stops on the first failure
run [upload | pwd] -k
001 – upload
    Command is not allowed in scripts
002 + pwd
Stopped: 2
Run · 14
run [stop maintenance]
Line 001 – maintenance
Stopped: 0
Allow privileged non-interactive commands such as php and ses
run [pwd | php -v]
001 + pwd
002 – php -v
    Command is not allowed in scripts
Stopped: 2
Allow privileged non-interactive commands such as php and ses
run [pwd | php -v] -x -v
001 + pwd
    sandbox
002 + php -v
    PHP 8.4.24
Completed: 2
Allow privileged non-interactive commands such as php and ses
run sandbox/scripts/privileged.lil
001 – php -v
    Command is not allowed in scripts
Stopped: 1
Allow privileged non-interactive commands such as php and ses
run sandbox/scripts/privileged.lil -x -v
001 + php -v
    PHP 8.4.24
Completed: 1
Validate and show expanded commands without executing them
run sandbox/scripts/invalid.lil -n
001 · pwd
Line 003 – Missing end
Stopped: 1
Use run when variables, conditions, nesting, capture or other workflow logic is required
run sandbox/scripts/recursive.lil
Recursive script detected
Stopped: 0
Execute a plain or packed .lil script
run sandbox/scripts/blocked.lil
001 – @install find
    Automatic installation is not allowed in scripts
Stopped: 1
Continue after failures; the default stops on the first failure
run sandbox/scripts/recover.lil -k
001 – upload
    Command is not allowed in scripts
002 + pwd
Stopped: 2
Create a checksum-protected packed script
run -p sandbox/scripts/workflow.lil sandbox/scripts/workflow.export.lil
Packed workflow.lil > sandbox/scripts/workflow.export.lil
182 B > 256 B
Execute a plain or packed .lil script
run sandbox/scripts/workflow.packed.lil
001 + pwd
002 + pwd
Completed: 2
Validate and show expanded commands without executing them
run sandbox/scripts/workflow.packed.lil -n
001 · pwd
002 · pwd
Checked: 2
Execute a plain or packed .lil script
run [@install find]
001 – @install find
    Automatic installation is not allowed in scripts
Stopped: 1
Execute a plain or packed .lil script
run [upload]
001 – upload
    Command is not allowed in scripts
Stopped: 1
Execute a plain or packed .lil script
run sandbox/scripts/missing.lil
Script file not found
Execute a plain or packed .lil script
run sandbox/data/sample.txt
Script must use the .lil extension
Execute a plain or packed .lil script
run sandbox/scripts/workflow.lil -z
Unknown run option: -z
Execute an inline script; an unquoted | separates statements
run [pwd
Inline script is missing ]
Execute a plain or packed .lil script
run
?

File used in this example: sandbox/scripts/demo.lil

The example uses a file or directory from the protected /sandbox/ documentation workspace.

# lil-sandbox workflow
pwd
dir 1 sandbox
echo sandbox/data/sample.txt

Related documentation

How do I keep terminal output across site pages? →Is lil-terminal safe to leave on a production site? →

Current public release

v1.2.42026-11-01

Production refinement

Current stable release of run. run executes `.

# Version history