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

# exec()

> Execute shell or PowerShell commands in the sandbox

## Overview

Execute shell commands (Linux) or PowerShell commands (Windows) in the sandbox environment.

## Syntax

```javascript theme={null}
await testdriver.exec(language, code, timeout, silent)
```

## Parameters

<ParamField path="language" type="string" required>
  Language to execute: `'sh'` (Shell/Linux) or `'pwsh'` (PowerShell/Windows)
</ParamField>

<ParamField path="code" type="string" required>
  Code or command to execute
</ParamField>

<ParamField path="timeout" type="number" required>
  Timeout in milliseconds
</ParamField>

<ParamField path="silent" type="boolean" default="false">
  Suppress output if `true`
</ParamField>

## Returns

`Promise<string>` - Command output

## Shell Execution (Linux)

Execute shell commands in the Linux sandbox.

### Basic Commands

```javascript theme={null}
// List files
const files = await testdriver.exec('sh', 'ls -la', 5000);

// Check current directory
const pwd = await testdriver.exec('sh', 'pwd', 5000);

// Run a script
await testdriver.exec('sh', './setup.sh', 60000);
```

### File Operations

```javascript theme={null}
// Create a file
await testdriver.exec('sh', 'echo "Hello World" > test.txt', 5000);

// Read a file
const content = await testdriver.exec('sh', 'cat test.txt', 5000);

// Copy files
await testdriver.exec('sh', 'cp source.txt dest.txt', 5000);

// Delete files
await testdriver.exec('sh', 'rm test.txt', 5000);
```

## PowerShell Execution (Windows)

Execute PowerShell commands in the Windows sandbox.

### Software Installation

```javascript theme={null}
// Install npm package globally
await testdriver.exec('pwsh', 'npm install -g http-server', 30000);

// Install via Chocolatey
await testdriver.exec('pwsh', 'choco install firefox -y', 60000);

// Download and run installer
await testdriver.exec('pwsh', `
  Invoke-WebRequest -Uri "https://example.com/setup.exe" -OutFile "C:\\setup.exe"
  Start-Process -FilePath "C:\\setup.exe" -ArgumentList "/S" -Wait
`, 120000);
```

### File Operations

```javascript theme={null}
// Create a file
await testdriver.exec('pwsh', `
  Set-Content -Path "C:\\test.txt" -Value "Hello World"
`, 5000);

// Read a file
const content = await testdriver.exec('pwsh', 
  'Get-Content -Path "C:\\test.txt"', 
  5000
);

// Copy files
await testdriver.exec('pwsh', 
  'Copy-Item -Path "C:\\source.txt" -Destination "C:\\dest.txt"', 
  5000
);

// Delete files
await testdriver.exec('pwsh', 
  'Remove-Item -Path "C:\\test.txt"', 
  5000
);

// List directory
const files = await testdriver.exec('pwsh', 
  'Get-ChildItem -Path "C:\\Users\\testdriver\\Documents"', 
  5000
);
```

### Process Management

```javascript theme={null}
// List running processes
const processes = await testdriver.exec('pwsh', 'Get-Process', 5000);

// Start application
await testdriver.exec('pwsh', `
  Start-Process "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" -ArgumentList "--start-maximized", "https://example.com"
`, 5000);

// Kill a process
await testdriver.exec('pwsh', 'Stop-Process -Name "chrome" -Force', 5000);

// Wait for process
await testdriver.exec('pwsh', 'Start-Process notepad -Wait', 30000);
```

### Environment Variables

```javascript theme={null}
// Set environment variable (session)
await testdriver.exec('pwsh', '$env:MY_VAR = "value"', 5000);

// Get environment variable
const value = await testdriver.exec('pwsh', '$env:MY_VAR', 5000);

// Set persistent environment variable
await testdriver.exec('pwsh', `
  [Environment]::SetEnvironmentVariable("MY_VAR", "value", "User")
`, 5000);
```

### Network Operations

