Skip to content

Command

The @effect/platform/Command module provides a way to create and run commands with the specified process name and an optional list of arguments.

The Command.make function generates a command object, which includes details such as the process name, arguments, and environment.

Example (Defining a Command for Directory Listing)

1
import {
import Command
Command
} from "@effect/platform"
2
3
const
const command: Command.Command
command
=
import Command
Command
.
const make: (command: string, ...args: Array<string>) => Command.Command

Create a command with the specified process name and an optional list of arguments.

make
("ls", "-al")
4
namespace console var console: Console

The `console` module provides a simple debugging console that is similar to the JavaScript console mechanism provided by web browsers. The module exports two specific components: * A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream. * A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstdout) and [`process.stderr`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module. _**Warning**_: The global console object's methods are neither consistently synchronous like the browser APIs they resemble, nor are they consistently asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v22.x/api/process.html#a-note-on-process-io) for more information. Example using the global `console`: ```js console.log('hello world'); // Prints: hello world, to stdout console.log('hello %s', 'world'); // Prints: hello world, to stdout console.error(new Error('Whoops, something bad happened')); // Prints error message and stack trace to stderr: // Error: Whoops, something bad happened // at [eval]:5:15 // at Script.runInThisContext (node:vm:132:18) // at Object.runInThisContext (node:vm:309:38) // at node:internal/process/execution:77:19 // at [eval]-wrapper:6:22 // at evalScript (node:internal/process/execution:76:60) // at node:internal/main/eval_string:23:3 const name = 'Will Robinson'; console.warn(`Danger ${name}! Danger!`); // Prints: Danger Will Robinson! Danger!, to stderr ``` Example using the `Console` class: ```js const out = getStreamSomehow(); const err = getStreamSomehow(); const myConsole = new console.Console(out, err); myConsole.log('hello world'); // Prints: hello world, to out myConsole.log('hello %s', 'world'); // Prints: hello world, to out myConsole.error(new Error('Whoops, something bad happened')); // Prints: [Error: Whoops, something bad happened], to err const name = 'Will Robinson'; myConsole.warn(`Danger ${name}! Danger!`); // Prints: Danger Will Robinson! Danger!, to err ```

console
.
(method) Console.log(message?: any, ...optionalParams: any[]): void

Prints to `stdout` with newline. Multiple arguments can be passed, with the first used as the primary message and all additional used as substitution values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html) (the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args)). ```js const count = 5; console.log('count: %d', count); // Prints: count: 5, to stdout console.log('count:', count); // Prints: count: 5, to stdout ``` See [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args) for more information.

log
(
const command: Command.Command
command
)
5
/*
6
{
7
_id: '@effect/platform/Command',
8
_tag: 'StandardCommand',
9
command: 'ls',
10
args: [ '-al' ],
11
env: {},
12
cwd: { _id: 'Option', _tag: 'None' },
13
shell: false,
14
gid: { _id: 'Option', _tag: 'None' },
15
uid: { _id: 'Option', _tag: 'None' }
16
}
17
*/

This command object does not execute until run by an executor.

You need a CommandExecutor to run the command, which can capture output in various formats such as strings, lines, or streams.

Example (Running a Command and Printing Output)

1
import {
import Command
Command
} from "@effect/platform"
2
import {
import NodeContext
NodeContext
,
import NodeRuntime
NodeRuntime
} from "@effect/platform-node"
3
import {
import Effect
Effect
} from "effect"
4
5
const
const command: Command.Command
command
=
import Command
Command
.
const make: (command: string, ...args: Array<string>) => Command.Command

Create a command with the specified process name and an optional list of arguments.

