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

# Run Command

You can use the `commands.run()` method to run terminal commands inside the sandbox.

## Basic usage

Call `commands.run()` with a command string. The returned result contains the command output.

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita } from 'novita-sandbox'

const novita = new Novita()
const sandbox = await novita.sandbox.create()

const result = await sandbox.commands.run('ls -l')
console.log(result)

await sandbox.kill()
```

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita

novita = Novita()
sandbox = novita.sandbox.create()

result = sandbox.commands.run('ls -l')
print(result)

sandbox.kill()
```

```bash CLI icon="terminal" theme={"system"}
# Execute a command in a running sandbox (alias: sandbox ex)
novita sandbox exec <sandboxID> -- echo "hello"

# Run in background
novita sandbox exec <sandboxID> -b -- long-running-cmd

# Set working directory / user / env
novita sandbox exec <sandboxID> -c /home/user -u root -e KEY=VALUE -- ls -la
```

## Read command output

Use `stdout` to read what the command printed.

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita } from 'novita-sandbox'

const novita = new Novita()
const sandbox = await novita.sandbox.create()

const result = await sandbox.commands.run('echo hello')
console.log(result.stdout) // hello

await sandbox.kill()
```

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita

novita = Novita()
sandbox = novita.sandbox.create()

result = sandbox.commands.run("echo hello")
print(result.stdout)   # hello

sandbox.kill()
```

## Run in the background

Pass the background option to start a long-running process (such as a server) without blocking on it.

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita } from 'novita-sandbox'

const novita = new Novita()
const sandbox = await novita.sandbox.create()

await sandbox.commands.run('python3 -m http.server 3000', { background: true })

await sandbox.kill()
```

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita

novita = Novita()
sandbox = novita.sandbox.create()

sandbox.commands.run("python3 -m http.server 3000", background=True)

sandbox.kill()
```

## Override environment variables per command

You can override or append environment variables for a single command with the `envs` option. It applies only to that command.

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita } from 'novita-sandbox'

const novita = new Novita()
const sandbox = await novita.sandbox.create()

const result = await sandbox.commands.run('echo $LOG_LEVEL', {
  envs: { LOG_LEVEL: 'info' }, // applies only to this command
})
console.log(result.stdout) // info

await sandbox.kill()
```

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita

novita = Novita()
sandbox = novita.sandbox.create()

result = sandbox.commands.run(
    "echo $LOG_LEVEL",
    envs={"LOG_LEVEL": "info"},   # applies only to this command
)
print(result.stdout)   # info

sandbox.kill()
```

## Stream output

For long-running commands, pass `on_stdout` / `on_stderr` (Python) or `onStdout` / `onStderr` (JavaScript) callbacks to receive output as it is produced, instead of waiting for the command to finish. The returned result still contains the final exit code.

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita

novita = Novita()
sbx = novita.sandbox.connect(sandbox_id)

result = sbx.commands.run(
    "for i in 1 2 3; do echo line $i; sleep 1; done",
    on_stdout=lambda data: print("OUT:", data, end=""),
    on_stderr=lambda data: print("ERR:", data, end=""),
)
print("exit code:", result.exit_code)
```

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita } from 'novita-sandbox'

const novita = new Novita()
const sbx = await novita.sandbox.connect(sandboxId)

const result = await sbx.commands.run(
  'for i in 1 2 3; do echo line $i; sleep 1; done',
  {
    onStdout: (data) => process.stdout.write(`OUT: ${data}`),
    onStderr: (data) => process.stderr.write(`ERR: ${data}`),
  },
)
console.log('exit code:', result.exitCode)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.