commands.run() runs terminal commands inside a sandbox. It returns the command output, can start a process in the background, and can stream output through callbacks as the process produces it.
Install the SDK, or the CLI for
ppio commands, and set the PPIO_API_KEY and PPIO_DOMAIN environment variables before running these examples. See Quickstart and Install and authenticate.Run a command
Callcommands.run() with a command string. The returned result contains the command output. In the CLI examples, <sandbox-id> is the sandbox ID.
Read the command output
Usestdout to read what the command printed.
Run a command in the background
Pass the background option to start a long-running process, such as a server, without blocking on it.Override environment variables for one command
Override or append environment variables for a single command with theenvs option. It applies only to that command.
Stream output as it is produced
For long-running commands, passon_stdout / on_stderr in Python or onStdout / onStderr in Node.js to receive output as it is produced, instead of waiting for the command to finish. Each callback receives its output as soon as it exists, with stdout and stderr delivered separately. The returned result still contains the final exit code.
Stream a background command
To keep the program running while a command streams, start it withbackground=True in Python or background: true in Node.js. The call returns a CommandHandle instead of waiting for the result. The same callbacks can be attached, other work can continue, and wait() blocks until the command finishes and returns its CommandResult.
Retrieve the full output
When real-time output is not needed, run the command in the foreground and read the fullstdout and stderr from the returned CommandResult. This is the simplest approach for commands with a predictable, short duration.
Output of a background command
For a command started in the background, the accumulated output is also available on the handle after it completes.Command options
- Python
- Node.js
Result fields
- Python
- Node.js
A command that exits with a non-zero code raises an error. The Errors page lists it, and the error carries the same
stdout, stderr, exitCode and error fields, so the output is still readable after a failure.