{
"id": "fn-sys-command",
"dataComponent": "sys",
"heading": {
"title": "command",
"badges": [
"System",
"ASYNC"
]
},
"synopsis": "Runs a shell command asynchronously and immediately returns `Bool(true)`. The result is eventually passed to a callback as a keyed array containing the command's output, error stream, exit code, etc.",
"codeBlocks": [
"// Basic usage:\n\nextend(\"sys\")\n\n// Launch an external command asynchronously.\nsys:command(\"echo 'Hello'\", result => {\n // 'result' is a keyed array.\n // For example: [ command:\"echo 'Hello'\", stdout:\"Hello\\n\", stderr:\"\", exit:0, success:true ]\n\n // Print the type => typically \"keyed_array\".\n sput( type(result) )\n\n // Print the entire keyed array.\n sput(result)\n})\n\n// The interpreter's main loop (or plugin tasks) will keep running\n// until any background tasks complete, so your callback can finish."
],
"notes": [
"sys:command(...) spawns a background thread to run the given command string in your system shell/environment.",
"The second argument is a callback function that receives a keyed array when the command finishes. That array typically has these fields:",
"- `command`: the original command string",
"- `stdout`: a single string of the command's stdout output",
"- `stderr`: a single string of the command's stderr output",
"- `exit`: an integer exit code (0 means success, non-zero means error)",
"- `success`: a boolean true if exit=0, false otherwise",
"You do not have to return anything from your callback function. The `sys:command` call returns `Bool(true)` immediately, while the command runs in the background.",
"If you need to actively poll for how many sys:command tasks remain, call `sys:check_tasks()` repeatedly. In some Lava builds, a built-in event loop runs that automatically waits for tasks to finish before exiting."
]
}