runShell

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

Import

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

Signature

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

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.