Effect Command Executor

Child Process Execution with Effect v4

Overview

The ChildProcess module provides type-safe, composable process execution with automatic resource cleanup via Scope. Commands are AST values — built first with make and pipeTo, then executed via the ChildProcessSpawner service.

When to use this skill:

• Running shell commands or external programs
• Capturing command output as string, lines, or stream
• Piping commands together (shell pipeline equivalent)
• Streaming output from long-running processes
• Managing process lifecycles with scoped cleanup

Note: This skill covers child process execution, NOT @effect/cli for building CLI applications.

Import Pattern

import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';

Platform layer (Node.js):

import { NodeServices } from '@effect/platform-node';

Creating Commands

Template Literal Form

import { ChildProcess } from 'effect/unstable/process';

// Simple command — parsed by whitespace
const cmd = ChildProcess.make`echo hello world`;

// With interpolation — expressions become separate arguments
const name = 'my-package';
const cmd2 = ChildProcess.make`bun publish ${name}`;

// Array expressions expand to multiple arguments
const files = ['a.ts', 'b.ts', 'c.ts'];
const cmd3 = ChildProcess.make`oxfmt ${files}`;

Options + Template Literal Form

import { ChildProcess } from 'effect/unstable/process';

// Options object returns a tagged template function
const cmd = ChildProcess.make({ cwd: '/tmp' })`ls -la`;

const cmd2 = ChildProcess.make({
	cwd: '/app',
	env: { NODE_ENV: 'production' },
	extendEnv: true
})`node server.js`;

Array Form

import { ChildProcess } from 'effect/unstable/process';

// Explicit command + args array
const cmd = ChildProcess.make('git', ['status'], {
	extendEnv: true,
	stdin: 'ignore'
});

// With options
const cmd2 = ChildProcess.make('bun', ['lint'], {
	env: { FORCE_COLOR: '1' },
	extendEnv: true,
	stdin: 'ignore'
});

// Command only (no args)
const cmd3 = ChildProcess.make('node', {
	cwd: '/app',
	extendEnv: true,
	stdin: 'ignore'
});

Command Options

import { ChildProcess } from 'effect/unstable/process';

const cmd = ChildProcess.make('node', ['script.js'], {
	// Working directory
	cwd: '/path/to/project',

	// Environment variables
	env: { NODE_ENV: 'production', API_KEY: 'xyz' },

	// Merge with process.env (default: false)
	extendEnv: true,

	// Run inside a shell (generally disadvised)
	shell: false,

	// Detach from parent (default: true on non-Windows)
	detached: true,

	// stdio configuration — use 'ignore' for non-interactive commands
	stdin: 'ignore', // "pipe" | "inherit" | "ignore" | Stream
	stdout: 'pipe', // "pipe" | "inherit" | "ignore" | Sink
	stderr: 'pipe', // "pipe" | "inherit" | "ignore" | Sink

	// Kill signal defaults
	killSignal: 'SIGTERM',
	forceKillAfter: '3 seconds',

	// Additional file descriptors
	additionalFds: {
		fd3: { type: 'output' }, // readable by parent
		fd4: { type: 'input' } // writable by parent
	}
});

extendEnv defaults to false. If env is supplied without extendEnv: true, it replaces the inherited child environment rather than merging with it.

The fd3/fd4 names above configure child-process stdio channels. They are unrelated to the FileSystem.File.Descriptor type removed in beta.103; process handles still expose getInputFd(number) and getOutputFd(number) for configured additional descriptors.

Combinators

import { ChildProcess } from 'effect/unstable/process';

// Set cwd (applies to all commands in a pipeline)
const cmd = ChildProcess.make`ls -la`.pipe(ChildProcess.setCwd('/tmp'));

// Set env (applies to all commands in a pipeline)
const cmd2 = ChildProcess.make`node script.js`.pipe(
	ChildProcess.setEnv({ NODE_ENV: 'test' })
);

// Prefix a command (e.g. `time`, `nice`, `sudo`)
const cmd3 = ChildProcess.make`echo foo`.pipe(ChildProcess.prefix`time`);
// executes: time echo foo

Executing Commands

Commands are Effect values: yield* on a command evaluates through its Effectable implementation, calls ChildProcessSpawner.spawn, and returns a ChildProcessHandle. spawner.spawn still requires Scope; helpers such as string, lines, and exitCode manage scope internally.

