# runShell

`fluxlay.yaml` で宣言されたシェルコマンドを実行する低レベルの命令型関数です。

## インポート

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

## シグネチャ

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

## パラメータ

| パラメータ  | 型             | 説明                                     |
| ----------- | -------------- | ---------------------------------------- |
| `commandId` | `string`       | `fluxlay.yaml` で宣言されたコマンド ID。 |
| `options`   | `ShellOptions` | オプションの設定。                       |

### ShellOptions

| プロパティ | 型       | 説明                       |
| ---------- | -------- | -------------------------- |
| `columns`  | `number` | 擬似ターミナルの列幅。     |
| `lines`    | `number` | 擬似ターミナルの行の高さ。 |

## 戻り値

### ShellResult

| プロパティ   | 型               | 説明                                                        |
| ------------ | ---------------- | ----------------------------------------------------------- |
| `success`    | `boolean`        | コマンドがステータス 0 で終了したか。                       |
| `stdout`     | `string`         | 標準出力。                                                  |
| `stderr`     | `string`         | 標準エラー。                                                |
| `statusCode` | `number \| null` | 終了ステータスコード。シグナルで終了した場合は `null`。     |
| `signal`     | `number \| null` | プロセスを終了させたシグナル番号。通常終了の場合は `null`。 |

## 使用例

```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>;
}
```

## 使い分け

`useShell` ではなく `runShell` を使うのは以下の場合です：

- 実行タイミングを完全に制御したい。
- 表示前に出力をプログラム的に処理したい。
- React のレンダリングサイクル外でコマンドを実行したい。

自動リフレッシュ付きのターミナルレンダリングには [`useShell`](/ja/studio/developer/reference/sdk/use-shell.md) を推奨します。