Run commands

Run non-interactive commands with exec() or shell(). Choose between structured arguments and shell evaluation based on the command you need to run.

Command operations start a stopped Devbox automatically. Commands run with exec() and shell() are retained with their output and can be inspected later with devbox logs.

`exec()`

Use exec() to pass an executable and its arguments without invoking a shell. Arguments are passed literally, so shell expansion, pipelines, redirects, and environment-variable interpolation do not apply.

Example

Run a command and inspect its result:

const devbox = await client.devboxes.get("sdk-example");
const result = await devbox.exec(["node", "--version"]);
if (result.exitCode !== 0) {
  throw new Error(result.error ?? result.stderr);
}
console.log(result.stdout.trim());

API reference

exec(argv: readonly string[], options?: ExecOptions): Promise<ExecResult>

Arguments and options

readonly string[]

required

The executable followed by its arguments. The array must contain at least one item.

ExecOptions

Options for the command.

Hide properties

string

The working directory. Absolute paths are used as provided. Relative paths resolve from the Devbox workspace directory.

Record<string, string>

Additional environment variables. Names must start with a letter or underscore and contain only letters, numbers, and underscores.

string | Uint8Array

Data provided to standard input. Strings are encoded as UTF-8.

(data: Uint8Array) => void

Called for each standard-output chunk. Output is also collected in the returned result.

(data: Uint8Array) => void

Called for each standard-error chunk. Output is also collected in the returned result.

AbortSignal

Cancels the operation when the signal is aborted.

number

The total timeout budget in milliseconds, including activation and connection time. The value must be finite and non-negative.

When cwd is omitted, the command runs in the Devbox’s default directory. If the Devbox checks out a repository during creation, that directory may not exist until the checkout completes. Pass an explicit cwd when running a command immediately after creation.

Return value

exec() resolves with an ExecResult after the command finishes.

interface ExecResult {
  exitCode: number | null;
  signal: string | null;
  error?: string;
  stdout: string;
  stderr: string;
}

number | null

required

The command’s exit code, or null when no exit code is available.

string | null

required

The signal that ended the command, or null when no signal is available.

string

Agent-reported failure detail, such as a command-not-found message.

string

required

The complete standard output decoded as UTF-8.

string

required

The complete standard error decoded as UTF-8.

A non-zero exit code does not reject the promise. Check exitCode to determine whether the command succeeded. The promise rejects for failures such as an invalid request, an aborted operation, a timeout, or a transport error.

More examples

Pass arguments containing spaces

Arguments containing spaces remain single arguments.

const devbox = await client.devboxes.get("sdk-example");
await devbox.exec(["printf", "%s\n", "hello world"]);

Stream command output

Stream output while retaining it in the returned result.

const devbox = await client.devboxes.get("sdk-example");
const result = await devbox.exec(["npm", "test"], {
  cwd: "/workspace",
  onStdout: (data) => process.stdout.write(data),
  onStderr: (data) => process.stderr.write(data),
  timeoutMs: 10 * 60_000,
});

`shell()`

Use shell() when a command requires shell syntax such as pipelines, redirects, variable interpolation, or multiple statements.

Example

Run a script that chains two commands, then print its standard output:

const devbox = await client.devboxes.get("sdk-example");
const result = await devbox.shell("npm install && npm test");
process.stdout.write(result.stdout);

API reference

shell(script: string, options?: ShellOptions): Promise<ExecResult>

Arguments and options

string

required

The script to evaluate with the Devbox shell.

ShellOptions

All ExecOptions, plus the shell property.

Hide additional property

string

The shell executable. The SDK uses the Devbox’s configured shell when available and otherwise falls back to /bin/sh.

Return value

shell() returns the same ExecResult as exec(). A non-zero exit code resolves normally and must be checked by the caller.

More examples

Set the working directory and environment variables

const devbox = await client.devboxes.get("sdk-example");
await devbox.shell("npm install && npm test", {
  cwd: "/workspace",
  env: { CI: "true" },
});

Use a specific shell

const devbox = await client.devboxes.get("sdk-example");
await devbox.shell("echo $SHELL", { shell: "/bin/bash" });

Choose between `exec()` and `shell()`

Use	When
`exec()`	You have an executable and structured arguments and do not need shell evaluation. This is the safer default for arguments derived from external input.
`shell()`	You need pipelines, redirects, variable interpolation, command chaining, or another shell feature.

Use interactive terminals

Open and control interactive terminal sessions.

Create and manage Devboxes

Create a Devbox and control its lifecycle.

Handle errors and timeouts

Cancel operations and handle SDK failures.

Devbox SDK

Automation

CLI

`exec()`

Example

API reference

Arguments and options

Return value

More examples

Pass arguments containing spaces

Stream command output

`shell()`

Example

API reference

Arguments and options

Return value

More examples

Set the working directory and environment variables

Use a specific shell

Choose between `exec()` and `shell()`

Use interactive terminals

Create and manage Devboxes

Handle errors and timeouts

​exec()

​Example

​API reference

​Arguments and options

​Return value

​More examples

​Pass arguments containing spaces

​Stream command output

​shell()

​Example

​API reference

​Arguments and options

​Return value

​More examples

​Set the working directory and environment variables

​Use a specific shell

​Choose between exec() and shell()

​Related documentation

Use interactive terminals

Create and manage Devboxes

Handle errors and timeouts

`exec()`

Example

API reference

Arguments and options

Return value

More examples

Pass arguments containing spaces

Stream command output

`shell()`

Example

API reference

Arguments and options

Return value

More examples

Set the working directory and environment variables

Use a specific shell

Choose between `exec()` and `shell()`

Related documentation