Processes

The process API allows you to spawn processes, capture their output, and wait for them to exit.

Spawning

To spawn a process, create a Command and spawn it.

require("pinnacle.process").command({
    cmd = "alacritty",
}):spawn()
-- Or
require("pinnacle.process").spawn("alacritty")

Commands have the following properties:

Property	Type	Description
Command	String or String[]	The command and its arguments
Shell command	String[]	A shell and arguments that gets prepended to the command above
Envs	Map<String, String>	Environment variables to spawn the command with
Unique	Bool	Causes the command to not spawn if an instance of it is already running
Once	Bool	Causes the command to not spawn it has been spawned at any time during the current session
Pipe std{in,out,err}	Bool	Sets up a pipe so that the config can interact with the process's stdio

Special spawn options

Unique

To prevent multiple instances of a process from spawning, use the unique flag.

require("pinnacle.process").command({
    cmd = "alacritty",
    unique = true,
}):spawn()
-- Or
require("pinnacle.process").spawn_unique("alacritty")

Once

To only spawn a process exactly once, use the once flag. This is useful for startup programs that you close and don't want respawning when reloading the config.

require("pinnacle.process").command({
    cmd = "alacritty",
    once = true,
}):spawn()
-- Or
require("pinnacle.process").spawn_once("alacritty")

With shell

Sometimes you may want to spawn something using a shell, for example to enable piping. Using the shell command feature allows you to do this while also allowing once and unique to only process the actual command (if you pass the shell as the actual command it will trigger once and unique).

require("pinnacle.process").command({
    cmd = "echo hello | cat",
    shell_cmd = { "bash", "-c" },
}):spawn()

Capturing standard IO

To capture the process's standard IO, you must pipe the descriptors you want to capture:

local child = require("pinnacle.process").command({
    cmd = "alacritty",
    pipe_stdin = true,
    pipe_stdout = true,
    pipe_stderr = true,
}):spawn()

If the command spawns successfully and has standard IO, a Child object will be returned with the process's stdin, stdout, and stderr for those that were piped.

You can run a closure on every outputted line from stdout and stderr by calling the appropriate method:

local child = require("pinnacle.process").spawn("alacritty")
if child then
    child:on_line_stdout(function(line)
        print("stdout: " .. line)
    end)
    child:on_line_stderr(function(line)
        print("stderr: " .. line)
    end)
end

Waiting for the process

You can block and wait for the process to exit, additionally capturing its exit code and message.

local child = require("pinnacle.process").spawn("alacritty")
local exit_info = child:wait()