---
title: "shell"
description: "The shell namespace — the engine's Luau API reference for shell."
section: "API Reference"
slug: "api-shell"
canonical: "https://origozero.ai/docs/api-shell"
updated: "2026-09-05T23:13:47.180123475+00:00"
tags: ["api", "reference"]
---

# shell

The `shell` namespace — 7 functions.

## globals/shell/run {#globals-shell-run}

```lua
shell.run(command: string) -> ShellResult
```

Execute a command in the engine's emulated Unix shell and
return once it has completed. This is the same shell as the MCP
`bash` tool — 60+ builtins (ls, cat, grep, find, echo, ...)
operating on the virtual scene filesystem. A command that runs
Luau (`run`, `luau`, `zm`, `zero`) needs the engine's frame loop,
so from a coroutine it is queued to run off the frame loop and
this yields until it finishes; everything else runs inline. That
queueing runs the whole line, so a line that also ran a command
of its own comes back with the explanation in `stderr` and
`shell.runAsync` as the way to run it whole.

**Parameters**

- `command` `string` — Shell command to execute.

**Returns** `ShellResult` — Command result `{ stdout, stderr, exitCode, ok }`.

```lua
local r = shell.run("ls /zero/source")
```

## globals/shell/runAsync {#globals-shell-runasync}

```lua
shell.runAsync(command: string) -> string
```

Asynchronous version of `shell.run`. Returns a promise ID that
resolves to a JSON-encoded result string. Use with
`task.await()`.

**Parameters**

- `command` `string` — Shell command to execute.

**Returns** `string` — Promise ID — pass to `task.await()` to get the JSON result.

```lua
local json = task.await(shell.runAsync("find /zero -name '*.luau'"))
```

## modules/shell/README {#modules-shell-readme}

```lua
require("@builtin/modules/api/engine/shell") -- shell (also available as global 'shell')
```

Engine emulated Unix shell — same shell that powers the MCP `bash` tool. Public Luau surface over the `__shell` Internal FFI namespace.

Usage: local shell = require("@builtin/modules/api/engine/shell")
Also available as global: shell

## modules/shell/run {#modules-shell-run}

```lua
run(command: string): ShellResult
```

Execute a command in the engine's emulated Unix shell and
return once it has completed. This is the same shell as the MCP
`bash` tool — 60+ builtins (ls, cat, grep, find, echo, ...)
operating on the virtual scene filesystem. A command that runs
Luau (`run`, `luau`, `zm`, `zero`) needs the engine's frame loop,
so from a coroutine it is queued to run off the frame loop and
this yields until it finishes; everything else runs inline. That
queueing runs the whole line, so a line that also ran a command
of its own comes back with the explanation in `stderr` and
`shell.runAsync` as the way to run it whole.

**Parameters**

- `command` `string` — Shell command to execute.

```lua
local r = shell.run("ls /zero/source")
```

## modules/shell/runAsync {#modules-shell-runasync}

```lua
runAsync(command: string): string
```

Asynchronous version of `shell.run`. Returns a promise ID that
resolves to a JSON-encoded result string. Use with
`task.await()`.

**Parameters**

- `command` `string` — Shell command to execute.

```lua
local json = task.await(shell.runAsync("find /zero -name '*.luau'"))
```

## typed/builtin//modules/api/engine/shell/shell/run {#typed-builtin-modules-api-engine-shell-shell-run}

```lua
shell.run(command: string) -> ShellResult
```

Execute a command in the engine's emulated Unix shell and
return once it has completed. This is the same shell as the MCP
`bash` tool — 60+ builtins (ls, cat, grep, find, echo, ...)
operating on the virtual scene filesystem. A command that runs
Luau (`run`, `luau`, `zm`, `zero`) needs the engine's frame loop,
so from a coroutine it is queued to run off the frame loop and
this yields until it finishes; everything else runs inline. That
queueing runs the whole line, so a line that also ran a command
of its own comes back with the explanation in `stderr` and
`shell.runAsync` as the way to run it whole.

**Parameters**

- `command` `string` — Shell command to execute.

**Returns** `ShellResult` — Command result `{ stdout, stderr, exitCode, ok }`.

```lua
local r = shell.run("ls /zero/source")
```

## typed/builtin//modules/api/engine/shell/shell/runAsync {#typed-builtin-modules-api-engine-shell-shell-runasync}

```lua
shell.runAsync(command: string) -> string
```

Asynchronous version of `shell.run`. Returns a promise ID that
resolves to a JSON-encoded result string. Use with
`task.await()`.

**Parameters**

- `command` `string` — Shell command to execute.

**Returns** `string` — Promise ID — pass to `task.await()` to get the JSON result.

```lua
local json = task.await(shell.runAsync("find /zero -name '*.luau'"))
```