make
("ls", "-al")
6
7
// The program depends on a CommandExecutor
8
const
const program: Effect.Effect<void, PlatformError, CommandExecutor>
program
=
import Effect
Effect
.
const gen: <YieldWrap<Effect.Effect<string, PlatformError, CommandExecutor>>, void>(f: (resume: Effect.Adapter) => Generator<...>) => Effect.Effect<...> (+1 overload)
gen
(function* () {
9
// Runs the command returning the output as a string
10
const
const output: string
output
= yield*
import Command
Command
.
const string: (command: Command.Command, encoding?: string) => Effect.Effect<string, PlatformError, CommandExecutor> (+1 overload)

Runs the command returning the entire output as a string with the specified encoding. If an encoding is not specified, the encoding will default to `utf-8`.

string
(
const command: Command.Command
command
)
11
namespace console var console: Console

The `console` module provides a simple debugging console that is similar to the JavaScript console mechanism provided by web browsers. The module exports two specific components: * A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream. * A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstdout) and [`process.stderr`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module. _**Warning**_: The global console object's methods are neither consistently synchronous like the browser APIs they resemble, nor are they consistently asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v22.x/api/process.html#a-note-on-process-io) for more information. Example using the global `console`: ```js console.log('hello world'); // Prints: hello world, to stdout console.log('hello %s', 'world'); // Prints: hello world, to stdout console.error(new Error('Whoops, something bad happened')); // Prints error message and stack trace to stderr: // Error: Whoops, something bad happened // at [eval]:5:15 // at Script.runInThisContext (node:vm:132:18) // at Object.runInThisContext (node:vm:309:38) // at node:internal/process/execution:77:19 // at [eval]-wrapper:6:22 // at evalScript (node:internal/process/execution:76:60) // at node:internal/main/eval_string:23:3 const name = 'Will Robinson'; console.warn(`Danger ${name}! Danger!`); // Prints: Danger Will Robinson! Danger!, to stderr ``` Example using the `Console` class: ```js const out = getStreamSomehow(); const err = getStreamSomehow(); const myConsole = new console.Console(out, err); myConsole.log('hello world'); // Prints: hello world, to out myConsole.log('hello %s', 'world'); // Prints: hello world, to out myConsole.error(new Error('Whoops, something bad happened')); // Prints: [Error: Whoops, something bad happened], to err const name = 'Will Robinson'; myConsole.warn(`Danger ${name}! Danger!`); // Prints: Danger Will Robinson! Danger!, to err ```

console
.
(method) Console.log(message?: any, ...optionalParams: any[]): void

Prints to `stdout` with newline. Multiple arguments can be passed, with the first used as the primary message and all additional used as substitution values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html) (the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args)). ```js const count = 5; console.log('count: %d', count); // Prints: count: 5, to stdout console.log('count:', count); // Prints: count: 5, to stdout ``` See [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args) for more information.

log
(
const output: string
output
)
12
})
13
14
// Provide the necessary CommandExecutor
15
import NodeRuntime
NodeRuntime
.
const runMain: RunMain <PlatformError, void>(effect: Effect.Effect<void, PlatformError, never>, options?: { readonly disableErrorReporting?: boolean | undefined; readonly disablePrettyLogger?: boolean | undefined; readonly teardown?: Teardown | undefined; }) => void (+1 overload)
runMain
(
const program: Effect.Effect<void, PlatformError, CommandExecutor>
program
.
(method) Pipeable.pipe<Effect.Effect<void, PlatformError, CommandExecutor>, Effect.Effect<void, PlatformError, never>>(this: Effect.Effect<...>, ab: (_: Effect.Effect<...>) => Effect.Effect<...>): Effect.Effect<...> (+21 overloads)
pipe
(
import Effect
Effect
.
const provide: <NodeContext.NodeContext, never, never>(layer: Layer<NodeContext.NodeContext, never, never>) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<...> (+9 overloads)

Splits the context into two parts, providing one part using the specified layer/context/runtime and leaving the remainder `R0`

provide
(
import NodeContext
NodeContext
.
const layer: Layer<NodeContext.NodeContext, never, never>
layer
)))

You can choose different methods to handle command output:

MethodDescription
stringRuns the command returning the output as a string (with the specified encoding)
linesRuns the command returning the output as an array of lines (with the specified encoding)
streamRuns the command returning the output as a stream of Uint8Array chunks
streamLinesRuns the command returning the output as a stream of lines (with the specified encoding)

If you only need the exit code of a command, use Command.exitCode.

Example (Getting the Exit Code)

1
import {
import Command
Command
} from "@effect/platform"
2
import {
import NodeContext
NodeContext
,
import NodeRuntime
NodeRuntime
} from "@effect/platform-node"
3
import {
import Effect
Effect
} from "effect"
4
5
const
const command: Command.Command
command
=
import Command
Command
.
const make: (command: string, ...args: Array<string>) => Command.Command

Create a command with the specified process name and an optional list of arguments.