Get the Spawner Service

import { Effect } from 'effect';
import { ChildProcessSpawner } from 'effect/unstable/process';

const program = Effect.gen(function* () {
	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
	// use spawner.string, spawner.lines, spawner.spawn, etc.
});

Capture as String

import { Effect, String } from 'effect';
import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';

const program = Effect.gen(function* () {
	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
	const version = yield* spawner
		.string(ChildProcess.make('node', ['--version']))
		.pipe(Effect.map(String.trim));
	// version: "v22.0.0"
});

Capture as Lines

import { Effect } from 'effect';
import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';

const program = Effect.gen(function* () {
	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
	const files = yield* spawner.lines(
		ChildProcess.make('git', ['diff', '--name-only', 'main...HEAD'])
	);
	const tsFiles = files.filter((f) => f.endsWith('.ts'));
});

Progressive Output with Side Effects

import { Effect, Stream } from 'effect';
import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';

const program = Effect.gen(function* () {
	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
	let output = '';
	const handle = yield* spawner.spawn(
		ChildProcess.make('bun', ['test'], {
			extendEnv: true,
			stdin: 'ignore'
		})
	);
	yield* Stream.runForEach(Stream.decodeText(handle.all), (chunk) =>
		Effect.sync(() => {
			output += chunk;
		})
	).pipe(Effect.forkScoped);
	const exitCode = yield* handle.exitCode;
	return { output, exitCode };
}).pipe(Effect.scoped);

Use this pattern when you need per-chunk side effects (progress reporting, streaming to UI) during command execution. spawner.string/spawner.lines cannot provide per-chunk callbacks.

Get Exit Code

import { Effect } from 'effect';
import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';

const program = Effect.gen(function* () {
	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
	const exitCode = yield* spawner.exitCode(
		ChildProcess.make('test', ['-f', 'package.json'])
	);
	// exitCode: ExitCode (branded number)
	if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
		yield* Effect.fail(new Error('file not found'));
	}
});

Stream Output (Long-Running Processes)

import { Console, Effect, Stream } from 'effect';
import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';

const program = Effect.gen(function* () {
	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;

	// Stream lines from a command
	yield* spawner
		.streamLines(ChildProcess.make`tail -f /var/log/app.log`)
		.pipe(Stream.runForEach((line) => Console.log(line)));

	// Stream raw string chunks
	yield* spawner
		.streamString(ChildProcess.make`my-program`)
		.pipe(Stream.runForEach((chunk) => Console.log(chunk)));
});

Process Handle (spawn)

Use spawner.spawn when you need the process handle for interactive control, streaming output while running, or checking exit codes.

import { Console, Effect, Stream } from 'effect';
import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';

const program = Effect.gen(function* () {
	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;

	const handle = yield* spawner.spawn(
		ChildProcess.make('bun', ['lint'], {
			env: { FORCE_COLOR: '1' },
			extendEnv: true,
			stdin: 'ignore'
		})
	);

	// Stream combined stdout+stderr while process runs
	yield* handle.all.pipe(
		Stream.decodeText(),
		Stream.splitLines,
		Stream.runForEach((line) => Console.log(`[lint] ${line}`))
	);

	// Wait for exit
	const exitCode = yield* handle.exitCode;
	if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
		yield* Effect.fail(new Error(`lint failed: exit ${exitCode}`));
	}
}).pipe(Effect.scoped); // <-- spawn requires Scope

ChildProcessHandle API

Piping Commands

import { Effect } from 'effect';
import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';

const program = Effect.gen(function* () {
	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;

	// stdout → stdin (default)
	const lines = yield* spawner.lines(
		ChildProcess.make('git', [
			'log',
			'--pretty=format:%s',
			'-n',
			'20'
		]).pipe(ChildProcess.pipeTo(ChildProcess.make('head', ['-n', '5'])))
	);

	// Pipe stderr instead of stdout
	const errors = yield* spawner.lines(
		ChildProcess.make`my-program`.pipe(
			ChildProcess.pipeTo(ChildProcess.make`grep error`, {
				from: 'stderr'
			})
		)
	);

	// Pipe combined stdout+stderr
	const all = yield* spawner.lines(
		ChildProcess.make`my-program`.pipe(
			ChildProcess.pipeTo(ChildProcess.make`tee output.log`, {
				from: 'all'
			})
		)
	);
});

