> ## 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.

# Wait for Command

> Block until a background command completes and return its result.

Blocks until the background process identified by `pid` completes, then returns the
full `CommandResult`. The process is removed from the tracked list after this call
returns.

If the PID is not found in the tracked process list, the endpoint returns a
`CommandResult` with `exit_code: 1` and a `"process not found"` message in stderr.

## Path Parameters

<ParamField path="sandbox_id" type="string" required>
  The sandbox identifier. Format: `sbx-<8 chars>`.
</ParamField>

<ParamField path="pid" type="integer" required>
  Process ID of the background command to wait for.

  Example: `42`
</ParamField>

## Response

<ResponseField name="stdout" type="string">
  Full standard output produced by the command.
</ResponseField>

<ResponseField name="stderr" type="string">
  Full standard error output. Contains `"process not found"` if the PID is
  not tracked.
</ResponseField>

<ResponseField name="exit_code" type="integer">
  Exit code returned by the process. `0` indicates success. `1` when the
  process was not found.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  # Start a background command first
  curl -X POST https://api.declaw.ai/sandboxes/sbx-a1b2c3d4/commands \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "cmd": "sleep 2 && echo done", "background": true }'

  # Then wait for it
  curl https://api.declaw.ai/sandboxes/sbx-a1b2c3d4/commands/42/wait \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  from declaw import Sandbox

  sbx = Sandbox.connect("sbx-a1b2c3d4", api_key="YOUR_API_KEY", domain="api.declaw.ai")

  handle = sbx.commands.run("sleep 2 && echo done", background=True)
  result = sbx.commands.wait(handle.pid)
  print(result.stdout)    # done\n
  print(result.exit_code) # 0
  ```

  ```typescript TypeScript theme={null}
  import { Sandbox } from "@declaw/sdk";

  const sbx = await Sandbox.connect("sbx-a1b2c3d4", {
    apiKey: "YOUR_API_KEY",
    domain: "api.declaw.ai",
  });

  const handle = await sbx.commands.run("sleep 2 && echo done", {
    background: true,
  });
  const result = await sbx.commands.wait(handle.pid);
  console.log(result.stdout);   // done\n
  console.log(result.exitCode); // 0
  ```
</CodeGroup>

```json Response theme={null}
{
  "stdout": "done\n",
  "stderr": "",
  "exit_code": 0
}
```

## Error Responses

| Status | Cause                                       |
| ------ | ------------------------------------------- |
| `400`  | `pid` path parameter is not a valid integer |
| `401`  | Missing or invalid API key                  |
| `503`  | Sandbox has no VM                           |
| `502`  | envd daemon inside the VM is unreachable    |