make
("ls", "-al")
6
7
const
const program: Effect.Effect<void, PlatformError, CommandExecutor>
program
=
import Effect
Effect
.
const gen: <YieldWrap<Effect.Effect<ExitCode, PlatformError, CommandExecutor>>, void>(f: (resume: Effect.Adapter) => Generator<...>) => Effect.Effect<...> (+1 overload)
gen
(function* () {
8
const
const exitCode: ExitCode
exitCode
= yield*
import Command
Command
.
const exitCode: (self: Command.Command) => Effect.Effect<ExitCode, PlatformError, CommandExecutor>

Returns the exit code of the command after the process has completed execution.

exitCode
(
const command: Command.Command
command
)
9
namespace console var console: Console

The `console` module provides a simple debugging console that is similar to the JavaScript console mechanism provided by web browsers. The module exports two specific components: * A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream. * A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstdout) and [`process.stderr`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module. _**Warning**_: The global console object's methods are neither consistently synchronous like the browser APIs they resemble, nor are they consistently asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v22.x/api/process.html#a-note-on-process-io) for more information. Example using the global `console`: ```js console.log('hello world'); // Prints: hello world, to stdout console.log('hello %s', 'world'); // Prints: hello world, to stdout console.error(new Error('Whoops, something bad happened')); // Prints error message and stack trace to stderr: // Error: Whoops, something bad happened // at [eval]:5:15 // at Script.runInThisContext (node:vm:132:18) // at Object.runInThisContext (node:vm:309:38) // at node:internal/process/execution:77:19 // at [eval]-wrapper:6:22 // at evalScript (node:internal/process/execution:76:60) // at node:internal/main/eval_string:23:3 const name = 'Will Robinson'; console.warn(`Danger ${name}! Danger!`); // Prints: Danger Will Robinson! Danger!, to stderr ``` Example using the `Console` class: ```js const out = getStreamSomehow(); const err = getStreamSomehow(); const myConsole = new console.Console(out, err); myConsole.log('hello world'); // Prints: hello world, to out myConsole.log('hello %s', 'world'); // Prints: hello world, to out myConsole.error(new Error('Whoops, something bad happened')); // Prints: [Error: Whoops, something bad happened], to err const name = 'Will Robinson'; myConsole.warn(`Danger ${name}! Danger!`); // Prints: Danger Will Robinson! Danger!, to err ```

console
.
(method) Console.log(message?: any, ...optionalParams: any[]): void

Prints to `stdout` with newline. Multiple arguments can be passed, with the first used as the primary message and all additional used as substitution values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html) (the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args)). ```js const count = 5; console.log('count: %d', count); // Prints: count: 5, to stdout console.log('count:', count); // Prints: count: 5, to stdout ``` See [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args) for more information.

log
(
const exitCode: ExitCode
exitCode
)
10
})
11
12
import NodeRuntime
NodeRuntime
.
const runMain: RunMain <PlatformError, void>(effect: Effect.Effect<void, PlatformError, never>, options?: { readonly disableErrorReporting?: boolean | undefined; readonly disablePrettyLogger?: boolean | undefined; readonly teardown?: Teardown | undefined; }) => void (+1 overload)
runMain
(
const program: Effect.Effect<void, PlatformError, CommandExecutor>
program
.
(method) Pipeable.pipe<Effect.Effect<void, PlatformError, CommandExecutor>, Effect.Effect<void, PlatformError, never>>(this: Effect.Effect<...>, ab: (_: Effect.Effect<...>) => Effect.Effect<...>): Effect.Effect<...> (+21 overloads)
pipe
(
import Effect
Effect
.
const provide: <NodeContext.NodeContext, never, never>(layer: Layer<NodeContext.NodeContext, never, never>) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<...> (+9 overloads)

Splits the context into two parts, providing one part using the specified layer/context/runtime and leaving the remainder `R0`

provide
(
import NodeContext
NodeContext
.
const layer: Layer<NodeContext.NodeContext, never, never>
layer
)))
13
// Output: 0

You can customize environment variables in a command by using Command.env. This is useful when you need specific variables for the command’s execution.

Example (Setting Environment Variables)

In this example, the command runs in a shell to ensure environment variables are correctly processed.

1
import {
import Command
Command
} from "@effect/platform"
2
import {
import NodeContext
NodeContext
,
import NodeRuntime
NodeRuntime
} from "@effect/platform-node"
3
import {
import Effect
Effect
} from "effect"
4
5
const
const command: Command.Command
command
=
import Command
Command
.
const make: (command: string, ...args: Array<string>) => Command.Command

Create a command with the specified process name and an optional list of arguments.

