Subprocess

Spawn and manage child processes, execute commands, and collect output. Useful for executing external programs from Deno.

Eg Deno.Command

class Deno.ChildProcess

implements AsyncDisposable

The interface for handling a child process returned from Deno.Command.spawn.

Properties

pid: number

readonly

status: Promise<CommandStatus>

readonly

A promise that resolves once the child process has exited, with its exit code and terminating signal (if any). The promise never rejects; if the process is still running the promise is pending. Accessing this property does not, on its own, prevent the Deno process from exiting - see ChildProcess.ref.

stderr: SubprocessReadableStream

readonly

stdin: WritableStream<Uint8Array<ArrayBufferLike>>

readonly

stdout: SubprocessReadableStream

readonly

Methods

[Symbol.asyncDispose](): Promise<void>

kill(signo?: Signal | number): void

Kills the process with given Deno.Signal or numeric signal.

Defaults to SIGTERM if no signal is provided.

output(): Promise<CommandOutput>

Waits for the child to exit completely, returning all its output and status.

ref(): void

Ensure that the status of the child process prevents the Deno process from exiting.

unref(): void

Ensure that the status of the child process does not block the Deno process from exiting.

class Deno.Command

allow-run

Create a child process.

If any stdio options are not set to "piped", accessing the corresponding field on the Command or its CommandOutput will throw a TypeError.

If stdin is set to "piped", the stdin WritableStream needs to be closed manually.

Command acts as a builder. Each call to Command.spawn or Command.output will spawn a new subprocess.

Examples

const command = new Deno.Command(Deno.execPath(), {
  args: [
    "eval",
    "console.log('Hello World')",
  ],
  stdin: "piped",
  stdout: "piped",
});
const child = command.spawn();

// open a file and pipe the subprocess output to it.
child.stdout.pipeTo(
  Deno.openSync("output", { write: true, create: true }).writable,
);

// manually close stdin
child.stdin.close();
const status = await child.status;

const command = new Deno.Command(Deno.execPath(), {
  args: [
    "eval",
    "console.log('hello'); console.error('world')",
  ],
});
const { code, stdout, stderr } = await command.output();
console.assert(code === 0);
console.assert("hello\n" === new TextDecoder().decode(stdout));
console.assert("world\n" === new TextDecoder().decode(stderr));

const command = new Deno.Command(Deno.execPath(), {
  args: [
    "eval",
    "console.log('hello'); console.error('world')",
  ],
});
const { code, stdout, stderr } = command.outputSync();
console.assert(code === 0);
console.assert("hello\n" === new TextDecoder().decode(stdout));
console.assert("world\n" === new TextDecoder().decode(stderr));

Constructors

Command(

command: string | URL,

options?: CommandOptions,
)

new

Methods

output(): Promise<CommandOutput>

Executes the Deno.Command, waiting for it to finish and collecting all of its output.

Will throw an error if stdin: "piped" is set.

If options stdout or stderr are not set to "piped", accessing the corresponding field on Deno.CommandOutput will throw a TypeError.

outputSync(): CommandOutput

Synchronously executes the Deno.Command, waiting for it to finish and collecting all of its output.

Will throw an error if stdin: "piped" is set.

If options stdout or stderr are not set to "piped", accessing the corresponding field on Deno.CommandOutput will throw a TypeError.

spawn(): ChildProcess

Spawns a streamable subprocess, allowing to use the other methods.

function Deno.kill

allow-run

kill(

pid: number,

signo?: Signal | number,
): void

Send a signal to process under given pid. The value and meaning of the signal to the process is operating system and process dependant. Signal provides the most common signals. Default signal is "SIGTERM".

The term kill is adopted from the UNIX-like command line command kill which also signals processes.

If pid is negative, the signal will be sent to the process group identified by pid. An error will be thrown if a negative pid is used on Windows.

const command = new Deno.Command("sleep", { args: ["10000"] });
const child = command.spawn();

Deno.kill(child.pid, "SIGINT");

As a special case, a signal of 0 can be used to test for the existence of a process.

Requires allow-run permission.

Parameters

pid: number

signo: Signal | number

optional

Return Type

void

function Deno.spawn

unstable

allow-run

Overload 1

spawn(

command: string | URL,

options?: CommandOptions,
): ChildProcess

Spawns a new subprocess, returning a Deno.ChildProcess handle.

Examples

const child = Deno.spawn(Deno.execPath(), {
  args: ["eval", "console.log('hello')"],
  stdout: "piped",
});
const output = await child.stdout.text();
console.log(output); // "hello\n"
const status = await child.status;

Parameters

command: string | URL

options: CommandOptions

optional

Return Type

ChildProcess

Overload 2

spawn(

command: string | URL,

args: string[],

options?: Omit<CommandOptions, "args">,
): ChildProcess

Spawns a new subprocess with the given arguments, returning a Deno.ChildProcess handle.

Examples

const child = Deno.spawn(Deno.execPath(), ["eval", "console.log('hello')"], {
  stdout: "piped",
});
const output = await child.stdout.text();
console.log(output); // "hello\n"
const status = await child.status;

Parameters

command: string | URL

args: string[]

options: Omit<CommandOptions, "args">

optional

Return Type

ChildProcess

function Deno.spawnAndWait

unstable

allow-run

Overload 1

