rutil

rutil is an interactive workstation utility for Windows, Linux, and macOS. It gives networking, development toolchains, diagnostics, storage, security, WSL, and maintenance operations one consistent command interface while using native PowerShell and Bash implementations underneath.

The project is pre-1.0. Its defaults are conservative, but you should still review every proposed change before using mutation commands on an important workstation.

What makes rutil useful

• 171 documented workstation commands
• a compact main menu with focused submenus for network, system, storage, processes, development, environment, security, WSL, hardware, software, and diagnostics
• automatic discovery and numbered selection of adapters, processes, disks, runtimes, projects, and WSL distributions
• multi-selection for cleanup, bootstrap, and removal workflows
• current-state and target previews before configuration changes
• confirmation before destructive actions
• elevation only when an operation requires administrator or root access
• clear unsupported-capability messages instead of fake success
• no database servers, database clients, Redis, or database-specific packages in the Linux development stack

Quick installation

Clone the repository and enter it:

git clone https://github.com/rambod/rutil.git
cd rutil

Run the installer for your operating system.

Windows

.\bootstrap\install-windows.ps1

Linux

bash bootstrap/install-linux.sh

macOS

bash bootstrap/install-macos.sh

Each installer now:

1. checks whether the correct Go Task executable is already available;
2. installs Task only when it is missing;
3. installs the rutil launcher and adds its directory to your user PATH;
4. verifies that the command catalog loads;
5. prints commands you can run next.

Automatic Task installation uses:

Platform	Installer used when Task is missing
Windows	winget install Task.Task
Linux	sudo snap install task --classic
macOS	brew install go-task

WinGet, Snap, or Homebrew is only required when Task is not already installed. If the relevant package manager is unavailable, the installer stops before installing rutil and explains what is missing.

The manual Task commands, if you prefer to install it yourself, are documented by the Task project:

# Windows
winget install Task.Task

# Linux with Snap support
sudo snap install task --classic

# macOS
brew install go-task

Your first five minutes with rutil

Open a new terminal after installation and start with:

rutil

This opens the main category menu. Select a category by number, then select the command you want to run. Enter 0 to go back or exit.

rutil
  -> Development
     -> dev:install        # Linux language and compiler stack
     -> dev:doctor
     -> rust:toolchain

  -> Storage & Cleanup
     -> storage:info
     -> storage:largest-files
     -> storage:cleanup

You can also open a category directly:

rutil storage
rutil wsl                 # Windows only
rutil dev
rutil network
rutil security

Then verify the repository and required tools:

rutil doctor

Get a quick overview of the workstation:

rutil system:summary
rutil dev:versions
rutil network:info

Direct commands remain available when you already know what you need:

rutil storage:info
rutil wsl:list
rutil dev:versions
rutil network:diagnose

Use rutil help when you want the complete command listing instead of the menu. The categorized reference is in docs/COMMANDS.md.

How commands work

The general form is:

rutil category:operation

Examples:

rutil network:dns:test
rutil env:path:list
rutil storage:largest-files
rutil rust:doctor
rutil security:status

Most commands intentionally do not require flags. They discover available choices and ask questions such as:

Select network adapter:

[1] Ethernet
[2] Wi-Fi
[3] VMware Network Adapter
[0] Cancel

Enter one number for a single choice. When a command supports multi-selection, enter comma-separated numbers such as 1,3,5. Enter 0 when it is displayed to cancel without making a change. Confirmation questions default to No when you press Enter.

You can run the same catalog directly from the repository:

task network:info
task dev:doctor

The rutil launcher is the recommended everyday interface; it locates this repository’s Taskfile automatically.

Status messages

rutil uses consistent output labels:

Label	Meaning
[INFO]	Context, next steps, or a read-only observation
[OK] / [PASS]	The operation or diagnostic succeeded
[WARNING]	A capability is missing, a result needs attention, or an optional step was skipped
[ERROR] / [FAIL]	The requested operation could not be completed

