Shell tools and customization

Applies to: Rubian 4.0.2; host commands require their corresponding installed tools

Updated September 16, 2026

Rubian can combine its own commands with tools installed on the host. Select the interface deliberately: a Ruby block operates in the Rubian session, while a host-command string follows the host shell's rules and permissions.

Discover and run a host command#

which(name) returns an available command's location or nil. Rubian command names are checked as well as host executables. whereis(name) displays broader command, binary and manual-location information when available. Use the startup command inventory for Rubian's installed command names.

bash(command = nil) opens the host Bash shell or executes a supplied string. It displays output and returns nil. sudo_cmd(*arguments) invokes a host command with the host's privilege mechanism and returns a Boolean result. Neither grants a disconnected Rubian session authority over a managed environment.

Where the supplied environment exposes it, kexec(path, *arguments) runs a permitted external executable and returns its execution result or an error. Its executable must be allowed by that environment's execution policy. This is distinct from bg, which starts Ruby work.

Repeat an observation#

watch(5) { system_status }

This repeats a Ruby block at the requested interval until interrupted with Ctrl-C. The minimum interval is one second. A string form runs a host Bash command instead. watch is an interactive repetition tool; use recurring work when the operation needs a named definition, retained result and restoration controls.

time_cmd { expression } measures elapsed time, displays it and returns the block's result. A string argument selects a host command. The helper can display a caught error, so a timing line alone does not prove successful work. It is useful for local observation, not a substitute for a defined performance evaluation.

Define a host-command alias#

alias_cmd('host_date', 'date')
host_date

An alias names a host-shell command string. It does not store a Ruby expression or persist automatically between sessions. alias_cmd(:list) shows registered aliases. Removing or clearing the alias registry in this edition does not reliably remove a callable method already created in the session; start a fresh session when you need to ensure an old alias is unavailable.

For reusable Rubian logic, define a Ruby method as described in Command language and results, or keep it in a project.

Small composition helpers#

Command	Result
`echo(*values, quiet: false)`	Joined text as a string; displays it unless quiet.
`date(format = nil, quiet: false)`	Current time, or a string formatted with the supplied Ruby time format.
`seq(start, finish = nil, step = 1, quiet: false)`	Numeric sequence as an array.
`sleep_cmd(seconds)`	Pauses the current operation.
`env(key = nil)`	The selected environment value, or all environment values when no key is given.
`clear`	Clears the terminal display.
`yes(string = 'y')`	Uses the host utility for continuous repeated output; interrupt with Ctrl-C.

Request a specific environment key when diagnosing configuration. A full environment listing can include secrets. In connected mode, hostname and uname can display connected-runtime identification rather than conventional host hostname or kernel information; use a host tool explicitly when that is the information required.

Host package utilities#

gem_list(pattern = nil), gem_install(*names) and gem_uninstall(*names) use host Ruby package tools. Installing a gem does not establish its Forge compatibility. Check the selected Ruby environment and each package's tool output; a returned collection does not aggregate success across every requested installation.

On Debian-family hosts, apt(action, *packages) invokes the host package manager. Installation, removal, purge and upgrade operations can accept changes automatically. Use a reviewed package operation for the actual host; these commands are not a Rubian product-update mechanism.