ChrisTitusTech_linutil/docs/content/userguide/getting-started.md at 2fcd7cf878ec3609a40b07a7605a6886210225a2

Files

T

Sean (ANGRYxScotsman) 2fcd7cf878 New linutil website (#1215 )

* Add Hugo build artifacts to .gitignore

Ignore docs/public/, docs/resources/, and docs/.hugo_build.lock so
generated Hugo output is never accidentally committed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Add Hugo site infrastructure for Linutil docs

Adds the Hugo configuration, theme module (hextra), layout shortcodes,
i18n strings, static assets (favicons, nav logo), and archetype template
needed to build the documentation site.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Add docs site homepage

Adds the root _index.md with badges, the quick-start curl command, and
an important-note callout about frequent updates.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Add user guide content pages for Linutil

Rewrites all user guide sections from Winutil (Windows) content to
accurate Linutil (Linux) documentation:

- _index.md: overview, feature summary, quick links
- getting-started.md: how to run, install options, TUI navigation, keyboard shortcuts
- store/_index.md: application installation guide with category tables
- tweaks/_index.md: distro-specific system setup (Arch, Fedora, Debian, Ubuntu, Alpine)
- features/_index.md: security, gaming, emulators, and utilities reference
- updates/_index.md: how to keep Linutil up to date
- automation/_index.md: TOML config file usage and use-case examples

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Add FAQ, known issues, and contributing guide pages

- faq.md: answers for general usage, running, scripts, contributing, and updates
- KnownIssues.md: documents terminal size, rendering, distro support, Nvidia, and Cargo update issues
- CONTRIBUTING.md: full contributing guide based on .github/CONTRIBUTING.md, formatted for the docs site

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Add developer reference section and architecture docs

- dev/_index.md: landing page for the developer reference section
- dev/architecture.md: comprehensive architecture doc covering workspace
  layout, data model (Tab/ListNode/Command), tab_data.toml format, task
  list flags, preconditions system, script embedding via include_dir!,
  the script execution pipeline (PTY/vt100/tui-term), TUI layout and
  focus state machine, config file parsing, and key dependencies

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docgen: write walkthrough to docs/content/userguide/walkthrough.md

- Rename generated file from userguide.md to walkthrough.md to better
  reflect that it is an auto-generated script reference/walkthrough
- Update USER_GUIDE path to docs/content/userguide/walkthrough.md so
  cargo xtask docgen writes to the correct Hugo content location
- Update automation guide link to point to ../walkthrough/

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: remove unused Winutil screenshot assets

All images in docs/assets/images/ were Winutil (Windows) screenshots
copied over from the Winutil docs. None are referenced by any content
file. Keeping only favicon.png and navlogo.png at the assets root,
which are used by hugo.toml.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Update CNAME

* updated hugo configs

* docs: add preview.gif to homepage via Hugo mount

Mount .github/preview.gif directly into Hugo's static pipeline using
includeFiles so only the gif is exposed (no workflows or other .github
files). This means any update to .github/preview.gif is automatically
reflected on the site without any manual copying.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* added workflow

* Delete docs/assets/navlogo.png

can change this to something else

* Delete navlogo.png

* Update docs.yaml

* Update hugo.toml

* Update _index.md

* fix typo

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-05 16:13:39 -06:00

4.1 KiB

Raw Blame History

title, weight

title	weight
Getting Started with Linutil	1

Welcome to Linutil!

Linutil is a distro-agnostic Linux toolbox built in Rust. It provides an interactive terminal UI (TUI) for installing applications, configuring your system, and running common Linux setup tasks — all from one place.

System Requirements

Before running Linutil, ensure your system meets these requirements:

Operating System: Any modern Linux distribution (Arch, Fedora, Debian, Ubuntu, openSUSE, etc.)
Shell: Bash or a compatible POSIX shell
Internet Connection: Required for downloading applications and scripts
curl: Pre-installed on most distributions

Running Linutil

Linutil runs directly from a single curl command — no installation required.

Stable Branch (Recommended)

curl -fsSL https://christitus.com/linux | sh

Dev Branch (Latest Features)

curl -fsSL https://christitus.com/linuxdev | sh

Note

The dev branch may contain untested features. Use the stable branch for day-to-day use.

Installing Linutil Locally

If you prefer a persistent local install, Linutil is available through several package managers.

Arch Linux (AUR)

# Using paru
paru -S linutil

# Using yay
yay -S linutil

# Stable pre-compiled binary
paru -S linutil-bin

openSUSE

sudo zypper install linutil

Cargo

cargo install linutil_tui

Note

Cargo installs require manual updates via cargo install --force linutil_tui, or use the built-in Linutil Updater script inside the tool.

CLI Arguments

View all available options:

linutil --help

Common Options

Flag	Description
`--config` / `-c`	Path to a TOML config file
`--skip-confirmation`	Skip confirmation prompts
`--size-bypass`	Bypass terminal size requirements

Navigating the TUI

Once Linutil launches, you'll see a tree-style menu on the left and a description panel on the right.

Keyboard Shortcuts

Key	Action
`↑` / `↓` or `j` / `k`	Move up/down in the list
`Enter` or `→`	Select / expand item
`←`	Collapse / go back
`Space`	Multi-select an item
`/`	Search/filter items
`q` or `Escape`	Quit / go back
`t`	Toggle multi-select mode

Linutil is organized into these main categories:

Applications Setup — Install popular Linux software
Gaming — Gaming dependencies, emulators, game configs
Security — Firewall setup and hardening
System Setup — Distro-specific configuration (Arch, Fedora, Debian, Ubuntu, etc.)
Utilities — Monitor control, printers, Bluetooth, WiFi, and more

Your First Steps

Here are recommended actions for new users:

1. Browse and Install Applications

Navigate to Applications Setup
Browse categories (browsers, developer tools, communication apps, etc.)
Select an application and press Enter to run the install script

2. Set Up Your Distro

Navigate to System Setup
Find your distribution (Arch, Fedora, Debian, Ubuntu)
Run distro-specific scripts like AUR helpers, RPM Fusion, or package updates

3. Configure Utilities

Navigate to Utilities
Set up monitors, manage Bluetooth/WiFi, or configure services

Troubleshooting First Run

Script Won't Download

If the curl command fails, check your internet connection or try:

curl -fsSL https://raw.githubusercontent.com/ChrisTitusTech/linutil/main/linutil.sh | sh

Permission Errors

Most scripts require sudo access. Linutil will prompt for your password when needed.

Terminal Size Warning

If you get a terminal size warning, resize your terminal to be larger, or use the --size-bypass flag:

curl -fsSL https://christitus.com/linux | sh -s -- --size-bypass

Next Steps

Application Setup — Learn about installing software
System Setup — Distro-specific configuration
Features & Utilities — Security, gaming, and utilities
Automation — Run Linutil with a config file
FAQ — Common questions and answers

4.1 KiB Raw Blame History