Run commands on an instance - Namespace Documentation

client.command runs a command on a running instance. Use runCommand() to stream output as it is produced, or runCommandSync() to wait for the command to finish and read its combined output. The examples on this page use a Compute client:

import { createComputeClient } from "@namespacelabs/sdk/api/compute";

const client = createComputeClient();

Both methods take an optional targetContainerName. Set it to run the command in that container, which must already be running on the instance. See Create and manage compute instances to start containers at creation time. Omit it to run the command directly in the guest, as macOS instances do.

`command.runCommand()`

Run a command and stream its output. Stdout and stderr arrive as individual responses. The final response carries an exitStatus with the command’s exit code.

Example

const decoder = new TextDecoder();

for await (const response of client.command.runCommand({
  instanceId,
  targetContainerName: "app",
  command: { command: ["ls", "-la"], cwd: "/srv" },
})) {
  if (response.exitStatus) {
    console.log(`exited with ${response.exitStatus.exitCode}`);
  } else {
    process.stdout.write(decoder.decode(response.data));
  }
}

API reference

runCommand(
  request: MessageInitShape<typeof RunCommandRequestSchema>,
  options?: CallOptions,
): AsyncIterable<RunCommandResponse>

Arguments and options

string

required

The instance the command runs on.

string

The name of the container to run the command in. When omitted, the command runs directly in the guest.

Command

required

The command to execute.

Hide properties

string[]

required

The command and its arguments, such as ["ls", "-la"].

EnvironmentVariable[]

Environment variables to set for the command. Each entry has a name and either a value or a fromSecretId.

string

The working directory for the command.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns an async iterable of RunCommandResponse.

RunCommandResponse_Stream

The output stream the chunk belongs to: STDOUT, STDERR, or STREAM_UNKNOWN.

Uint8Array

A chunk of output data. Decode it with a TextDecoder for text output.

RunCommandResponse_ExitStatus

Set only on the last message in the stream. Carries the command’s exitCode.

If the instance does not exist, the call fails with NotFound. The same applies when targetContainerName is set and no such container exists.

`command.runCommandSync()`

Run a command and wait for it to complete. Stdout and stderr are buffered and returned in a single response.

Example

const decoder = new TextDecoder();

const result = await client.command.runCommandSync({
  instanceId,
  targetContainerName: "app",
  command: { command: ["sh", "-c", "npm test"] },
});

console.log(decoder.decode(result.stdout));

if (result.exitCode !== 0) {
  console.error(decoder.decode(result.stderr));
}

API reference

runCommandSync(
  request: MessageInitShape<typeof RunCommandRequestSchema>,
  options?: CallOptions,
): Promise<RunCommandSyncResponse>

Arguments and options

runCommandSync() takes the same RunCommandRequest as runCommand().

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a RunCommandSyncResponse.

Uint8Array

The combined stdout output.

Uint8Array

The combined stderr output.

number

The exit code of the command.

If the instance does not exist, the call fails with NotFound. The same applies when targetContainerName is set and no such container exists.

The whole command runs within a single RPC. Raise timeoutMs in the call options for long-running commands, or use runCommand() and consume output as it arrives.

Create and manage instances

Create instances and start the containers commands run in.

Instance logs

Stream and fetch logs from an instance.

​command.runCommand()

​Example

​API reference

​Arguments and options

​Return value

​command.runCommandSync()

​Example

​API reference

​Arguments and options

​Return value

​Related documentation

Create and manage instances

Instance logs

`command.runCommand()`

Example

API reference

Arguments and options

Return value

`command.runCommandSync()`

Example

API reference

Arguments and options

Return value

Related documentation