make
("echo", "-n", "$MY_CUSTOM_VAR").
(method) Pipeable.pipe<Command.Command, Command.Command, Command.Command>(this: Command.Command, ab: (_: Command.Command) => Command.Command, bc: (_: Command.Command) => Command.Command): Command.Command (+21 overloads)
pipe
(
6
import Command
Command
.
const env: (environment: Record<string, string | undefined>) => (self: Command.Command) => Command.Command (+1 overload)

Specify the environment variables that will be used when running this command.

env
({
7
(property) MY_CUSTOM_VAR: string
MY_CUSTOM_VAR
: "Hello, this is a custom environment variable!"
8
}),
9
// Use shell to interpret variables correctly
10
// on Windows and Unix-like systems
11
import Command
Command
.
const runInShell: (shell: string | boolean) => (self: Command.Command) => Command.Command (+1 overload)

Allows for specifying whether or not a `Command` should be run inside a shell.

runInShell
(true)
12
)
13
14
const
const program: Effect.Effect<void, PlatformError, CommandExecutor>
program
=
import Effect
Effect
.
const gen: <YieldWrap<Effect.Effect<string, PlatformError, CommandExecutor>>, void>(f: (resume: Effect.Adapter) => Generator<...>) => Effect.Effect<...> (+1 overload)
gen
(function* () {
15
const
const output: string
output
= yield*
import Command
Command
.
const string: (command: Command.Command, encoding?: string) => Effect.Effect<string, PlatformError, CommandExecutor> (+1 overload)

Runs the command returning the entire output as a string with the specified encoding. If an encoding is not specified, the encoding will default to `utf-8`.

string
(
const command: Command.Command
command
)
16
namespace console var console: Console

The `console` module provides a simple debugging console that is similar to the JavaScript console mechanism provided by web browsers. The module exports two specific components: * A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream. * A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstdout) and [`process.stderr`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module. _**Warning**_: The global console object's methods are neither consistently synchronous like the browser APIs they resemble, nor are they consistently asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v22.x/api/process.html#a-note-on-process-io) for more information. Example using the global `console`: ```js console.log('hello world'); // Prints: hello world, to stdout console.log('hello %s', 'world'); // Prints: hello world, to stdout console.error(new Error('Whoops, something bad happened')); // Prints error message and stack trace to stderr: // Error: Whoops, something bad happened // at [eval]:5:15 // at Script.runInThisContext (node:vm:132:18) // at Object.runInThisContext (node:vm:309:38) // at node:internal/process/execution:77:19 // at [eval]-wrapper:6:22 // at evalScript (node:internal/process/execution:76:60) // at node:internal/main/eval_string:23:3 const name = 'Will Robinson'; console.warn(`Danger ${name}! Danger!`); // Prints: Danger Will Robinson! Danger!, to stderr ``` Example using the `Console` class: ```js const out = getStreamSomehow(); const err = getStreamSomehow(); const myConsole = new console.Console(out, err); myConsole.log('hello world'); // Prints: hello world, to out myConsole.log('hello %s', 'world'); // Prints: hello world, to out myConsole.error(new Error('Whoops, something bad happened')); // Prints: [Error: Whoops, something bad happened], to err const name = 'Will Robinson'; myConsole.warn(`Danger ${name}! Danger!`); // Prints: Danger Will Robinson! Danger!, to err ```

console
.
(method) Console.log(message?: any, ...optionalParams: any[]): void

Prints to `stdout` with newline. Multiple arguments can be passed, with the first used as the primary message and all additional used as substitution values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html) (the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args)). ```js const count = 5; console.log('count: %d', count); // Prints: count: 5, to stdout console.log('count:', count); // Prints: count: 5, to stdout ``` See [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args) for more information.

log
(
const output: string
output
)
17
})
18
19
import NodeRuntime
NodeRuntime
.
const runMain: RunMain <PlatformError, void>(effect: Effect.Effect<void, PlatformError, never>, options?: { readonly disableErrorReporting?: boolean | undefined; readonly disablePrettyLogger?: boolean | undefined; readonly teardown?: Teardown | undefined; }) => void (+1 overload)
runMain
(
const program: Effect.Effect<void, PlatformError, CommandExecutor>
program
.
(method) Pipeable.pipe<Effect.Effect<void, PlatformError, CommandExecutor>, Effect.Effect<void, PlatformError, never>>(this: Effect.Effect<...>, ab: (_: Effect.Effect<...>) => Effect.Effect<...>): Effect.Effect<...> (+21 overloads)
pipe
(
import Effect
Effect
.
const provide: <NodeContext.NodeContext, never, never>(layer: Layer<NodeContext.NodeContext, never, never>) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<...> (+9 overloads)

Splits the context into two parts, providing one part using the specified layer/context/runtime and leaving the remainder `R0`

provide
(
import NodeContext
NodeContext
.
const layer: Layer<NodeContext.NodeContext, never, never>
layer
)))
20
// Output: Hello, this is a custom environment variable!

You can send input directly to a command’s standard input using the Command.feed function.

Example (Sending Input to a Command’s Standard Input)

1
import {
import Command
Command
} from "@effect/platform"
2
import {
import NodeContext
NodeContext
,
import NodeRuntime
NodeRuntime
} from "@effect/platform-node"
3
import {
import Effect
Effect
} from "effect"
4
5
const
const command: Command.Command
command
=
import Command
Command
.
const make: (command: string, ...args: Array<string>) => Command.Command

Create a command with the specified process name and an optional list of arguments.

