ExecResult

Result type returned by command execution methods

Represents the result of a command execution, including output, exit code, and timing information.

Type Definition

interface ExecResult {
  success: boolean;
  exitCode: number;
  stdout: string;
  stderr: string;
  command: string;
  duration: number;
  timestamp: string;
  sessionId?: string;
}

Properties

success · boolean · required

Whether the command succeeded (exitCode === 0)

exitCode · number · required

Process exit code. 0 indicates success, non-zero indicates failure.

stdout · string · required

Standard output content from the command

stderr · string · required

Standard error content from the command

command · string · required

Command that was executed

duration · number · required

Execution duration in milliseconds

timestamp · string · required

ISO 8601 timestamp when command started

sessionId · string

Session ID if the command was executed in a specific session

Example Usage

import { getSandbox } from '@cloudflare/sandbox';

const sandbox = getSandbox(env.SANDBOX, 'my-sandbox');
const result = await sandbox.exec('ls -la /workspace');

// Check success
if (result.success) {
  console.log('Command succeeded');
  console.log('Output:', result.stdout);
} else {
  console.error('Command failed with exit code:', result.exitCode);
  console.error('Error:', result.stderr);
}

// Access metadata
console.log('Command:', result.command);
console.log('Duration:', result.duration, 'ms');
console.log('Started at:', result.timestamp);

Example: Error Handling

const result = await sandbox.exec('npm install');

if (!result.success) {
  throw new Error(
    `npm install failed (exit code ${result.exitCode}): ${result.stderr}`
  );
}

// Installation succeeded
console.log('Installed packages:', result.stdout);

Example: Performance Monitoring

const result = await sandbox.exec('heavy-computation.sh');

console.log(`Command took ${result.duration}ms`);

if (result.duration > 5000) {
  console.warn('Command took longer than 5 seconds');
}

// Log to monitoring system
await logMetric('command_duration', {
  command: result.command,
  duration: result.duration,
  success: result.success
});

Notes

• success is a convenience property derived from exitCode
• Empty stdout/stderr are represented as empty strings, not null
• Duration includes command execution time only, not parsing or network overhead
• Timestamp is in ISO 8601 format (e.g., “2024-01-15T10:30:00.000Z”)
• Large outputs are fully captured (no truncation)
• Use streaming for real-time output processing

See Also

• exec - Execute commands
• execStream - Stream command output
• Process - Background process type