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
Whether the command succeeded (exitCode === 0)
Process exit code. 0 indicates success, non-zero indicates failure.
Standard output content from the command
Standard error content from the command
Command that was executed
Execution duration in milliseconds
ISO 8601 timestamp when command started
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);
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
});
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