make
("cat").
(method) Pipeable.pipe<Command.Command, Command.Command>(this: Command.Command, ab: (_: Command.Command) => Command.Command): Command.Command (+21 overloads)
pipe
(
import Command
Command
.
const feed: (input: string) => (self: Command.Command) => Command.Command (+1 overload)

Feed a string to standard input (default encoding of UTF-8).

feed
("Hello"))
6
7
const
const program: Effect.Effect<void, PlatformError, CommandExecutor>
program
=
import Effect
Effect
.
const gen: <YieldWrap<Effect.Effect<string, PlatformError, CommandExecutor>>, void>(f: (resume: Effect.Adapter) => Generator<...>) => Effect.Effect<...> (+1 overload)
gen
(function* () {
8
namespace console var console: Console

The `console` module provides a simple debugging console that is similar to the JavaScript console mechanism provided by web browsers. The module exports two specific components: * A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream. * A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstdout) and [`process.stderr`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module. _**Warning**_: The global console object's methods are neither consistently synchronous like the browser APIs they resemble, nor are they consistently asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v22.x/api/process.html#a-note-on-process-io) for more information. Example using the global `console`: ```js console.log('hello world'); // Prints: hello world, to stdout console.log('hello %s', 'world'); // Prints: hello world, to stdout console.error(new Error('Whoops, something bad happened')); // Prints error message and stack trace to stderr: // Error: Whoops, something bad happened // at [eval]:5:15 // at Script.runInThisContext (node:vm:132:18) // at Object.runInThisContext (node:vm:309:38) // at node:internal/process/execution:77:19 // at [eval]-wrapper:6:22 // at evalScript (node:internal/process/execution:76:60) // at node:internal/main/eval_string:23:3 const name = 'Will Robinson'; console.warn(`Danger ${name}! Danger!`); // Prints: Danger Will Robinson! Danger!, to stderr ``` Example using the `Console` class: ```js const out = getStreamSomehow(); const err = getStreamSomehow(); const myConsole = new console.Console(out, err); myConsole.log('hello world'); // Prints: hello world, to out myConsole.log('hello %s', 'world'); // Prints: hello world, to out myConsole.error(new Error('Whoops, something bad happened')); // Prints: [Error: Whoops, something bad happened], to err const name = 'Will Robinson'; myConsole.warn(`Danger ${name}! Danger!`); // Prints: Danger Will Robinson! Danger!, to err ```

console
.
(method) Console.log(message?: any, ...optionalParams: any[]): void

Prints to `stdout` with newline. Multiple arguments can be passed, with the first used as the primary message and all additional used as substitution values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html) (the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args)). ```js const count = 5; console.log('count: %d', count); // Prints: count: 5, to stdout console.log('count:', count); // Prints: count: 5, to stdout ``` See [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args) for more information.

log
(yield*
import Command
Command
.
const string: (command: Command.Command, encoding?: string) => Effect.Effect<string, PlatformError, CommandExecutor> (+1 overload)

Runs the command returning the entire output as a string with the specified encoding. If an encoding is not specified, the encoding will default to `utf-8`.

string
(
const command: Command.Command
command
))
9
})
10
11
import NodeRuntime
NodeRuntime
.
const runMain: RunMain <PlatformError, void>(effect: Effect.Effect<void, PlatformError, never>, options?: { readonly disableErrorReporting?: boolean | undefined; readonly disablePrettyLogger?: boolean | undefined; readonly teardown?: Teardown | undefined; }) => void (+1 overload)
runMain
(
const program: Effect.Effect<void, PlatformError, CommandExecutor>
program
.
(method) Pipeable.pipe<Effect.Effect<void, PlatformError, CommandExecutor>, Effect.Effect<void, PlatformError, never>>(this: Effect.Effect<...>, ab: (_: Effect.Effect<...>) => Effect.Effect<...>): Effect.Effect<...> (+21 overloads)
pipe
(
import Effect
Effect
.
const provide: <NodeContext.NodeContext, never, never>(layer: Layer<NodeContext.NodeContext, never, never>) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<...> (+9 overloads)

Splits the context into two parts, providing one part using the specified layer/context/runtime and leaving the remainder `R0`

provide
(
import NodeContext
NodeContext
.
const layer: Layer<NodeContext.NodeContext, never, never>
layer
)))
12
// Output: Hello

You can access details about a running process, such as exitCode, stdout, and stderr.

Example (Accessing Exit Code and Streams from a Running Process)