Providing the Platform Layer

ChildProcess commands require a ChildProcessSpawner implementation. In Node.js:

import { NodeServices } from '@effect/platform-node';
import { Effect } from 'effect';

// NodeServices.layer provides: ChildProcessSpawner, Crypto, FileSystem, Path, Stdio, Terminal
const program = Effect.gen(function* () {
	// ...
}).pipe(Effect.scoped, Effect.provide(NodeServices.layer));

Or provide just the spawner:

import { NodeChildProcessSpawner } from '@effect/platform-node';

const program = myEffect.pipe(Effect.provide(NodeChildProcessSpawner.layer));

Complete Example: DevTools Service

import { NodeServices } from '@effect/platform-node';
import {
	Console,
	Effect,
	Layer,
	Schema,
	Context,
	Stream,
	String
} from 'effect';
import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';

class DevToolsError extends Schema.TaggedError<DevToolsError>()(
	'DevToolsError',
	{
		cause: Schema.Defect()
	}
) {}

class DevTools extends Context.Service<
	DevTools,
	{
		readonly nodeVersion: Effect.Effect<string, DevToolsError>;
		readonly recentCommitSubjects: Effect.Effect<
			ReadonlyArray<string>,
			DevToolsError
		>;
		readonly runLintFix: Effect.Effect<void, DevToolsError>;
		changedTypeScriptFiles(
			baseRef: string
		): Effect.Effect<ReadonlyArray<string>, DevToolsError>;
	}
>()('app/DevTools') {
	static readonly layer = Layer.effect(
		DevTools,
		Effect.gen(function* () {
			const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;

			const nodeVersion = spawner
				.string(ChildProcess.make('node', ['--version']))
				.pipe(
					Effect.map(String.trim),
					Effect.mapError((cause) => new DevToolsError({ cause }))
				);

			const changedTypeScriptFiles = Effect.fn(
				'DevTools.changedTypeScriptFiles'
			)(function* (baseRef: string) {
				yield* Effect.annotateCurrentSpan({ baseRef });
				const files = yield* spawner
					.lines(
						ChildProcess.make('git', [
							'diff',
							'--name-only',
							`${baseRef}...HEAD`
						])
					)
					.pipe(
						Effect.mapError((cause) => new DevToolsError({ cause }))
					);
				return files.filter((file) => file.endsWith('.ts'));
			});

			const recentCommitSubjects = spawner
				.lines(
					ChildProcess.make('git', [
						'log',
						'--pretty=format:%s',
						'-n',
						'20'
					]).pipe(
						ChildProcess.pipeTo(
							ChildProcess.make('head', ['-n', '5'])
						)
					)
				)
				.pipe(Effect.mapError((cause) => new DevToolsError({ cause })));

			const runLintFix = Effect.gen(function* () {
				const handle = yield* spawner
					.spawn(
						ChildProcess.make('bun', ['lint'], {
							env: { FORCE_COLOR: '1' },
							extendEnv: true,
							stdin: 'ignore'
						})
					)
					.pipe(
						Effect.mapError((cause) => new DevToolsError({ cause }))
					);

				yield* handle.all.pipe(
					Stream.decodeText(),
					Stream.splitLines,
					Stream.runForEach((line) => Console.log(`[lint] ${line}`)),
					Effect.mapError((cause) => new DevToolsError({ cause }))
				);

				const exitCode = yield* handle.exitCode.pipe(
					Effect.mapError((cause) => new DevToolsError({ cause }))
				);
				if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
					return yield* new DevToolsError({
						cause: new Error(
							`bun lint failed with exit code ${exitCode}`
						)
					});
				}
			}).pipe(Effect.scoped);

			return DevTools.of({
				nodeVersion,
				changedTypeScriptFiles,
				recentCommitSubjects,
				runLintFix
			});
		})
	).pipe(Layer.provide(NodeServices.layer));
}

DO / DON'T

DO: Use Effect.scoped when calling spawner.spawn

// spawn returns a handle that requires Scope for lifecycle management
const program = Effect.gen(function* () {
	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
	const handle = yield* spawner.spawn(ChildProcess.make`my-server`);
	// handle is automatically cleaned up when scope closes
}).pipe(Effect.scoped);

