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

# Commands And Processes

> Python SDK object reference for running commands and managing processes.

`machine.commands` runs commands inside a live machine. `AsyncMachine.commands`
provides the async equivalent.

## Command Execution

| Method                                                                                                                      | Use                                                                     |
| --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `run(command, args=None, shell=False, cwd=None, envs=None, timeout=None, background=False, on_stdout=None, on_stderr=None)` | Run a command, optionally stream output, or start it in the background. |
| `stream(...)`                                                                                                               | Stream command output from a long-running foreground execution.         |

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
result = machine.commands.run(
    "python3 -m pytest",
    shell=True,
    cwd="/workspace/repo",
    envs={"PYTHONUNBUFFERED": "1"},
    timeout=300,
)
print(result.exit_code, result.stdout)
```

Use `shell=True` for authored shell strings. Use `args=[...]` when exact
argument boundaries matter.

## Background Processes

| Method                      | Use                                                       |
| --------------------------- | --------------------------------------------------------- |
| `run(..., background=True)` | Start a long-running command and return a process handle. |
| `list()`                    | List running commands and PTY sessions.                   |
| `send_stdin(pid, data)`     | Send input to a process.                                  |
| `logs(pid)`                 | Fetch stdout, stderr, and interleaved output.             |
| `kill(pid)`                 | Stop a process by PID.                                    |

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
server = machine.commands.run(
    "python3 -m http.server 8080",
    shell=True,
    cwd="/workspace",
    background=True,
)
try:
    print(machine.get_url(8080))
    input("Open the URL, then press Enter to stop the server...")
finally:
    server.kill()
```

## Related

* [Commands guide](../../commands/overview)
* [Process management](../../commands/processes)
* [API operation: execCommand](../../api-reference)