1
import {
import Command
Command
} from "@effect/platform"
2
import {
import NodeContext
NodeContext
,
import NodeRuntime
NodeRuntime
} from "@effect/platform-node"
3
import {
import Effect
Effect
,
import Stream
Stream
,
import String
String
,
(alias) function pipe<A>(a: A): A (+19 overloads) import pipe

Pipes the value of an expression into a pipeline of functions. This is useful in combination with data-last functions as a simulation of methods: ``` as.map(f).filter(g) -> pipe(as, map(f), filter(g)) ```

pipe
} from "effect"
4
5
// Helper function to collect stream output as a string
6
const
const runString: <E, R>(stream: Stream.Stream<Uint8Array, E, R>) => Effect.Effect<string, E, R>
runString
= <
(type parameter) E in <E, R>(stream: Stream.Stream<Uint8Array, E, R>): Effect.Effect<string, E, R>
E
,
(type parameter) R in <E, R>(stream: Stream.Stream<Uint8Array, E, R>): Effect.Effect<string, E, R>
R
>(
7
(parameter) stream: Stream.Stream<Uint8Array, E, R>
stream
:
import Stream
Stream
.
interface Stream<out A, out E = never, out R = never> namespace Stream

A `Stream<A, E, R>` is a description of a program that, when evaluated, may emit zero or more values of type `A`, may fail with errors of type `E`, and uses an context of type `R`. One way to think of `Stream` is as a `Effect` program that could emit multiple values. `Stream` is a purely functional *pull* based stream. Pull based streams offer inherent laziness and backpressure, relieving users of the need to manage buffers between operators. As an optimization, `Stream` does not emit single values, but rather an array of values. This allows the cost of effect evaluation to be amortized. `Stream` forms a monad on its `A` type parameter, and has error management facilities for its `E` type parameter, modeled similarly to `Effect` (with some adjustments for the multiple-valued nature of `Stream`). These aspects allow for rich and expressive composition of streams.

Stream
<
interface Uint8Array

A typed array of 8-bit unsigned integer values. The contents are initialized to 0. If the requested number of bytes could not be allocated an exception is raised.

Uint8Array
,
(type parameter) E in <E, R>(stream: Stream.Stream<Uint8Array, E, R>): Effect.Effect<string, E, R>
E
,
(type parameter) R in <E, R>(stream: Stream.Stream<Uint8Array, E, R>): Effect.Effect<string, E, R>
R
>
8
):
import Effect
Effect
.
interface Effect<out A, out E = never, out R = never> namespace Effect

The `Effect` interface defines a value that lazily describes a workflow or job. The workflow requires some context `R`, and may fail with an error of type `E`, or succeed with a value of type `A`. `Effect` values model resourceful interaction with the outside world, including synchronous, asynchronous, concurrent, and parallel interaction. They use a fiber-based concurrency model, with built-in support for scheduling, fine-grained interruption, structured concurrency, and high scalability. To run an `Effect` value, you need a `Runtime`, which is a type that is capable of executing `Effect` values.