A warning is not always a broken installation. For example, a desktop without a battery or a Linux system without NetworkManager will report that the related capability is unavailable.

Practical workflows

Check workstation health

rutil system:summary
rutil system:health
rutil hardware:cpu
rutil hardware:memory
rutil hardware:disk
rutil system:restart-required

Diagnose a network problem

rutil network:info
rutil network:diagnose
rutil network:dns:test
rutil network:ping
rutil network:trace
rutil network:ports:listening

For configuration changes, use the interactive commands:

rutil network:configure
rutil network:dns:set
rutil network:profile:save
rutil network:profile:apply

They display current state, let you select a discovered adapter or service, show the proposed replacement, and request confirmation. Linux network mutations generally require NetworkManager. macOS exposes fewer public Wi-Fi credential operations than Windows or NetworkManager.

Inspect a development environment

rutil dev:versions
rutil dev:doctor
rutil dev:path
rutil cpp:doctor
rutil dotnet:info
rutil rust:doctor
rutil node:doctor
rutil python:doctor

Create a basic project interactively:

rutil dev:project:new

The command asks for C++, C#, Rust, Go, Python, or Node.js, then offers language-native initialization, a README, and a .gitignore. It does not create a Git repository.

Language-specific examples:

rutil cpp:cmake:configure
rutil cpp:build
rutil dotnet:project:new
rutil rust:toolchain
rutil node:packages:outdated
rutil python:venv:create

Bootstrap developer tools

For a small, selectable native package plan:

rutil bootstrap:dev

It detects installed tools, lets you select stacks, prints missing packages and their sources, and asks before installation. Security-development and minimal bootstrap variants are also available:

rutil bootstrap:security
rutil bootstrap:minimal

On Ubuntu, open the Development menu and choose dev:install, or run it directly:

rutil dev:install

Its default languages profile installs current verified upstream releases of Go, Rust, Node.js LTS, CPython, Ruby, Dart, and Swift; .NET 10 LTS; and C, C++, Objective-C, Fortran, LLVM, assembly, JVM, and other distribution-supported compilers.

rutil dev:install -- --profile core
rutil dev:install -- --profile languages
rutil dev:install -- --profile full

Database servers, database clients, Redis, and database-specific development packages are rejected by policy. Mutable unverified installer routes remain disabled unless explicitly enabled with --allow-unverified-installers.

The older command names system:linux:dev and dev:languages remain aliases for compatibility.

Find or stop a local development server

rutil devserver:list
rutil port:find
rutil port:owner
rutil devserver:open
rutil devserver:kill

Termination commands identify the owning process and ask for confirmation.

Reclaim development disk space

Start with read-only analysis:

rutil storage:analyze
rutil storage:largest-files
rutil storage:largest-folders
rutil storage:duplicates

Then use a targeted cleanup:

rutil dev:clean
rutil node:clean
rutil python:cache:clean
rutil cpp:clean
rutil dotnet:clean
rutil rust:clean

Generated directories are discovered, sized, selected, displayed, and confirmed before recursive deletion. Platform cleanup commands are separate:

rutil storage:cleanup:windows
rutil storage:cleanup:linux
rutil storage:cleanup:mac

Running another operating system’s cleanup command does not substitute a different cleanup policy.

Review security and logs

rutil security:status
rutil security:firewall
rutil security:ports
rutil security:ssh
rutil security:updates
rutil security:secrets
rutil logs:errors

The secret scan is heuristic and reports candidate filenames without printing matching secret values. Review findings manually. Create a local diagnostic bundle with:

rutil diagnose:bundle

Review a bundle before sharing it, even though rutil limits the collected network and system fields.

Manage WSL on Windows

Install WSL and select a distribution from the current online list:

rutil system:wsl:install

Ubuntu 26.04 is placed first when Microsoft exposes it in wsl.exe --list --online. Press Enter for the recommended entry, choose another number, or enter Q to cancel.