```javascript theme={null}
// Test connectivity
const pingResult = await testdriver.exec('pwsh', 
  'Test-NetConnection google.com', 
  10000
);

// Download file
await testdriver.exec('pwsh', `
  Invoke-WebRequest -Uri "https://example.com/file.zip" -OutFile "C:\\Downloads\\file.zip"
`, 30000);

// Check if port is open
const portOpen = await testdriver.exec('pwsh', 
  'Test-NetConnection -ComputerName localhost -Port 3000', 
  5000
);
```

## Silent Execution

Suppress output for background operations:

```javascript theme={null}
// Silent installation
await testdriver.exec('pwsh', 'npm install -g some-package', 30000, true);

// Start background process
await testdriver.exec('pwsh', 'Start-Process notepad', 5000, true);

// Run setup script silently
await testdriver.exec('pwsh', '.\\setup.ps1', 60000, true);
```

## Best Practices

<Check>
  **Use appropriate timeouts**

  ```javascript theme={null}
  // Quick operations: 5000ms
  await testdriver.exec('sh', 'ls -la', 5000);

  // Installations: 30000-60000ms
  await testdriver.exec('pwsh', 'npm install -g package', 30000);

  // Downloads or complex operations: 60000-120000ms
  await testdriver.exec('pwsh', 'Install-Module Something', 120000);
  ```
</Check>

<Check>
  **Handle errors gracefully**

  ```javascript theme={null}
  try {
    await testdriver.exec('pwsh', 'Some-Command', 5000);
  } catch (error) {
    console.error('Command failed:', error.message);
    // Fallback or retry logic
  }
  ```
</Check>

<Check>
  **Use silent mode for background tasks**

  ```javascript theme={null}
  // Silent install
  await testdriver.exec('pwsh', 'npm install -g tool', 30000, true);

  // Background service
  await testdriver.exec('pwsh', 'Start-Service MyService', 5000, true);
  ```
</Check>

<Warning>
  **Escape strings properly in PowerShell**

  Use proper escaping for special characters:

  ```javascript theme={null}
  // Use backticks for newlines
  await testdriver.exec('pwsh', `
    Write-Host "Line 1\`nLine 2"
  `, 5000);

  // Use single quotes to avoid variable expansion
  await testdriver.exec('pwsh', 
    "Write-Host 'Text with $special chars'", 
    5000
  );
  ```
</Warning>

## Complete Example

```javascript theme={null}
import { beforeAll, afterAll, describe, it } from 'vitest';
import TestDriver from 'testdriverai';

describe('Code Execution', () => {
  let testdriver;

  beforeAll(async () => {
    client = new TestDriver(process.env.TD_API_KEY);
    await testdriver.auth();
    await testdriver.connect();
  });

  afterAll(async () => {
    await testdriver.disconnect();
  });

  it('should execute shell commands on Linux', async () => {
    // List directory
    const files = await testdriver.exec('sh', 'ls -la', 5000);
    console.log('Files:', files);
    
    // Create a file
    await testdriver.exec('sh', 'echo "Hello World" > test.txt', 5000);
    
    // Read the file
    const content = await testdriver.exec('sh', 'cat test.txt', 5000);
    expect(content).toContain('Hello World');
  });

  it('should install and use tools on Windows', async () => {
    // Install tool
    await testdriver.exec('pwsh', 'npm install -g http-server', 30000, true);
    
    // Create HTML file
    await testdriver.exec('pwsh', `
      Set-Content -Path "C:\\index.html" -Value "<h1>Test Page</h1>"
    `, 5000);
    
    // Start server in background
    await testdriver.exec('pwsh', `
      Start-Process pwsh -ArgumentList "-Command", "http-server C:\\ -p 8080"
    `, 5000, true);
    
    await new Promise(r => setTimeout(r, 3000));
    
    // Launch browser
    await testdriver.exec('pwsh', `
      Start-Process chrome -ArgumentList "http://localhost:8080"
    `, 5000);
    
    await testdriver.focusApplication('Google Chrome');
  });
});
```

## Related Methods

* [`focusApplication()`](/v7/focus-application) - Focus apps before exec
* [`find()`](/v7/find) - Locate elements visually
* [`type()`](/v7/type) - Type text into inputs