Effect
<string,
(type parameter) E in <E, R>(stream: Stream.Stream<Uint8Array, E, R>): Effect.Effect<string, E, R>
E
,
(type parameter) R in <E, R>(stream: Stream.Stream<Uint8Array, E, R>): Effect.Effect<string, E, R>
R
> =>
9
(parameter) stream: Stream.Stream<Uint8Array, E, R>
stream
.
(method) Pipeable.pipe<Stream.Stream<Uint8Array, E, R>, Stream.Stream<string, E, R>, Effect.Effect<string, E, Exclude<R, Scope>>>(this: Stream.Stream<...>, ab: (_: Stream.Stream<...>) => Stream.Stream<...>, bc: (_: Stream.Stream<...>) => Effect.Effect<...>): Effect.Effect<...> (+21 overloads)
pipe
(
10
import Stream
Stream
.
const decodeText: (encoding?: string | undefined) => <E, R>(self: Stream.Stream<Uint8Array, E, R>) => Stream.Stream<string, E, R> (+1 overload)

Decode Uint8Array chunks into a stream of strings using the specified encoding.

decodeText
(),
11
import Stream
Stream
.
const runFold: <string, string>(s: string, f: (s: string, a: string) => string) => <E, R>(self: Stream.Stream<string, E, R>) => Effect.Effect<string, E, Exclude<R, Scope>> (+1 overload)

Executes a pure fold over the stream of values - reduces all elements in the stream to a value of type `S`.

runFold
(
import String
String
.
const empty: ""

The empty string `""`.

empty
,
import String
String
.
const concat: { <B extends string>(that: B): <A extends string>(self: A) => String.Concat<A, B>; <A extends string, B extends string>(self: A, that: B): String.Concat<A, B>; }

Concatenates two strings at runtime.

concat
)
12
)
13
14
const
const program: Effect.Effect<void, PlatformError, Scope | CommandExecutor>
program
=
import Effect
Effect
.
const gen: <YieldWrap<Effect.Effect<[ExitCode, string, string], PlatformError, Scope | CommandExecutor>>, void>(f: (resume: Effect.Adapter) => Generator<...>) => Effect.Effect<...> (+1 overload)
gen
(function* () {
15
const
const command: Command.Command
command
=
import Command
Command
.
const make: (command: string, ...args: Array<string>) => Command.Command

Create a command with the specified process name and an optional list of arguments.

make
("ls")
16
17
const [
const exitCode: ExitCode
exitCode
,
const stdout: string
stdout
,
const stderr: string
stderr
] = yield*
(alias) pipe<Effect.Effect<Process, PlatformError, Scope | CommandExecutor>, Effect.Effect<[ExitCode, string, string], PlatformError, Scope | CommandExecutor>>(a: Effect.Effect<...>, ab: (a: Effect.Effect<...>) => Effect.Effect<...>): Effect.Effect<...> (+19 overloads) import pipe

Pipes the value of an expression into a pipeline of functions. This is useful in combination with data-last functions as a simulation of methods: ``` as.map(f).filter(g) -> pipe(as, map(f), filter(g)) ```

pipe
(
18
// Start running the command and return a handle to the running process
19
import Command
Command
.
const start: (command: Command.Command) => Effect.Effect<Process, PlatformError, CommandExecutor | Scope>

Start running the command and return a handle to the running process.

start
(
const command: Command.Command
command
),
20
import Effect
Effect
.
const flatMap: <Process, [ExitCode, string, string], PlatformError, never>(f: (a: Process) => Effect.Effect<[ExitCode, string, string], PlatformError, never>) => <E, R>(self: Effect.Effect<...>) => Effect.Effect<...> (+1 overload)

This function is a pipeable operator that maps over an `Effect` value, flattening the result of the mapping function into a new `Effect` value.

flatMap
((
(parameter) process: Process
process
) =>
21
import Effect
Effect
.
const all: <readonly [Effect.Effect<ExitCode, PlatformError, never>, Effect.Effect<string, PlatformError, never>, Effect.Effect<string, PlatformError, never>], { ...; }>(arg: readonly [...], options?: { ...; } | undefined) => Effect.Effect<...>

Runs all the provided effects in sequence respecting the structure provided in input. Supports multiple arguments, a single argument tuple / array or record / struct.

all
(
22
[
23
// Waits for the process to exit and returns
24
// the ExitCode of the command that was run
25
(parameter) process: Process
process
.
(property) Process.exitCode: Effect.Effect<ExitCode, PlatformError, never>

Waits for the process to exit and returns the `ExitCode` of the command that was run.

exitCode
,
26
// The standard output stream of the process
27
const runString: <PlatformError, never>(stream: Stream.Stream<Uint8Array, PlatformError, never>) => Effect.Effect<string, PlatformError, never>
runString
(
(parameter) process: Process
process
.
(property) Process.stdout: Stream.Stream<Uint8Array, PlatformError, never>

The standard output stream of the process.

stdout
),
28
// The standard error stream of the process
29
const runString: <PlatformError, never>(stream: Stream.Stream<Uint8Array, PlatformError, never>) => Effect.Effect<string, PlatformError, never>
runString
(
(parameter) process: Process
process
.
(property) Process.stderr: Stream.Stream<Uint8Array, PlatformError, never>

The standard error stream of the process.

stderr
)
30
],
31
{
(property) concurrency: number
concurrency
: 3 }
32
)
33
)
34
)
35
namespace console var console: Console

The `console` module provides a simple debugging console that is similar to the JavaScript console mechanism provided by web browsers. The module exports two specific components: * A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream. * A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstdout) and [`process.stderr`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module. _**Warning**_: The global console object's methods are neither consistently synchronous like the browser APIs they resemble, nor are they consistently asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v22.x/api/process.html#a-note-on-process-io) for more information. Example using the global `console`: ```js console.log('hello world'); // Prints: hello world, to stdout console.log('hello %s', 'world'); // Prints: hello world, to stdout console.error(new Error('Whoops, something bad happened')); // Prints error message and stack trace to stderr: // Error: Whoops, something bad happened // at [eval]:5:15 // at Script.runInThisContext (node:vm:132:18) // at Object.runInThisContext (node:vm:309:38) // at node:internal/process/execution:77:19 // at [eval]-wrapper:6:22 // at evalScript (node:internal/process/execution:76:60) // at node:internal/main/eval_string:23:3 const name = 'Will Robinson'; console.warn(`Danger ${name}! Danger!`); // Prints: Danger Will Robinson! Danger!, to stderr ``` Example using the `Console` class: ```js const out = getStreamSomehow(); const err = getStreamSomehow(); const myConsole = new console.Console(out, err); myConsole.log('hello world'); // Prints: hello world, to out myConsole.log('hello %s', 'world'); // Prints: hello world, to out myConsole.error(new Error('Whoops, something bad happened')); // Prints: [Error: Whoops, something bad happened], to err const name = 'Will Robinson'; myConsole.warn(`Danger ${name}! Danger!`); // Prints: Danger Will Robinson! Danger!, to err ```

console
.
(method) Console.log(message?: any, ...optionalParams: any[]): void

Prints to `stdout` with newline. Multiple arguments can be passed, with the first used as the primary message and all additional used as substitution values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html) (the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args)). ```js const count = 5; console.log('count: %d', count); // Prints: count: 5, to stdout console.log('count:', count); // Prints: count: 5, to stdout ``` See [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args) for more information.

