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

# Run Command

> Execute terminal commands inside agent runtimes

`runtime.run_cmd(command=...)` accepts either a single shell string or a `command` + explicit `args` list:

```python theme={null}
runtime.run_cmd(command="pip install pandas --quiet")
runtime.run_cmd(command="echo hello; sleep 1; echo world")

runtime.run_cmd(command="pip", args=["install", "pandas", "--quiet"])
runtime.run_cmd(command="ls", args=["-la", "/workspace"])
```

## Basic Usage

```python theme={null}
from gravixlayer import GravixLayer

client = GravixLayer()
runtime = client.runtime.create(template="python-3.14-base-small")

# Single-string form
result = runtime.run_cmd(command="ls -la /workspace")
print(result.stdout)
print(result.exit_code)

# Equivalent command + args form
result = runtime.run_cmd(command="ls", args=["-la", "/workspace"])
print(result.stdout)

runtime.kill()
```

## Install Packages

```python theme={null}
from gravixlayer import GravixLayer

client = GravixLayer()
runtime = client.runtime.create(template="python-3.14-base-small")

# Install a Python package — single string form
runtime.run_cmd(command="pip install pandas --quiet")

# Or with command + args (safer for user-supplied package names)
runtime.run_cmd(command="pip", args=["install", "pandas", "--quiet"])

# Verify installation
result = runtime.run_cmd(
    command="python",
    args=["-c", "import pandas; print(pandas.__version__)"],
)
print(result.stdout)

runtime.kill()
```

## Run Shell Scripts

```python theme={null}
from gravixlayer import GravixLayer

client = GravixLayer()
runtime = client.runtime.create(template="python-3.14-base-small")

# Single string — chained commands run in one shell invocation
result = runtime.run_cmd(command="echo $HOME && python --version")
print(result.stdout)

# Equivalent with explicit shell invocation
result = runtime.run_cmd(
    command="sh",
    args=["-lc", "echo $HOME && python --version"],
)
print(result.stdout)

runtime.kill()
```

## With Environment Variables

Set `env_vars` at runtime creation so variables are available to every `run_cmd` / `run_code` call:

```python theme={null}
from gravixlayer import GravixLayer

client = GravixLayer()
runtime = client.runtime.create(
    template="python-3.14-base-small",
    env_vars={"APP_MODE": "production"},
)

result = runtime.run_cmd(command="sh", args=["-lc", "echo APP_MODE=$APP_MODE"])
print(result.stdout)  # APP_MODE=production

runtime.kill()
```

## Streaming Output

For long-running commands, pass `on_stdout` / `on_stderr` / `on_exit` callbacks to receive output incrementally as the process produces it. The transport switches to Server-Sent Events transparently; the returned `CommandRunResponse` still carries the aggregated stdout/stderr/exit\_code so existing code keeps working.

```python theme={null}
from gravixlayer import GravixLayer

client = GravixLayer()
runtime = client.runtime.create(template="python-3.14-base-small")

result = runtime.run_cmd(
    command="sh -lc 'for i in 1 2 3 4 5; do echo line-$i; sleep 1; done'",
    on_stdout=lambda chunk: print(chunk, end="", flush=True),
    on_stderr=lambda chunk: print(chunk, end="", flush=True),
    on_exit=lambda code: print(f"\n[exit={code}]"),
)

print("final exit code:", result.exit_code)
print("duration:", result.duration_ms, "ms")
runtime.kill()
```

All user code (including streamed commands) executes as the unprivileged `agent` user inside the runtime. `sudo` is configured for the `agent` user with `NOPASSWD`, so commands like `sudo apt-get install -y ...` work without prompting.

## Parameters

| Parameter     | Type          | Required | Description                                                         |
| ------------- | ------------- | -------- | ------------------------------------------------------------------- |
| `command`     | string        | Yes      | Command to execute. May be a single shell string or a program name. |
| `args`        | list\[string] | No       | Additional arguments appended to `command`.                         |
| `working_dir` | string        | No       | Working directory.                                                  |
| `timeout`     | integer       | No       | Timeout in seconds.                                                 |
| `on_stdout`   | callable(str) | No       | Per-chunk stdout callback. Enables streaming mode.                  |
| `on_stderr`   | callable(str) | No       | Per-chunk stderr callback. Enables streaming mode.                  |
| `on_exit`     | callable(int) | No       | Final exit-code callback. Enables streaming mode.                   |

## Response

| Field         | Type    | Description                                 |
| ------------- | ------- | ------------------------------------------- |
| `stdout`      | string  | Standard output (aggregated when streaming) |
| `stderr`      | string  | Standard error (aggregated when streaming)  |
| `exit_code`   | integer | Process exit code                           |
| `duration_ms` | integer | Execution duration in milliseconds          |
| `success`     | boolean | `True` when exit code is 0                  |
| `error`       | string  | API-level error (if any)                    |