{
  "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."
  ]
}
