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'
});