DON'T: Use spawner.spawn without scoping

// Process handle leaks — no scope to manage cleanup
const program = Effect.gen(function* () {
	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
	const handle = yield* spawner.spawn(ChildProcess.make`my-server`);
	// ❌ no Effect.scoped — process may leak
});

DO: Use spawner.string / spawner.lines for simple output capture

// These convenience methods handle scope internally
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
const output = yield* spawner.string(ChildProcess.make`echo hello`);
const lines = yield* spawner.lines(ChildProcess.make`ls -1`);

DON'T: Use spawn + manual stream collection when string/lines suffices

// Unnecessarily complex for simple output capture
const handle = yield* spawner.spawn(ChildProcess.make`echo hello`);
const chunks = yield* Stream.runCollect(handle.stdout);
// ❌ overkill — just use spawner.string

DO: Use Effect.mapError to wrap PlatformError in domain errors

class MyError extends Schema.TaggedError<MyError>()('MyError', {
	cause: Schema.Defect()
}) {}

const result =
	yield*
	spawner
		.string(ChildProcess.make`git status`)
		.pipe(Effect.mapError((cause) => new MyError({ cause })));

DON'T: Let PlatformError leak into your service API

// ❌ exposes platform implementation details to consumers
class MyService extends Context.Service<
	MyService,
	{
		readonly status: Effect.Effect<string, PlatformError.PlatformError>; // ❌
	}
>()('MyService') {}

DO: Check ExitCode with the branded constructor

if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
	yield* Effect.fail(new Error(`command failed: ${exitCode}`));
}

DON'T: Compare exit codes as raw numbers

// ❌ ExitCode is a branded type — direct number comparison may not work as expected
if (exitCode !== 0) {
	/* ... */
}

DO: Use handle.all for interleaved stdout+stderr

yield*
	handle.all.pipe(
		Stream.decodeText(),
		Stream.splitLines,
		Stream.runForEach((line) => Console.log(line))
	);

DON'T: Mix handle.stdout/handle.stderr with handle.all

// ❌ Using stdout/stderr alongside all may cause interleaving issues
yield* Stream.merge(handle.stdout, handle.all).pipe(Stream.runCollect);

Error Handling

Child process operations fail with PlatformError:

import { Effect } from 'effect';
import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';

const program = Effect.gen(function* () {
	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;

	const result = yield* spawner
		.string(ChildProcess.make`non-existent-command`)
		.pipe(
			Effect.catchTag('PlatformError', (error) =>
				Effect.succeed(`fallback: ${error.message}`)
			)
		);
});

Boundary Abort Signals

Prefer Effect interruption as the cancellation signal between your own services. If a host API hands you an AbortSignal, convert it once at the outer boundary instead of threading AbortSignal through unrelated services.

Keep process kill, timeout, and output-drain logic inside the process adapter that owns the ChildProcessHandle.

Bridging External Signals

Use Effect.callback to convert an AbortSignal (or any event-driven API) into an Effect. The cleanup Effect removes the listener, and the already-aborted edge case is handled first:

import { Effect } from 'effect';

const fromAbortSignal = (signal: AbortSignal) =>
	Effect.callback<void>((resume) => {
		if (signal.aborted) return resume(Effect.void);
		const handler = () => resume(Effect.void);
		signal.addEventListener('abort', handler, { once: true });
		return Effect.sync(() => signal.removeEventListener('abort', handler));
	});

Abort / Timeout Multiplexing

Combine Effect.raceAll with discriminated result types to handle exit, abort, and timeout in a single expression:

import { Effect } from 'effect';

const exit =
	yield*
	Effect.raceAll([
		handle.exitCode.pipe(
			Effect.map((code) => ({ kind: 'exit' as const, code }))
		),
		fromAbortSignal(signal).pipe(
			Effect.map(() => ({ kind: 'abort' as const }))
		),
		Effect.sleep(timeout).pipe(
			Effect.map(() => ({ kind: 'timeout' as const }))
		)
	]);
if (exit.kind !== 'exit') {
	yield* handle.kill({ forceKillAfter: '3 seconds' });
}

Related Skills

• effect-platform-abstraction: FileSystem, Path, and other platform services
• effect-testing: Testing Effect programs with @effect/vitest
• effect-error-handling: Typed error handling patterns with catchTag