Add per-command env and cwd options documentation

Document new per-command environment variable and working directory
options added to exec(), execStream(), and startProcess() methods.

Changes:
- Add env and cwd parameters to exec() and execStream() API docs
- Add practical examples showing per-command env variable scoping
- Add working directory override examples
- Update environment variables configuration guide
- Clarify that per-command options do not persist in session

Related PR: cloudflare/sandbox-sdk#204

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: github-actions[bot]

src/content/docs/sandbox/api/commands.mdx

@@ -25,6 +25,8 @@ const result = await sandbox.exec(command: string, options?: ExecOptions): Promi
   - `stream` - Enable streaming callbacks (default: `false`)
   - `onOutput` - Callback for real-time output: `(stream: 'stdout' | 'stderr', data: string) => void`
   - `timeout` - Maximum execution time in milliseconds
+  - `env` - Environment variables for this command only (does not persist in session)
+  - `cwd` - Working directory for this command only (does not persist in session)
 
 **Returns**: `Promise<ExecuteResponse>` with `success`, `stdout`, `stderr`, `exitCode`
 
@@ -43,6 +45,12 @@ await sandbox.exec('npm install', {
   stream: true,
   onOutput: (stream, data) => console.log(`[${stream}] ${data}`)
 });
+
+// With per-command environment variables and working directory
+await sandbox.exec('npm test', {
+  env: { NODE_ENV: 'test', CI: 'true' },
+  cwd: '/workspace/my-app'
+});
 ```
 </TypeScriptExample>
 
@@ -56,7 +64,7 @@ const stream = await sandbox.execStream(command: string, options?: ExecOptions):
 
 **Parameters**:
 - `command` - The command to execute
-- `options` - Same as `exec()`
+- `options` - Same as `exec()` (includes `timeout`, `env`, `cwd`)
 
 **Returns**: `Promise<ReadableStream>` emitting `ExecEvent` objects (`start`, `stdout`, `stderr`, `complete`, `error`)
 
@@ -79,6 +87,12 @@ for await (const event of parseSSEStream<ExecEvent>(stream)) {
       break;
   }
 }
+
+// With per-command options
+const stream = await sandbox.execStream('python analyze.py', {
+  env: { DATA_PATH: '/workspace/data' },
+  cwd: '/workspace/analysis'
+});
 ```
 </TypeScriptExample>
 
@@ -93,8 +107,12 @@ const process = await sandbox.startProcess(command: string, options?: ProcessOpt
 **Parameters**:
 - `command` - The command to start as a background process
 - `options` (optional):
-  - `cwd` - Working directory
-  - `env` - Environment variables
+  - `cwd` - Working directory for the process
+  - `env` - Environment variables for the process
+  - `timeout` - Maximum execution time in milliseconds
+  - `processId` - Custom process ID (auto-generated if not provided)
+  - `encoding` - Output encoding (default: `'utf-8'`)
+  - `autoCleanup` - Automatically clean up process on exit (default: `true`)
 
 **Returns**: `Promise<ProcessInfo>` with `id`, `pid`, `command`, `status`
 
@@ -103,7 +121,7 @@ const process = await sandbox.startProcess(command: string, options?: ProcessOpt
 const server = await sandbox.startProcess('python -m http.server 8000');
 console.log('Started with PID:', server.pid);
 
-// With custom environment
+// With custom environment and working directory
 const app = await sandbox.startProcess('node app.js', {
   cwd: '/workspace/my-app',
   env: { NODE_ENV: 'production', PORT: '3000' }

src/content/docs/sandbox/configuration/environment-variables.mdx

@@ -32,7 +32,7 @@ await sandbox.exec("python seed.py"); // Has DATABASE_URL and API_KEY
 
 ### 2. Per-command with exec() options
 
-Pass environment variables for a specific command:
+Pass environment variables for a specific command without affecting the session:
 
 ```typescript
 await sandbox.exec("node app.js", {
@@ -42,6 +42,14 @@ await sandbox.exec("node app.js", {
 	},
 });
 
+// Works with execStream() too
+const stream = await sandbox.execStream("npm run build", {
+	env: {
+		CI: "true",
+		NODE_ENV: "production",
+	},
+});
+
 // Also works with startProcess()
 await sandbox.startProcess("python server.py", {
 	env: {
@@ -50,6 +58,8 @@ await sandbox.startProcess("python server.py", {
 });
 ```
 
+Per-command environment variables are scoped to that command only and do not persist in the session. They are automatically cleaned up when the command completes.
+
 **Use when:** You need different environment variables for different commands, or want to override sandbox-level variables.
 
 ### 3. Session-level with createSession()

src/content/docs/sandbox/guides/execute-commands.mdx

@@ -133,6 +133,66 @@ await sandbox.exec('python /workspace/analyze.py data.csv');
 ```
 </TypeScriptExample>
 
+## Use per-command environment variables
+
+Set environment variables for a single command without affecting the session:
+
+<TypeScriptExample>
+```
+// Environment variables scoped to this command only
+const result = await sandbox.exec('echo $API_KEY', {
+  env: { API_KEY: 'secret-key-123' }
+});
+
+console.log(result.stdout); // "secret-key-123"
+
+// Next command does not have API_KEY
+const verify = await sandbox.exec('echo $API_KEY');
+console.log(verify.stdout); // "" (empty)
+```
+</TypeScriptExample>
+
+Per-command environment variables:
+- Do not persist in the session
+- Override session-level variables if both are set
+- Are isolated from other concurrent commands
+- Are cleaned up automatically after the command completes
+
+## Override working directory
+
+Override the working directory for a single command:
+
+<TypeScriptExample>
+```
+// Execute in a specific directory
+const result = await sandbox.exec('pwd', {
+  cwd: '/workspace/my-project'
+});
+
+console.log(result.stdout); // "/workspace/my-project"
+
+// Session working directory unchanged
+const verify = await sandbox.exec('pwd');
+console.log(verify.stdout); // "/workspace" (default)
+```
+</TypeScriptExample>
+
+Combining `cwd` and `env` for complex workflows:
+
+<TypeScriptExample>
+```
+// Run tests in a specific directory with custom environment
+await sandbox.exec('npm test', {
+  cwd: '/workspace/api',
+  env: {
+    NODE_ENV: 'test',
+    DATABASE_URL: 'sqlite::memory:',
+    LOG_LEVEL: 'debug'
+  }
+});
+```
+</TypeScriptExample>
+
 ## Best practices
 
 - **Check exit codes** - Always verify `result.success` and `result.exitCode`
@@ -158,14 +218,19 @@ if (!check.success) {
 
 ### Working directory issues
 
-Use absolute paths or change directory:
+Use the `cwd` option for cleaner code, or use absolute paths:
 
 <TypeScriptExample>
 ```
-// Use absolute path
+// Best: Use cwd option
+await sandbox.exec('python script.py', {
+  cwd: '/workspace/my-app'
+});
+
+// Alternative: Use absolute path
 await sandbox.exec('python /workspace/my-app/script.py');
 
-// Or change directory
+// Alternative: Change directory inline
 await sandbox.exec('cd /workspace/my-app && python script.py');
 ```
 </TypeScriptExample>