# useShell

Executes a shell command declared in `fluxlay.yaml` and optionally renders the output in an xterm terminal.

## Import

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

## Signature

```tsx
function useShell(commandId: string, options?: UseShellOptions): UseShellReturn;
```

## Parameters

| Parameter   | Type              | Description                                                       |
| ----------- | ----------------- | ----------------------------------------------------------------- |
| `commandId` | `string`          | The command ID declared in the `shell` section of `fluxlay.yaml`. |
| `options`   | `UseShellOptions` | Optional configuration.                                           |

### UseShellOptions

| Property          | Type                       | Default     | Description                                              |
| ----------------- | -------------------------- | ----------- | -------------------------------------------------------- |
| `refreshInterval` | `number`                   | `30000`     | Interval in milliseconds to re-execute the command.      |
| `showStdout`      | `boolean`                  | `true`      | Write stdout to the terminal.                            |
| `showStderr`      | `boolean`                  | `false`     | Write stderr to the terminal.                            |
| `terminal`        | `TerminalInstance \| null` | `undefined` | Terminal instance from `useTerminal()` to render output. |
| `columns`         | `number`                   | —           | Pseudo-terminal column width.                            |
| `lines`           | `number`                   | —           | Pseudo-terminal line height.                             |

## Return Value

| Property    | Type                  | Description                                 |
| ----------- | --------------------- | ------------------------------------------- |
| `execute`   | `() => Promise<void>` | Manually trigger command execution.         |
| `isRunning` | `boolean`             | Whether the command is currently executing. |
| `error`     | `string \| null`      | Error message if execution failed.          |
| `result`    | `ShellResult \| null` | Result of the last execution.               |

### 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

### With Terminal

```tsx
const { terminalRef, instance } = useTerminal({
  theme: TerminalThemes.nord
});

const { error } = useShell("macchina", {
  terminal: instance,
  refreshInterval: 60000
});
```

### Without Terminal

```tsx
const { result, isRunning } = useShell("fetch-ip", {
  refreshInterval: 10000
});

return <p>{result?.stdout}</p>;
```

## Behavior

- Executes once on mount.
- Re-executes when `commandId` changes.
- Re-executes at `refreshInterval` intervals if set.
- If a `terminal` instance is provided, output is written to the terminal with ANSI support.