Useful follow-up commands:

rutil wsl:list
rutil wsl:doctor
rutil wsl:start
rutil wsl:ip
rutil wsl:port
rutil wsl:backup
rutil wsl:restore

For an explicitly unattended installation:

rutil system:wsl:install -- -Distribution Ubuntu-26.04 -NonInteractive

Automatic Windows restart remains disabled unless explicitly requested. WSL administration commands are Windows-only.

Save and start workspaces

rutil workspace:add
rutil workspace:list
rutil workspace:open
rutil workspace:start
rutil workspace:status

A workspace stores its name, directory, and optional local startup components. Commands are shown again and confirmed before they are started. rutil stores no workspace secrets and performs no Git or Docker management.

Safety and elevation

• Read-only commands do not request administrator or root access.
• A privileged script elevates only for the system mutation it needs.
• Configuration commands show current and proposed state where native tools expose it.
• Cleanup and removal commands show exact targets and sizes where practical.
• PATH and hosts-file workflows create rutil-owned backups.
• Project .env commands do not display existing values.
• Diagnostic output stays local until you choose to share it.
• Unsupported capabilities explain why no change was made.

Always read a confirmation prompt carefully. A successful elevation prompt does not remove the later operation-specific confirmation.

Files created by rutil

Depending on the commands you use, rutil stores only local utility state:

Platform	Typical locations
Windows	%LOCALAPPDATA%\rutil, %APPDATA%\rutil, and the repository bin directory on user PATH
Linux/macOS	$XDG_CONFIG_HOME/rutil or ~/.config/rutil; $XDG_STATE_HOME/rutil or ~/.local/state/rutil; and ~/.local/bin/rutil
Project-specific	.env, virtual environments, or language-native project files only when requested

Network profiles, PATH backups, hosts backups, workspace metadata, logs, and diagnostic bundles stay on the local machine. Do not commit generated .env files or diagnostic output.

Troubleshooting

rutil is not found after installation

Open a new terminal first. On Linux or macOS, you can reload immediately with the command printed by the installer, usually:

source ~/.bashrc   # Bash
source ~/.zshrc    # Zsh

Confirm that the launcher directory is present:

# Windows
$env:Path -split ';' | Select-String 'rutil\\bin'

# Linux/macOS
command -v rutil
printf '%s\n' "$PATH"

Task is missing

Rerun the platform bootstrap. It automatically installs Task when WinGet, Snap, or Homebrew is available. You can also use the manual Task commands from the installation section.

Verify that the installed program is Go Task:

task --version
task --help

Its help output should include the --taskfile option.

A command reports an unavailable capability

Read the warning for the native dependency. Common examples are NetworkManager for Linux connection changes, smartctl for detailed disk SMART data, lm-sensors for Linux temperatures, and platform-specific VPN clients. rutil does not silently install optional tools during an unrelated command.

A privileged operation fails

Run the command normally rather than opening the whole terminal as administrator or root. rutil will request UAC or sudo when needed. If elevation is unavailable or cancelled, it exits without applying the mutation.

Updating rutil

rutil does not perform Git-management operations. Update the checked-out repository yourself, review the changes, and rerun the bootstrap if launcher behavior changed:

git pull --ff-only

.\bootstrap\install-windows.ps1

bash bootstrap/install-linux.sh   # Linux
bash bootstrap/install-macos.sh   # macOS

Development and validation

Run the complete regression suite from Windows PowerShell:

.\tests\Invoke-StaticChecks.ps1

It parses every PowerShell and Bash script, validates every Taskfile, dry-runs the 171-command public contract, checks destructive defaults and the no-database policy, exercises selection helpers, and covers WSL installer regressions. CI additionally validates the platform Task catalog and Bash syntax on Ubuntu and macOS.

See docs/ADDING_A_TASK.md, CONTRIBUTING.md, SECURITY.md, and CODE_OF_CONDUCT.md before contributing.

License

MIT - see LICENSE.