# runShell

Low-level imperative function to execute a shell command declared in `fluxlay.yaml`.

## Import

```tsx
import { runShell } from "@fluxlay/react";
```

## Signature

```tsx
function runShell(commandId: string, options?: ShellOptions): Promise<ShellResult>;
```

## Parameters

| Parameter   | Type           | Description                                |
| ----------- | -------------- | ------------------------------------------ |
| `commandId` | `string`       | The command ID declared in `fluxlay.yaml`. |
| `options`   | `ShellOptions` | Optional configuration.                    |

### ShellOptions

| Property  | Type     | Description                   |
| --------- | -------- | ----------------------------- |
| `columns` | `number` | Pseudo-terminal column width. |
| `lines`   | `number` | Pseudo-terminal line height.  |

## Return Value

### ShellResult

| Property     | Type             | Description                                                                 |
| ------------ | ---------------- | --------------------------------------------------------------------------- |
| `success`    | `boolean`        | Whether the command exited with status 0.                                   |
| `stdout`     | `string`         | Standard output.                                                            |
| `stderr`     | `string`         | Standard error.                                                             |
| `statusCode` | `number \| null` | Exit status code, or `null` if the process was terminated by a signal.      |
| `signal`     | `number \| null` | Signal number that terminated the process, or `null` if it exited normally. |

## Example

```tsx
import { useEffect, useState } from "react";
import { runShell } from "@fluxlay/react";

function BatteryStatus() {
  const [battery, setBattery] = useState("");

  useEffect(() => {
    const fetch = async () => {
      const result = await runShell("battery", { columns: 80, lines: 24 });
      if (result.success) setBattery(result.stdout.trim());
    };
    fetch();
    const id = setInterval(fetch, 30000);
    return () => clearInterval(id);
  }, []);

  return <p>{battery}</p>;
}
```

## When to Use

Use `runShell` instead of `useShell` when you need:

- Full control over execution timing.
- To process the output programmatically before display.
- To execute a command outside of React's render cycle.

For terminal-rendered output with automatic refresh, prefer [`useShell`](/en/studio/developer/reference/sdk/use-shell.md).