> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibekit.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# executeCommand

> Run arbitrary shell commands in the sandbox environment.

## Method signature

```typescript theme={"dark"}
public async executeCommand(
  command: string,
  options: {
    timeoutMs?: number;
    background?: boolean;
    branch?: string;
    callbacks?: StreamCallbacks;
  } = {}
): Promise<AgentResponse>
```

## Parameters

| Parameter | Type     | Required | Default | Description                                             |
| --------- | -------- | -------- | ------- | ------------------------------------------------------- |
| `command` | `string` | Yes      | -       | The shell command to execute in the sandbox environment |
| `options` | `object` | No       | `{}`    | Configuration options for command execution             |

### Options Object

| Property     | Type              | Required | Default | Description                                                   |
| ------------ | ----------------- | -------- | ------- | ------------------------------------------------------------- |
| `timeoutMs`  | `number`          | No       | -       | Maximum time in milliseconds to wait for command completion   |
| `background` | `boolean`         | No       | `false` | Whether to run the command in the background (non-blocking)   |
| `branch`     | `string`          | No       | -       | Git branch to checkout or create before executing the command |
| `callbacks`  | `StreamCallbacks` | No       | -       | Streaming callbacks for real-time command output              |

### StreamCallbacks Interface

| Property   | Type                        | Required | Description                                                |
| ---------- | --------------------------- | -------- | ---------------------------------------------------------- |
| `onUpdate` | `(message: string) => void` | No       | Called with streaming updates from command output (stdout) |
| `onError`  | `(error: string) => void`   | No       | Called when errors occur during command execution (stderr) |

## Return value

| Type                     | Description                                            |
| ------------------------ | ------------------------------------------------------ |
| `Promise<AgentResponse>` | Promise that resolves to the command execution results |

### AgentResponse Interface

| Property    | Type     | Description                                                |
| ----------- | -------- | ---------------------------------------------------------- |
| `sandboxId` | `string` | Unique identifier for the sandbox environment              |
| `stdout`    | `string` | Standard output from the command execution                 |
| `stderr`    | `string` | Standard error from the command execution                  |
| `exitCode`  | `number` | Exit code from the command execution (0 indicates success) |

## Examples

### Basic Command Execution

```typescript theme={"dark"}
import { VibeKit } from 'vibekit';

const vibekit = new VibeKit(config);

// Execute a simple command
const result = await vibekit.executeCommand('ls -la');

console.log('Command output:', result.stdout);
console.log('Exit code:', result.exitCode);
```

### Command with Timeout

```typescript theme={"dark"}
// Execute command with a timeout
const result = await vibekit.executeCommand('npm install', {
  timeoutMs: 30000 // 30 seconds timeout
});

if (result.exitCode === 0) {
  console.log('Installation completed successfully');
} else {
  console.log('Installation failed:', result.stderr);
}
```

### Background Command Execution

```typescript theme={"dark"}
// Run a long-running command in the background
const result = await vibekit.executeCommand('npm run dev', {
  background: true
});

console.log('Background process started with sandbox ID:', result.sandboxId);
```

### Streaming Command Output

```typescript theme={"dark"}
// Execute command with streaming output using stdout/stderr events
vibekit.on('stdout', (output) => {
  console.log('Command output:', output);
});

vibekit.on('stderr', (error) => {
  console.error('Command error:', error);
});

const result = await vibekit.executeCommand('npm test');

console.log('Final test result:', result.exitCode === 0 ? 'PASSED' : 'FAILED');
```

### Streaming with Callbacks (Legacy)

```typescript theme={"dark"}
// Execute command with streaming output using callbacks (deprecated approach)
const result = await vibekit.executeCommand('npm test', {
  callbacks: {
    onUpdate: (message) => {
      console.log('Test output:', message);
    },
    onError: (error) => {
      console.error('Test error:', error);
    }
  }
});

console.log('Final test result:', result.exitCode === 0 ? 'PASSED' : 'FAILED');
```

### Command with Branch Switching

```typescript theme={"dark"}
// Execute command on a specific git branch
const result = await vibekit.executeCommand('npm run build', {
  branch: 'feature-new-ui',
  timeoutMs: 60000
});

if (result.exitCode === 0) {
  console.log('Build completed successfully on feature-new-ui branch');
} else {
  console.log('Build failed:', result.stderr);
}
```

### Complex Command with All Options

```typescript theme={"dark"}
// Execute a complex command with multiple options
vibekit.on('stdout', (output) => {
  console.log('pytest:', output);
});

vibekit.on('stderr', (error) => {
  console.error('pytest error:', error);
});

const result = await vibekit.executeCommand('python -m pytest tests/', {
  timeoutMs: 60000,
  background: false,
  branch: 'test-improvements'
});

console.log(`Tests completed with exit code: ${result.exitCode}`);
```

## Error handling

The method throws errors in the following cases:

* **Sandbox not available:** When no active sandbox environment exists
* **Command timeout:** When the command exceeds the specified timeout
* **Invalid command:** When the command syntax is invalid or command not found
* **Permission errors:** When the command requires elevated permissions not available in the sandbox
* **Resource limitations:** When the command exceeds sandbox resource limits

```typescript theme={"dark"}
try {
  const result = await vibekit.executeCommand('sudo rm -rf /', {
    timeoutMs: 5000
  });
} catch (error) {
  if (error.message.includes('timeout')) {
    console.error('Command timed out');
  } else if (error.message.includes('permission')) {
    console.error('Permission denied');
  } else {
    console.error('Command execution failed:', error.message);
  }
}
```

## Security considerations

* Commands are executed within a sandboxed environment for security
* Elevated privileges (sudo) may not be available depending on sandbox configuration
* File system access is limited to the sandbox environment
* Network access may be restricted based on sandbox configuration

## Notes

* **Sandbox Environment:** Commands are executed within the active sandbox environment
* **Working Directory:** Commands execute in the sandbox's default working directory
* **Branch Support:** Automatically switches to the specified branch (creates if it doesn't exist)
* **Environment Variables:** Sandbox environment variables are available to executed commands
* **Resource Limits:** Commands are subject to sandbox CPU, memory, and time limitations
* **Background Execution:** Background commands continue running after the method returns
* **Streaming Support:** Real-time output streaming is available through stdout/stderr events or callbacks
* **Exit Codes:** Standard Unix exit codes apply (0 = success, non-zero = error)
* **Event Handling:** Prefer using `vibekit.on('stdout')` and `vibekit.on('stderr')` over callback options