log
({
(property) exitCode: ExitCode
exitCode
,
(property) stdout: string
stdout
,
(property) stderr: string
stderr
})
36
})
37
38
import NodeRuntime
NodeRuntime
.
const runMain: RunMain <PlatformError, void>(effect: Effect.Effect<void, PlatformError, never>, options?: { readonly disableErrorReporting?: boolean | undefined; readonly disablePrettyLogger?: boolean | undefined; readonly teardown?: Teardown | undefined; }) => void (+1 overload)
runMain
(
39
import Effect
Effect
.
const scoped: <void, PlatformError, Scope | CommandExecutor>(effect: Effect.Effect<void, PlatformError, Scope | CommandExecutor>) => Effect.Effect<...>

Scopes all resources used in this workflow to the lifetime of the workflow, ensuring that their finalizers are run as soon as this workflow completes execution, whether by success, failure, or interruption.

scoped
(
const program: Effect.Effect<void, PlatformError, Scope | CommandExecutor>
program
).
(method) Pipeable.pipe<Effect.Effect<void, PlatformError, CommandExecutor>, Effect.Effect<void, PlatformError, never>>(this: Effect.Effect<...>, ab: (_: Effect.Effect<...>) => Effect.Effect<...>): Effect.Effect<...> (+21 overloads)
pipe
(
import Effect
Effect
.
const provide: <NodeContext.NodeContext, never, never>(layer: Layer<NodeContext.NodeContext, never, never>) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<...> (+9 overloads)

Splits the context into two parts, providing one part using the specified layer/context/runtime and leaving the remainder `R0`

provide
(
import NodeContext
NodeContext
.
const layer: Layer<NodeContext.NodeContext, never, never>
layer
))
40
)

To stream a command’s stdout directly to process.stdout, you can use the following approach:

Example (Streaming Command Output Directly to Standard Output)

1
import {
import Command
Command
} from "@effect/platform"
2
import {
import NodeContext
NodeContext
,
import NodeRuntime
NodeRuntime
} from "@effect/platform-node"
3
import {
import Effect
Effect
} from "effect"
4
5
// Create a command to run `cat` on a file and inherit stdout
6
const
const program: Effect.Effect<ExitCode, PlatformError, CommandExecutor>
program
=
import Command
Command
.
const make: (command: string, ...args: Array<string>) => Command.Command

Create a command with the specified process name and an optional list of arguments.

make
("cat", "./some-file.txt").
(method) Pipeable.pipe<Command.Command, Command.Command, Effect.Effect<ExitCode, PlatformError, CommandExecutor>>(this: Command.Command, ab: (_: Command.Command) => Command.Command, bc: (_: Command.Command) => Effect.Effect<...>): Effect.Effect<...> (+21 overloads)
pipe
(
7
import Command
Command
.
const stdout: (stdout: Command.Command.Output) => (self: Command.Command) => Command.Command (+1 overload)

Specify the standard output stream for a command.

stdout
("inherit"), // Stream stdout to process.stdout
8
import Command
Command
.
const exitCode: (self: Command.Command) => Effect.Effect<ExitCode, PlatformError, CommandExecutor>

Returns the exit code of the command after the process has completed execution.

exitCode
// Get the exit code
9
)
10
11
import NodeRuntime
NodeRuntime
.
const runMain: RunMain <PlatformError, ExitCode>(effect: Effect.Effect<ExitCode, PlatformError, never>, options?: { readonly disableErrorReporting?: boolean | undefined; readonly disablePrettyLogger?: boolean | undefined; readonly teardown?: Teardown | undefined; }) => void (+1 overload)
runMain
(
const program: Effect.Effect<ExitCode, PlatformError, CommandExecutor>
program
.
(method) Pipeable.pipe<Effect.Effect<ExitCode, PlatformError, CommandExecutor>, Effect.Effect<ExitCode, PlatformError, never>>(this: Effect.Effect<...>, ab: (_: Effect.Effect<...>) => Effect.Effect<...>): Effect.Effect<...> (+21 overloads)
pipe
(
import Effect
Effect
.
const provide: <NodeContext.NodeContext, never, never>(layer: Layer<NodeContext.NodeContext, never, never>) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<...> (+9 overloads)

Splits the context into two parts, providing one part using the specified layer/context/runtime and leaving the remainder `R0`

provide
(
import NodeContext
NodeContext
.
const layer: Layer<NodeContext.NodeContext, never, never>
layer
)))