> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rebind.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# rb.system

> Read the clock, cursor, screen size and focused window, run commands, and type text.

`rb.system` reads the state of the computer a script runs on: the clock, the
cursor position, the screen size and the focused window. It also runs commands and
types text through the operating system. A script reaches for it to check which
app has focus, call a command-line tool, or enter text.

**Needs:** the `exec` [permission](https://docs.rebind.gg/reference/sdk/modeline.md#permissions) for
`exec` and `exec_detached`.

This script runs `git status` on F5 and logs its error output when the command
exits with a nonzero code:

```luau theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
-- rebind: min_sdk=3.9.0 name=example version=1.0.0 permissions=exec
rb.bind("F5", function()
  rb.run(function()
    local result = rb.system.exec("git status", { timeout = 10000 })
    if result.exit ~= 0 then
      rb.log.error(result.stderr)
    end
  end)
end)
```

| Signature | Returns |
| - | - |
| `rb.system.time() -> number` | wall-clock time in milliseconds since the Unix epoch |
| `rb.system.mouse() -> (number, number)` | cursor x, y |
| `rb.system.screen() -> (number, number)` | screen width, height |
| `rb.system.window() -> WindowInfo` | the focused window: `{ title, process, x, y, width, height }` |
| `rb.system.exec(cmd: string, options: ExecOptions?) -> ExecResult` | `{ exit, stdout, stderr }` |
| `rb.system.exec_detached(cmd: string, options: RbExecDetachedOptions?) -> number` | the process id |
| `rb.system.type_text(text: string) -> ()` | nothing |

## rb.system.exec

Runs `cmd` through the shell (`cmd.exe /C` on Windows, `sh -c` on macOS) and
waits for it.

* `options.timeout`: milliseconds, default 5000. On expiry the process is killed
  (on macOS its whole process group) and the call raises
  `exec timed out after <ms>ms`.
* `options.cwd`: working directory.
* `stdout` and `stderr` keep the first 64 KB (65,536 bytes) each, with trailing
  whitespace trimmed. `exit` is `-1` when the process has no exit code.
* On Windows no console window appears.

Inside a coroutine the command runs on a worker thread and the coroutine yields.
Elsewhere it blocks the engine until the command ends and logs one warning per
script; that fallback is deprecated.

Without the `exec` permission the call raises
`System.Exec() requires 'exec' permission` and Rebind stops the script.

## rb.system.exec\_detached

Starts `cmd` directly, without a shell, and returns its process id at once.
`options.args` is a list of arguments, passed as given; `options.cwd` sets the
working directory. Output is discarded and the process keeps running after the
script stops. A failed start raises `exec detached spawn failed: <reason>`.

## rb.system.type\_text

Types `text` through the host operating system and never through the script's
HID output, so it types the same in hardware mode. That includes any Unicode.
It raises when the operating system refuses the input, for example macOS
without the Accessibility grant.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.