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

<CodeGroup>
  ```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-cli sandbox exec <sandboxID> -- echo "hello"

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

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

## Read command output

Use `stdout` to read what the command printed.

<CodeGroup>
  ```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()
  ```
</CodeGroup>

## Run in the background

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

<CodeGroup>
  ```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()
  ```
</CodeGroup>

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

<CodeGroup>
  ```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()
  ```
</CodeGroup>

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

<CodeGroup>
  ```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)
  ```
</CodeGroup>