# シェルコマンドを命令的に実行

`useShell()` は宣言した間隔で自動的にコマンドを実行しますが、`runShell()` は呼び出した瞬間に 1 回だけ実行する命令的な API です。ボタンクリックやイベントに応じて実行したい場合、または出力を加工してから表示したい場合に使います。

## マニフェストの宣言

`useShell` と同じく、まず `fluxlay.yaml` で実行可能なコマンドを宣言します。

```yaml title="fluxlay.yaml"
shell:
  weather:
    run: curl -s "https://wttr.in/?format=%t"
    reason: 現在の気温を取得します。
    required:
      - curl
```

## ボタンクリックで実行

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

function RefreshButton() {
  const [temp, setTemp] = useState<string>("");

  const handleClick = async () => {
    const result = await runShell("weather");
    setTemp(result.stdout.trim());
  };

  return <button onClick={handleClick}>気温を更新 {temp && `: ${temp}`}</button>;
}
```

## 出力を加工してから表示

```tsx
async function fetchProcesses() {
  const { stdout } = await runShell("ps-aux");
  return stdout
    .split("\n")
    .slice(1, 11) // 上位 10 件
    .map(line => line.trim());
}
```

## useShell との使い分け

| 場面                                 | 推奨       |
| ------------------------------------ | ---------- |
| 一定間隔で自動更新してターミナル表示 | `useShell` |
| ボタンクリックなどイベント駆動       | `runShell` |
| 出力を JSON パースして利用           | `runShell` |
| 表示前に値を加工・フィルタしたい     | `runShell` |

## 注意事項

- 戻り値は `Promise<ShellResult>` で、`{ stdout, stderr, statusCode, success, signal }` を含みます。`stdout` を使う前に `success`（または `statusCode === 0`）を確認してください。
- コマンド ID は `fluxlay.yaml` の `shell` セクションで宣言されている必要があります。未宣言の ID を渡すとエラーになります。
- `columns` / `lines` で擬似端末のサイズを指定できます（カラー出力の幅調整に有用）。

詳細は [runShell リファレンス](/ja/studio/developer/reference/sdk/run-shell.md)を参照してください。