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

# Run Command

> Run shell commands in a Declaw sandbox with environment variables, working directories, and error handling.

## What You'll Learn

* Running a basic shell command with `sbx.commands.run()`
* Passing environment variables via the `envs` parameter
* Setting the working directory via the `cwd` parameter
* Handling failing commands by inspecting `exit_code` and `stderr`
* Running multi-line / chained commands with `&&`
* Proper cleanup with `try/finally` and `sbx.kill()`

## Prerequisites

<Snippet file="snippets/env-setup.mdx" />

## Code Walkthrough

<Tabs>
  <Tab title="Python">
    **Basic command** — `result.stdout` contains the captured output:

    ```python theme={null}
    result = sbx.commands.run('echo "Hello World"')
    print(f"stdout: {result.stdout}")
    print(f"exit_code: {result.exit_code}")
    ```

    **Environment variables** — pass a dict via `envs`:

    ```python theme={null}
    result = sbx.commands.run(
        "echo $GREETING",
        envs={"GREETING": "Hi from Declaw"},
    )
    print(f"stdout: {result.stdout}")
    ```

    **Working directory** — set with `cwd`:

    ```python theme={null}
    result = sbx.commands.run("pwd", cwd="/tmp")
    # stdout: /tmp
    ```

    **Failing commands** — non-zero exit codes do not raise exceptions by default:

    ```python theme={null}
    result = sbx.commands.run("exit 42")
    print(f"exit_code: {result.exit_code}")   # 42
    print(f"stderr: {result.stderr!r}")
    if result.exit_code != 0:
        print(f"Command failed as expected with exit code {result.exit_code}")
    ```

    **Chained commands** — use shell operators:

    ```python theme={null}
    result = sbx.commands.run('echo "line1" && echo "line2" && echo "line3"')
    print(f"stdout:\n{result.stdout}")
    ```
  </Tab>

  <Tab title="TypeScript">
    **Basic command** — `result.stdout` contains the captured output:

    ```typescript theme={null}
    let result = await sbx.commands.run('echo "Hello World"');
    console.log(`stdout: ${result.stdout}`);
    console.log(`exit_code: ${result.exitCode}`);
    ```

    **Environment variables** — pass as `envs` in the options object:

    ```typescript theme={null}
    result = await sbx.commands.run("echo $GREETING", {
      envs: { GREETING: "Hi from Declaw" },
    });
    console.log(`stdout: ${result.stdout}`);
    ```

    **Working directory** — set with `cwd`:

    ```typescript theme={null}
    result = await sbx.commands.run("pwd", { cwd: "/tmp" });
    // stdout: /tmp
    ```

    **Failing commands** — inspect `exitCode` without a thrown exception:

    ```typescript theme={null}
    result = await sbx.commands.run("exit 42");
    console.log(`exit_code: ${result.exitCode}`);  // 42
    if (result.exitCode !== 0) {
      console.log(`Command failed as expected with exit code ${result.exitCode}`);
    }
    ```

    **Chained commands:**

    ```typescript theme={null}
    result = await sbx.commands.run(
      'echo "line1" && echo "line2" && echo "line3"'
    );
    console.log(`stdout:\n${result.stdout}`);
    ```
  </Tab>
</Tabs>

## Expected Output

```
==================================================
Declaw Run Command Example
==================================================

--- Creating Sandbox ---
Sandbox created: sbx_abc123

--- 1. Basic Command ---
stdout: Hello World
exit_code: 0

--- 2. Command with Environment Variables ---
stdout: Hi from Declaw
exit_code: 0

--- 3. Command with Working Directory ---
stdout: /tmp
exit_code: 0

--- 4. Failing Command ---
exit_code: 42
stderr: ''
Command failed as expected with exit code 42

--- 5. Multi-line Command ---
stdout:
line1
line2
line3
exit_code: 0

--- Cleaning Up ---
Sandbox killed.

==================================================
Done!
==================================================
```