veilor-os/docs/CLI.md

veilor-os CLI

User-facing commands shipped at /usr/local/bin/. Every veilor-* tool is a small bash script — readable, auditable, no compiled bits.

---

veilor-update

Wraps dnf upgrade --refresh -y plus flatpak update -y. One command for "give me everything new". Mirrors the operator habit of always patching both DNF and Flatpak — neither is sufficient on its own.

Usage:

veilor-update

What it does:

1. Pings mirrors.fedoraproject.org. If unreachable, exits early with a helpful message instead of letting dnf spin and time out.
2. Runs sudo dnf upgrade --refresh -y and tees output for live progress.
3. Counts packages from the Upgraded:/Installed: lines of dnf output and reports the total.
4. If flatpak is installed, runs flatpak update -y.
5. Compares running kernel to the newest installed kernel and prints a reboot suggestion if they differ.

Exit codes:

Code	Meaning
0	dnf and flatpak both succeeded
1	dnf upgrade failed
2	flatpak failed (dnf still ran successfully)
3	no network — pre-check failed

Example:

=== veilor-update: refreshing DNF metadata + applying updates ===
... dnf output ...
=== veilor-update: updating flatpaks ===
... flatpak output ...
=== veilor-update: complete ===
  Packages updated : 47
  Running kernel   : 6.19.14-200.fc43.x86_64
  Newest kernel    : 6.19.16-200.fc43.x86_64 (reboot suggested)

If gum is on the system, status banners render with colour and a spinner; otherwise plain ASCII output. Either form is identical in substance.

---

veilor-doctor

Read-only diagnostic. Walks the v0.2 hardening checklist and reports drift. Never modifies system state — fixes are a separate, deliberate step.

Usage:

veilor-doctor              # full coloured table
veilor-doctor --quiet      # PASS/FAIL summary only
veilor-doctor --json       # machine-readable JSON

Sections checked:

Section	Checks
System	hostname, OS, kernel, uptime
Hardening	SELinux mode, USBGuard active, fail2ban active, firewalld zone, kernel.yama.ptrace_scope, kernel.kptr_restrict
Disk	LUKS device + cipher, btrfs subvolume count, root free space
Network	NetworkManager state, default route, DNS servers, public IP
Updates	last dnf history entry, pending update count via dnf check-update
veilor	state of veilor-firstboot.service + veilor-modules-lock.service

Exit codes:

Code	Meaning
0	all checks passed
1	one or more checks failed
2	bad CLI flag

Example output:

── System ──
  [OK]   hostname             veilor
  [OK]   os                   veilor-os
  [OK]   kernel               6.19.14-200.fc43.x86_64
  [OK]   uptime               up 3 hours, 21 minutes

── Hardening ──
  [OK]   selinux              Enforcing
  [OK]   usbguard             active
  [OK]   fail2ban             active
  [OK]   firewalld_zone       drop
  [OK]   ptrace_scope         2
  [OK]   kptr_restrict        2

── Disk ──
  [OK]   luks                 dm-0: aes-xts-plain64
  [OK]   btrfs                4 subvolume(s)
  [OK]   root_free            72G free / 234G (32% used)

19 checks passed.

veilor-doctor --json emits a single-line JSON object with pass, fail, and checks keys. Suitable for piping into a monitoring agent.

---

See also

• veilor-power — switch tuned profile (save / mid / perf)
• veilor-firstboot — root-owned, runs once on first boot
• veilor-installer — TTY1 TUI installer (live ISO only)