Command Execution with @effect/platform
Overview
The Command module provides type-safe, testable process execution with automatic resource cleanup. Use this for spawning child processes, running shell commands, capturing output, and managing process lifecycles.
When to use this skill:
- Running shell commands or external programs
- Spawning child processes with controlled stdio
- Capturing command output (string, lines, stream)
- Managing long-running processes with cleanup
- Setting environment variables or working directories
- Piping commands together
Note: This skill covers the Command module for process execution, NOT @effect/cli for building CLI applications.
Import Pattern
import { Command, CommandExecutor } from "@effect/platform"Creating Commands
Basic Command
import { Command } from "@effect/platform"
import { pipe } from "effect"
declare const PROJECT_ROOT: string
// Simple command with arguments
const command = Command.make("echo", "-n", "test")
// With working directory
const commandWithDir = pipe(
Command.make("npm", "install"),
Command.workingDirectory("/path/to/project")
)
// With environment variables
const commandWithEnv = pipe(
Command.make("node", "script.js"),
Command.env({ NODE_ENV: "production", API_KEY: "xyz" })
)
// Control stdio streams
const commandWithStdio = pipe(
Command.make("hardhat", "node"),
Command.stdout("inherit"), // "inherit" | "pipe"
Command.stderr("inherit"),
Command.workingDirectory(PROJECT_ROOT)
)Command Configuration Options
import { Command } from "@effect/platform"
import type { Stream } from "effect"
declare const stream: Stream.Stream<Uint8Array>
declare const stringInput: string
// stdout/stderr modes:
// - "inherit": Pass through to parent process
// - "pipe": Capture for programmatic access
const configuredCommand = pipe(
Command.make("some-command"),
Command.stdout("pipe"), // Capture output
Command.stderr("inherit"), // Show errors in console
Command.stdin(stream), // Pipe stream as stdin
Command.feed(stringInput) // Feed string as stdin
)Executing Commands
Capture as String
import { Command } from "@effect/platform"
import { Effect } from "effect"
const result = Effect.gen(function* () {
const command = Command.make("echo", "-n", "hello")
const output = yield* Command.string(command)
// output: "hello"
return output
})Capture as Lines
import { Command } from "@effect/platform"
import { Effect } from "effect"
const result = Effect.gen(function* () {
const command = Command.make("ls", "-1")
const lines = yield* Command.lines(command)
// lines: string[]
return lines
})Stream Output
import { Command } from "@effect/platform"
import { Effect, Stream, Chunk, Console, pipe } from "effect"
declare const decoder: TextDecoder
const result = Effect.gen(function* () {
const command = Command.make("tail", "-f", "app.log")
// As line stream
const lineStream = Command.streamLines(command)
yield* Stream.runForEach(lineStream, (line) => Console.log(line))
// As byte stream
const byteStream = Command.stream(command)
yield* pipe(
byteStream,
Stream.mapChunks(Chunk.map((bytes) => decoder.decode(bytes))),
Stream.runCollect
)
})Get Exit Code
import { Command } from "@effect/platform"
import { Effect } from "effect"
const result = Effect.gen(function* () {
const command = Command.make("test", "-f", "file.txt")
const exitCode = yield* Command.exitCode(command)
// exitCode: number (0 = success, non-zero = failure)
return exitCode
})Process Management
Start Process with Handle
import { Command, CommandExecutor } from "@effect/platform"
import { Effect, Stream, pipe } from "effect"
declare const PROJECT_ROOT: string
declare function handleOutput(chunk: Uint8Array): Effect.Effect<void>
const program = Effect.gen(function* () {
// Get the executor service
const executor = yield* CommandExecutor.CommandExecutor
const command = pipe(
Command.make("bunx", "hardhat", "node"),
Command.workingDirectory(PROJECT_ROOT),
Command.stdout("inherit"),
Command.stderr("inherit")
)
// Start returns a process handle
const process = yield* executor.start(command)
// Check if running
const isRunning = yield* process.isRunning
// Kill the process
yield* process.kill("SIGTERM") // or "SIGKILL", "SIGINT", etc.
// Access streams (when stdout/stderr are "pipe")
yield* Stream.runForEach(process.stdout, handleOutput)
})Automatic Cleanup with Finalizers
import { Command, CommandExecutor } from "@effect/platform"
import { Effect, pipe } from "effect"
declare const PROJECT_ROOT: string
declare const waitForHardhat: Effect.Effect<void>
const startHardhatNode = Effect.gen(function* () {
const executor = yield* CommandExecutor.CommandExecutor
const command = pipe(
Command.make("bunx", "hardhat", "node"),
Command.workingDirectory(PROJECT_ROOT),
Command.stdout("inherit"),
Command.stderr("inherit")
)
const process = yield* executor.start(command)
// Register cleanup - runs when scope closes
yield* Effect.addFinalizer(() =>
process.kill("SIGTERM").pipe(Effect.ignoreLogged)
)
yield* waitForHardhat
yield* Effect.log("Hardhat node ready")
})
// Usage with Scope
const program = pipe(
startHardhatNode,
Effect.scoped // Automatically runs finalizers when scope ends
)Scoped Process Management
import { Command } from "@effect/platform"
import { Effect, pipe } from "effect"
const runWithProcess = Effect.gen(function* () {
const command = Command.make("sleep", "100")
// Process is scoped - automatically killed when scope closes
const process = yield* Command.start(command)
const isRunning = yield* process.isRunning
// isRunning: true
// Do work with process...
// When this Effect completes, process is killed
}).pipe(Effect.scoped)Piping Commands
import { Command } from "@effect/platform"
import { Effect, pipe } from "effect"
const program = Effect.gen(function* () {
// Pipe commands together like shell pipelines
const command = pipe(
Command.make("echo", "2\n1\n3"),
Command.pipeTo(Command.make("sort")),
Command.pipeTo(Command.make("head", "-2"))
)
const lines = yield* Command.lines(command)
// lines: ["1", "2"]
})Error Handling
Commands fail with typed SystemError:
import { Command } from "@effect/platform"
import { Effect, pipe } from "effect"
const program = Effect.gen(function* () {
const command = Command.make("non-existent-command")
const result = yield* Command.string(command).pipe(
Effect.catchTag("SystemError", (error) => {
// error.reason: "NotFound" | "PermissionDenied" | etc
// error.module: "Command"
// error.method: "spawn"
if (error.reason === "NotFound") {
// Fallback to alternative command
return Command.string(Command.make("alternative"))
}
return Effect.fail(error)
})
)
})Complete Example: E2E Test Setup
import { Effect, Schedule, Scope, Exit, pipe } from "effect"
import { Command, CommandExecutor } from "@effect/platform"
import { BunContext } from "@effect/platform-bun"
declare function createPublicClient(config: { transport: unknown }): { getChainId(): Promise<number> }
declare function http(url: string): unknown
const PROJECT_ROOT = new URL("../", import.meta.url).pathname
// Check if service is ready
const checkReady = Effect.tryPromise({
try: async () => {
// Check if Hardhat is responding
const client = createPublicClient({ transport: http("http://127.0.0.1:8545") })
await client.getChainId()
return true
},
catch: () => new Error("Service not ready"),
})
// Wait for service with retries
const waitForReady = pipe(
checkReady,
Effect.retry(
Schedule.recurs(30).pipe(Schedule.addDelay(() => "500 millis"))
),
Effect.timeout("30 seconds"),
Effect.catchAll(() => Effect.fail(new Error("Failed to start")))
)
// Start long-running process
const startService = Effect.gen(function* () {
const executor = yield* CommandExecutor.CommandExecutor
const command = pipe(
Command.make("bunx", "hardhat", "node"),
Command.workingDirectory(PROJECT_ROOT),
Command.stdout("inherit"),
Command.stderr("inherit")
)
const process = yield* executor.start(command)
// Cleanup when scope closes
yield* Effect.addFinalizer(() =>
process.kill("SIGTERM").pipe(Effect.ignoreLogged)
)
yield* waitForReady
yield* Effect.log("Service ready")
})
// Run deployment command
const deploy = Effect.gen(function* () {
const command = Command.make(
"bunx", "hardhat", "ignition", "deploy",
"ignition/modules/MyModule.ts",
"--network", "localhost"
).pipe(Command.workingDirectory(PROJECT_ROOT))
const result = yield* Command.string(command)
if (result.includes("Error")) {
yield* Effect.fail(new Error("Deploy failed"))
}
})
// Setup with scope management
const testScope = Scope.make().pipe(Effect.runSync)
const setupProgram = pipe(
startService,
Effect.flatMap(() => deploy),
Effect.provide(BunContext.layer),
Scope.extend(testScope)
)
const teardownProgram = pipe(
Effect.gen(function* () {
yield* Effect.log("Cleaning up...")
yield* Scope.close(testScope, Exit.void)
}),
Effect.provide(BunContext.layer)
)
// Vitest global setup
export async function setup() {
await Effect.runPromise(setupProgram)
}
export async function teardown() {
await Effect.runPromise(teardownProgram)
}Key Patterns
1. Always Use CommandExecutor for Process Handles
import { CommandExecutor } from "@effect/platform"
declare const command: Command.Command
// Get the executor service first
const executor = yield* CommandExecutor.CommandExecutor
const process = yield* executor.start(command)2. Use Finalizers for Cleanup
import { Effect, pipe } from "effect"
declare const process: { kill(signal: string): Effect.Effect<void> }
// Register cleanup that runs when scope closes
yield* Effect.addFinalizer(() =>
process.kill("SIGTERM").pipe(Effect.ignoreLogged)
)3. Scope Long-Running Processes
import { Command } from "@effect/platform"
import { Effect, pipe } from "effect"
declare const command: Command.Command
// Wrap in Effect.scoped to ensure cleanup
const program = Effect.gen(function* () {
const process = yield* Command.start(command)
// ...
}).pipe(Effect.scoped)4. Control stdio Based on Needs
import { Command } from "@effect/platform"
import { pipe } from "effect"
declare const someCommand: Command.Command
// Inherit for visibility (dev/debug)
const withInherit = pipe(someCommand, Command.stdout("inherit"))
// Pipe for programmatic access
const withPipe = pipe(someCommand, Command.stdout("pipe"))5. Handle Errors with catchTag
import { Command } from "@effect/platform"
import { Effect, pipe } from "effect"
declare const command: Command.Command
const result = yield* Command.string(command).pipe(
Effect.catchTag("SystemError", (error) => {
// Handle specific error reasons
if (error.reason === "NotFound") { /* ... */ return Effect.succeed("") }
if (error.reason === "PermissionDenied") { /* ... */ return Effect.succeed("") }
return Effect.succeed("")
})
)Testing
Commands are testable using Layer.mock:
import { it } from "@effect/vitest"
import { Layer, Effect } from "effect"
import { Command, CommandExecutor } from "@effect/platform"
declare const mockProcess: CommandExecutor.Process
it.effect("runs command", () =>
Effect.gen(function* () {
const output = yield* Command.string(Command.make("echo", "test"))
expect(output).toBe("test")
}).pipe(
Effect.provide(
Layer.succeed(CommandExecutor.CommandExecutor, {
start: () => Effect.succeed(mockProcess)
} as CommandExecutor.CommandExecutor)
)
)
)Common Gotchas
1. Don't Forget to Scope Process Management
import { CommandExecutor } from "@effect/platform"
import { Effect, pipe } from "effect"
declare const executor: CommandExecutor.CommandExecutor
declare const command: Command.Command
// ❌ WRONG - process leaks if program fails
const wrongWay = Effect.gen(function* () {
const process = yield* executor.start(command)
// ...
})
// ✅ CORRECT - cleanup guaranteed
const rightWay = Effect.gen(function* () {
const process = yield* executor.start(command)
yield* Effect.addFinalizer(() => process.kill("SIGTERM").pipe(Effect.ignoreLogged))
// ...
})2. Choose Correct stdio Mode
import { Command } from "@effect/platform"
import { pipe } from "effect"
declare const someCommand: Command.Command
// ❌ WRONG - can't capture output with "inherit"
const wrongCommand = pipe(someCommand, Command.stdout("inherit"))
const wrongOutput = yield* Command.string(wrongCommand) // Empty!
// ✅ CORRECT - use "pipe" to capture
const rightCommand = pipe(someCommand, Command.stdout("pipe"))
const rightOutput = yield* Command.string(rightCommand)3. Use ignoreLogged for Finalizer Errors
import { Effect, pipe } from "effect"
declare const process: { kill(signal: string): Effect.Effect<void> }
// ❌ WRONG - finalizer errors can mask original errors
yield* Effect.addFinalizer(() => process.kill("SIGTERM"))
// ✅ CORRECT - log but don't fail on cleanup errors
yield* Effect.addFinalizer(() => process.kill("SIGTERM").pipe(Effect.ignoreLogged))Related Skills
- platform-abstraction: File I/O, Path, FileSystem services
- effect-testing: Testing Effect programs with @effect/vitest
- error-handling: Typed error handling patterns with catchTag