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

> Run shell commands, argv commands, streaming work, and background processes inside a machine.

Commands are the process API for a machine. Use them to run one-off checks,
install packages, start services, stream logs, send stdin, inspect processes,
and stop background work.

## Quick Example

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  from nullspace import Machine

  with Machine.create(template="base") as machine:
      result = machine.commands.run("echo hello", shell=True)
      print(result.exit_code, result.stdout.strip())
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine exec mch_... --shell "echo hello"
  ```
</CodeGroup>

`CommandResult` includes `exit_code`, `stdout`, `stderr`, and, when returned by
the API, `pid`. A command that exits non-zero still returns a result; check
`exit_code` before treating the work as successful.

## Choose An Execution Mode

| Need                              | SDK Call                                                           | Use When                                                      |
| --------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------- |
| Run and collect output after exit | `machine.commands.run(...)`                                        | The command is short and bounded.                             |
| Stream output while running       | `machine.commands.run_streaming(...)` or `run(..., on_stdout=...)` | Logs matter before the process exits.                         |
| Start long-running work           | `run(..., background=True)`                                        | You need a server or worker process to keep running.          |
| Reconnect to a process            | `machine.commands.connect(pid)`                                    | A background process already exists and you need live output. |
| Manage a process                  | `list()`, `get_logs()`, `send_stdin()`, `kill()`                   | You need process inventory or cleanup.                        |

## Shell Strings Vs Argv

Use `shell=True` for authored shell snippets, pipelines, redirects, and
environment expansion. Use `args` when you want exact argument boundaries
without shell parsing. The API rejects requests that combine `shell=True` with
non-empty `args`.

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  result = machine.commands.run("python3", ["-c", "print('hello')"])
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine exec mch_... python3 -- -c "print('argv')"
  ```

  ```json HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  {
    "command": "python3",
    "args": ["-c", "print('hello')"],
    "shell": false
  }
  ```
</CodeGroup>

The raw API body uses `command`, optional `args`, and `shell`.

## Working Directory, Environment, And Timeout

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  result = machine.commands.run(
      "pytest -q",
      shell=True,
      cwd="/workspace/project",
      envs={"PYTHONUNBUFFERED": "1"},
      timeout=120,
  )
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine exec mch_... \
    --cwd /workspace/project --env PYTHONUNBUFFERED=1 --timeout 120 \
    --shell "pytest -q"
  ```
</CodeGroup>

`cwd` must be a valid machine path and cannot target Nullspace runtime-managed
paths under `/workspace/.nullspace`. `envs` are added only for that execution;
they do not persist after the command exits unless your command writes them to
disk.

## Command Guides

<CardGroup cols={2}>
  <Card title="Streaming" href="./streaming">
    Stream stdout and stderr while a command is still running.
  </Card>

  <Card title="Run commands in background" href="./background">
    Start long-running processes and manage them by PID.
  </Card>

  <Card title="Manage processes" href="./processes">
    List processes, fetch logs, send stdin, and terminate work.
  </Card>

  <Card title="CLI commands" href="../cli/execute-commands">
    Execute commands and stream processes from the Nullspace CLI.
  </Card>
</CardGroup>

## Related

* [Machines](../machines/overview)
* [Filesystem](../filesystem)
* [Python SDK commands](../guides/python-sdk/commands-processes)