useShell

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

Import

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

Signature

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

const { terminalRef, instance } = useTerminal({
  theme: TerminalThemes.nord
});
 
const { error } = useShell("macchina", {
  terminal: instance,
  refreshInterval: 60000
});

Without Terminal

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.