> ## Documentation Index
> Fetch the complete documentation index at: https://namespace.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Run commands on an instance
> Run commands on a running Namespace compute instance with the TypeScript SDK.
`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:
```typescript theme={null}
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](/docs/reference/typescript-sdk/compute/manage) 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
```typescript {3-7} theme={null}
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
```typescript theme={null}
runCommand(
request: MessageInitShape,
options?: CallOptions,
): AsyncIterable
```
Arguments and options
The instance the command runs on.
The name of the container to run the command in. When omitted, the command runs directly in the guest.
The command to execute.
The command and its arguments, such as `["ls", "-la"]`.
Environment variables to set for the command. Each entry has a `name` and either a `value` or a `fromSecretId`.
The working directory for the command.
Cancellation, timeout, and header options. See [Shared call options](/docs/reference/typescript-sdk/compute/manage#shared-call-options).
Return value
Returns an async iterable of `RunCommandResponse`.
The output stream the chunk belongs to: `STDOUT`, `STDERR`, or `STREAM_UNKNOWN`.
A chunk of output data. Decode it with a `TextDecoder` for text output.
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
```typescript {3-7} theme={null}
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
```typescript theme={null}
runCommandSync(
request: MessageInitShape,
options?: CallOptions,
): Promise
```
Arguments and options
`runCommandSync()` takes the same `RunCommandRequest` as [`runCommand()`](#command-runcommand-arguments-and-options).
Cancellation, timeout, and header options. See [Shared call options](/docs/reference/typescript-sdk/compute/manage#shared-call-options).
Return value
Returns a `RunCommandSyncResponse`.
The combined stdout output.
The combined stderr output.
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.
## Related documentation
Create instances and start the containers commands run in.
Stream and fetch logs from an instance.