Skip to content

tyrus:os ​

tyrus:os exposes cross-platform information about the operating system the compiled binary is running on: platform, architecture, hostname, kernel release, locale, the line-ending constant, the active user, and standard directories. It is read-only and purely informational, process-level information (pid, cwd(), memoryUsage(), etc.) lives on the built-in process global instead, documented in Environment Variables.

Imports ​

tyrus
import { EOL, arch, hostname, language, locale, platform, release, systemName } from "tyrus:os";
import { OsArch, OsPlatform } from "tyrus:os";

System Identification ​

ExportSignaturePurpose
platform() => OsPlatformThe target platform.
arch() => OsArchThe target CPU architecture.
EOLstringThe native line-ending constant.
hostname() => stringThe machine's network hostname.
release() => stringThe kernel release/build version.
systemName() => stringThe POSIX-style (uname -s) system name.
locale() => stringThe current locale tag.
language() => stringThe current locale's language subtag.

User and Directories ​

ExportSignaturePurpose
userInfo() => UserInfoThe login, home directory, and shell in one call.
userName() => stringThe login name.
whoami() => string?The real name (GECOS), not the login.
homeDir() => stringThe user's home directory.
cacheDir() => stringThe user's cache directory.
configDir() => stringThe user's config directory.
dataDir() => stringThe user's data directory.
tempDir() => stringThe system's temporary directory.
desktopDir() => string?The user's desktop directory, if any.
documentsDir() => string?The user's documents directory, if any.
appDataDir(app: string) => stringAn application-specific subdirectory of dataDir.

Hardware and Performance ​

ExportSignaturePurpose
cpus() => CpuInfo[]One entry per logical CPU core.
totalMem() => u64Total system memory, in bytes.
freeMem() => u64Free system memory, in bytes.
uptime() => u64Seconds since the system itself last booted.
loadAvg() => f64[]The 1/5/15-minute load averages.
battery() => BatteryInfo?The first battery's info, if any.
cpuTemp(unit: string) => f32?The highest reported sensor temperature.

Screen and Session ​

ExportSignaturePurpose
isDarkMode() => booleanWhether the desktop is in dark mode.
terminalSize() => [u16, u16]?The terminal's columns and rows.
isScreenLocked() => booleanWhether the screensaver/lock screen is active.
isSessionLocked() => booleanWhether the current user session is locked.
preventSleep() => Result<void, OsError>Inhibit automatic system/display sleep.
allowSleep() => Result<void, OsError>Reverse preventSleep.

isScreenLocked/isSessionLocked are best effort and Linux-only for now, false on other platforms, or when the underlying service cannot be reached.

Fonts and Accessibility ​

ExportSignaturePurpose
systemFonts() => FontInfo[]One entry per font face installed on the system.
accessibleColorContrast(fg: Color, bg: Color) => booleanWhether a color pair meets the WCAG AA contrast ratio.

Utilities ​

ExportSignaturePurpose
hasCapability(cap: SystemCapability) => booleanWhether a given capability is available on this system.

See Interfaces and Enums for the shape of OsPlatform, OsArch, SystemCapability, UserInfo, CpuInfo, BatteryInfo, FontInfo, and Color.

Unresolved values never abort the program

hostname(), release(), systemName(), userName(), and every directory function fall back to "unknown" or an empty string if the operating system does not report a value. locale() and language() fall back to "und", the standard "undetermined locale" subtag. whoami(), desktopDir(), documentsDir(), battery(), and cpuTemp() return an optional type because absence is a normal outcome (a headless system, an account with no real name set, a desktop with no battery, a container with no thermal sensor), none of these functions can fail the program the way a filesystem error does. The one exception is cpuTemp's unit argument: "celsius"/"fahrenheit" are the only valid values, and anything else aborts the program.

Example ​

tyrus
import { EOL, arch, hostname, language, locale, platform, release, systemName } from "tyrus:os";
import { OsArch, OsPlatform } from "tyrus:os";

const currentPlatform: OsPlatform = platform();
const currentArch: OsArch = arch();

print(`${systemName()} ${release()} (${hostname()})${EOL}locale ${locale()} (${language()})`);
// "Linux 6.8.0-generic (my-machine)"
// "locale en-US (en)"

if (currentPlatform === OsPlatform.Windows) {
    print("running on Windows");
}