process

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

WARNING

These APIs are still open to future evolution. In new major versions, they may change in backwards incompatible ways.

Summary

Entry	Description
Path	A structured, platform-aware file system path.
Pathlike	Anything that can be used as a path: a string, a Path, or raw path data.
ProcessResult	The result of a completed process, including exit code and captured stdout/stderr.
ProcessRunOptions	Options for process.run:
ProcessSystemOptions	Options for process.system:
Signal
SignalHandle	How a child process's standard streams should be handled:
StdioKind
cwd	Returns the current working directory as a Path.
execPath	Returns the path of the currently running lute executable as a Path.
exit	Exits the current process with the given exitcode.
homedir	Returns the current user's home directory as a Path.
onSignal	Registers callback to be called whenever signal is delivered to this process.
pid	Returns the PID of the current process.
run	Runs the program given by args[1] with the remaining entries as arguments.
system	Runs command through the system shell. Returns the process result.

---

Types

Path

A structured, platform-aware file system path.

type Path = pathlib.Path

---

Pathlike

Anything that can be used as a path: a string, a Path, or raw path data.

type Pathlike = pathlib.Pathlike

---

ProcessResult

The result of a completed process, including exit code and captured stdout/stderr.

type ProcessResult = process.ProcessResult

---

ProcessRunOptions

Options for process.run:

• cwd: The working directory for the child process. Defaults to the current working directory.

• stdio: How to handle the child's stdio streams. Defaults to "default".

• env: Environment variables for the child process. If omitted, inherits the parent's environment.

type ProcessRunOptions = process.ProcessRunOptions

---

ProcessSystemOptions

Options for process.system:

• system: The shell executable to use. If omitted, uses the platform default ($SHELL on Unix, %COMSPEC% on Windows).

• cwd: The working directory for the child process. Defaults to the current working directory.

• stdio: How to handle the child's stdio streams. Defaults to "default".

• env: Environment variables for the child process. If omitted, inherits the parent's environment.

type ProcessSystemOptions = process.ProcessSystemOptions

---

Signal

type Signal = process.Signal

---

SignalHandle

How a child process's standard streams should be handled:

• "default": Capture stdout and stderr to pipes, accessible via ProcessResult.

• "inherit": Pass the parent process's stdio streams through to the child.

• "none": Discard the child's stdio streams.

type SignalHandle = process.SignalHandle

---

StdioKind

type StdioKind = process.StdioKind

---

Functions and Properties

process.cwd

Returns the current working directory as a Path.

() -> Path

---

process.execPath

Returns the path of the currently running lute executable as a Path.

() -> Path

---

process.exit

Exits the current process with the given exitcode.

(exitcode: number) -> never

---

process.homedir

Returns the current user's home directory as a Path.

() -> Path

---

process.onSignal

Registers callback to be called whenever signal is delivered to this process.

Suppresses the default OS behavior (e.g. "SIGINT" will no longer terminate the process).

Returns a handle; call handle:close() to deregister.

(signal: Signal, callback: () -> ()) -> SignalHandle

---

process.pid

Returns the PID of the current process.

() -> number

---

process.run

Runs the program given by args[1] with the remaining entries as arguments.

Returns the process result including exit code and any captured output.

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

---

process.system

Runs command through the system shell. Returns the process result.

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

---