process

local process = require("@rodeo/process")

Summary

Entry	Description
ProcessHandle	Handle to a process started with `create`. Fields are populated when
ProcessResult	Result returned by `run` and `system`.
ProcessRunOptions	Options accepted by `run`, `system`, and `create`. All fields optional.
StdioKind	How a stdio stream should be wired for a spawned process. `"default"`
args	The command-line arguments passed to this rodeo execution after `--`.
create	Spawns `args` as a child process without waiting. Returns a handle with
cwd	Returns the current working directory.
env	A read-only view of environment variables visible to this execution.
execpath	Returns the path of the running rodeo binary.
exit	Exits the current execution with the given code.
homedir	Returns the user’s home directory.
kill	Terminates a process started with `create`.
platform	Returns the run client’s OS: `"macos"`, `"windows"`, or `"linux"`.
run	Runs `args` (or an existing handle), blocking until completion. Returns
system	Like `run`, but takes a single shell-style command string.

Types

ProcessHandle

Handle to a process started with create. Fields are populated when

the corresponding stdio is "piped"; otherwise nil.

type ProcessHandle = {
  __rodeo_pid: string,
  stdin: stream.StreamHandle?,
  stdout: stream.StreamHandle?,
  stderr: stream.StreamHandle?,
}

ProcessResult

Result returned by run and system.

out and err are the captured stdout and stderr, empty when run waits on a create handle.

type ProcessResult = {
  ok: boolean, -- true when the process exited with status 0
  exitcode: number, -- -1 when the process was terminated by a signal
  out: string,
  err: string,
  signal: number?, -- the signal that terminated the process (Unix)
}

ProcessRunOptions

Options accepted by run, system, and create. All fields optional.

stdio applies to all three streams; per-stream overrides win.

env adds variables to the inherited environment.

input (run and system only) is written to the child’s stdin, which is then closed; without it, a child that reads stdin gets end-of-file.

shell (system only) is the shell that runs the command; the default is sh, or cmd on Windows.

type ProcessRunOptions = {
  cwd: string?,
  stdio: StdioKind?,
  stdin: StdioKind?,
  stdout: StdioKind?,
  stderr: StdioKind?,
  env: { [string]: string }?,
  input: (string | buffer)?,
  shell: string?,
}

StdioKind

How a stdio stream should be wired for a spawned process. "default"

uses the parent’s stream, "piped" captures into a StreamHandle,

"inherit" passes through, "none" discards, "tee" mirrors to both

a capture and the parent’s stream.

type StdioKind = "default" | "piped" | "inherit" | "none" | "tee"

Functions and Properties

process.args

The command-line arguments passed to this rodeo execution after --.

any) :: { string }

process.create

Spawns args as a child process without waiting. Returns a handle with

stdin/stdout/stderr stream handles for live interaction.

(args: { string }, options: ProcessRunOptions?) -> ProcessHandle

process.cwd

Returns the current working directory.

() -> string

process.env

A read-only view of environment variables visible to this execution.

any) :: { [string]: string? }

process.execpath

Returns the path of the running rodeo binary.

() -> string

process.exit

Exits the current execution with the given code.

(code: number) -> ()

process.homedir

Returns the user’s home directory.

() -> string

process.kill

Terminates a process started with create.

(handle: ProcessHandle) -> ()

process.platform

Returns the run client’s OS: "macos", "windows", or "linux".

() -> string

process.run

Runs args (or an existing handle), blocking until completion. Returns

captured stdout/stderr and exit code.

(argsOrHandle: { string } | ProcessHandle, options: ProcessRunOptions?) -> ProcessResult

process.system

Like run, but takes a single shell-style command string.

(command: string, options: ProcessRunOptions?) -> ProcessResult