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

# 执行命令

`sandbox exec` 命令在已经运行的沙箱内执行单个命令，并将其输出流式传输回您的终端。用于一次性命令、脚本和自动化；如需交互式 shell 会话，请改用远程 shell（`connect`）命令。

## 前置条件

在运行命令之前设置 `PPIO_API_KEY` 环境变量。您还需要运行中沙箱的 ID。

## 用法

```bash theme={null}
ppio sandbox exec <sandboxID> <command...>
```

该命令有别名 `ex`。沙箱 ID 之后的所有内容都被视为要执行的命令。

```bash theme={null}
# 运行一个简单的命令
ppio sandbox exec sbx-123 ls -l /tmp

# 使用别名
ppio sandbox exec sbx-123 python3 --version
```

## 参数

| 参数             | 说明                              |
| -------------- | ------------------------------- |
| `<sandboxID>`  | 要在其中执行命令的运行中沙箱的 ID。             |
| `<command...>` | 要执行的命令。多个部分会被引用并合并为单个 shell 命令。 |

## 选项

| 选项                      | 说明                                          |
| ----------------------- | ------------------------------------------- |
| `-b, --background`      | 在后台运行命令并立即返回。会打印进程 ID (PID)，CLI 以代码 `0` 退出。 |
| `-c, --cwd <dir>`       | 运行命令的工作目录。                                  |
| `-u, --user <user>`     | 以指定用户身份运行命令。                                |
| `-e, --env <KEY=VALUE>` | 为命令设置环境变量。可重复使用以设置多个变量。                     |

## 前台执行

默认情况下，命令在前台运行。它的 `stdout` 和 `stderr` 会实时流式传输到您的终端，CLI 以与远程命令相同的退出代码退出。

```bash theme={null}
# 在特定目录、以特定用户身份、使用环境变量运行
ppio sandbox exec sbx-123 \\
  --cwd /home/user/app \\
  --user root \\
  --env LOG_LEVEL=debug \\
  --env REGION=us-east \\
  ./run.sh
```

## 后台执行

传递 `-b` / `--background` 可以启动命令并立即返回，而无需等待它完成。CLI 会打印进程 ID 并以代码 `0` 退出。

```bash theme={null}
ppio sandbox exec sbx-123 --background \\
  "python3 -m http.server 3000"
```

## 管道标准输入

您可以通过标准输入将数据通过管道传输到命令；CLI 会将其流式传输到远程进程，并在输入耗尽时发出文件结束信号，因此像 `cat`、`wc` 和 `grep` 这样的工具可以正确终止。

```bash theme={null}
# 将本地数据通过管道传输到在沙箱中运行的命令
cat local-file.txt | ppio sandbox exec sbx-123 "wc -l"

# 将文件重定向到命令
ppio sandbox exec sbx-123 "grep error" < app.log
```

<Note>
  管道标准输入需要较新的沙箱版本。如果沙箱不支持它，CLI 会打印警告并忽略管道输入 —— 重新构建您的模板以获取最新的沙箱版本。
</Note>

## 退出代码和中断

* 在前台，CLI 以远程命令的退出代码退出，因此它可以自然地与 shell 脚本和 CI 组合。
* 如果命令无法启动或发生其他错误，CLI 会打印错误并以代码 `1` 退出。
* 按 `Ctrl+C`（或发送终止信号）会在 CLI 退出之前杀死远程进程。