spawnAndWait(

command: string | URL,

options?: CommandOptions,
): Promise<CommandOutput>

Spawns a subprocess, waits for it to finish, and returns the output.

Examples

const { code, stdout, stderr } = await Deno.spawnAndWait(Deno.execPath(), {
  args: ["eval", "console.log('hello')"],
});
console.log(new TextDecoder().decode(stdout)); // "hello\n"

Parameters

command: string | URL

options: CommandOptions

optional

Return Type

Promise<CommandOutput>

Overload 2

spawnAndWait(

command: string | URL,

args: string[],

options?: Omit<CommandOptions, "args">,
): Promise<CommandOutput>

Spawns a subprocess with the given arguments, waits for it to finish, and returns the output.

Examples

const { code, stdout } = await Deno.spawnAndWait(
  Deno.execPath(),
  ["eval", "console.log('hello')"],
);
console.log(new TextDecoder().decode(stdout)); // "hello\n"

Parameters

command: string | URL

args: string[]

options: Omit<CommandOptions, "args">

optional

Return Type

Promise<CommandOutput>

function Deno.spawnAndWaitSync

unstable

allow-run

Overload 1

spawnAndWaitSync(

command: string | URL,

options?: CommandOptions,
): CommandOutput

Synchronously spawns a subprocess, waits for it to finish, and returns the output.

Examples

const { code, stdout } = Deno.spawnAndWaitSync(Deno.execPath(), {
  args: ["eval", "console.log('hello')"],
});
console.log(new TextDecoder().decode(stdout)); // "hello\n"

Parameters

command: string | URL

options: CommandOptions

optional

Return Type

CommandOutput

Overload 2

spawnAndWaitSync(

command: string | URL,

args: string[],

options?: Omit<CommandOptions, "args">,
): CommandOutput

Synchronously spawns a subprocess with the given arguments, waits for it to finish, and returns the output.

Examples

const { code, stdout } = Deno.spawnAndWaitSync(
  Deno.execPath(),
  ["eval", "console.log('hello')"],
);
console.log(new TextDecoder().decode(stdout)); // "hello\n"

Parameters

command: string | URL

args: string[]

options: Omit<CommandOptions, "args">

optional

Return Type

CommandOutput

interface Deno.CommandOptions

Options which can be set when calling Deno.Command.

Properties

args: string[]

optional

Arguments to pass to the process.

cwd: string | URL

optional

The working directory of the process.

If not specified, the cwd of the parent process is used.

clearEnv: boolean = false

optional

Clear environmental variables from parent process.

Doesn't guarantee that only env variables are present, as the OS may set environmental variables for processes.

env: Record<string, string>

optional

Environmental variables to pass to the subprocess.

uid: number

optional

Sets the child process’s user ID. This translates to a setuid call in the child process. Failure in the set uid call will cause the spawn to fail.

gid: number

optional

Similar to uid, but sets the group ID of the child process.

signal: AbortSignal

optional

An AbortSignal that allows closing the process using the corresponding AbortController by sending the process a SIGTERM signal.

Not supported in Deno.Command.outputSync.

stdin: 
"piped"
 | "inherit"
 | "null"

optional

How stdin of the spawned process should be handled.

Defaults to "inherit" for output & outputSync, and "inherit" for spawn.

stdout: 
"piped"
 | "inherit"
 | "null"

optional

How stdout of the spawned process should be handled.

Defaults to "piped" for output & outputSync, and "inherit" for spawn.

stderr: 
"piped"
 | "inherit"
 | "null"

optional

How stderr of the spawned process should be handled.

Defaults to "piped" for output & outputSync, and "inherit" for spawn.

windowsRawArguments: boolean = false

optional

Skips quoting and escaping of the arguments on windows. This option is ignored on non-windows platforms.

detached: boolean = false

optional

Whether to detach the spawned process from the current process. This allows the spawned process to continue running after the current process exits.

Note: In order to allow the current process to exit, you need to ensure you call unref() on the child process.

In addition, the stdio streams – if inherited or piped – may keep the current process from exiting until the streams are closed.

interface Deno.CommandOutput

extends CommandStatus

The interface returned from calling Deno.Command.output or Deno.Command.outputSync which represents the result of spawning the child process.

Properties

stdout: Uint8Array<ArrayBuffer>

readonly

The buffered output from the child process' stdout.

stderr: Uint8Array<ArrayBuffer>

readonly

The buffered output from the child process' stderr.

interface Deno.CommandStatus

Properties

success: boolean

If the child process exits with a 0 status code, success will be set to true, otherwise false.

code: number

The exit code of the child process.

signal: Signal | null

The signal associated with the child process.

interface Deno.SubprocessReadableStream

extends ReadableStream<Uint8Array<ArrayBuffer>>

The interface for stdout and stderr streams for child process returned from Deno.Command.spawn.

Methods

arrayBuffer(): Promise<ArrayBuffer>

Reads the stream to completion. It returns a promise that resolves with an ArrayBuffer.

bytes(): Promise<Uint8Array<ArrayBuffer>>

Reads the stream to completion. It returns a promise that resolves with a Uint8Array.

json(): Promise<any>

Reads the stream to completion. It returns a promise that resolves with the result of parsing the body text as JSON.

text(): Promise<string>

Reads the stream to completion. It returns a promise that resolves with a USVString (text).