Skip to content

Installer and CLI

Jump to bottom
P3DROVFX edited this page Oct 12, 2026 · 1 revision

Installer, Updates and the CLI

One script — setup-ii-p3drovfx.sh — installs the shell, updates it, switches it between forks and branches, installs optional feature packages, and diagnoses problems. After the first run it is linked into ~/.local/bin as ii-p3drovfx (and II-P3DROVFX, the fork's written name — same link, so both spellings work). Everything in it is also reachable from the shell: Settings → About & Updates has an update button, a branch and fork switcher, an optional-packages table and a "What's new" changelog.

The script only ever replaces ~/.config/quickshell/ii (the Quickshell config) and, if you agree, overlays the fork's ~/.config/hypr. Your own edits in ~/.config/hypr/custom/ and your config.json are protected by default.

Commands

ii-p3drovfx help                 # the full surface (bare `ii-p3drovfx` prints this too)
ii-p3drovfx install              # first-time setup: the base illogical-impulse dotfiles, then the fork on top
ii-p3drovfx apply                # (re)apply the Quickshell config only — the default for the script file itself
ii-p3drovfx update               # refresh the fork and branch you are already on
ii-p3drovfx switch -f mine -b main   # change fork and/or branch
ii-p3drovfx fork end4            # shorthand: switch --fork end4
ii-p3drovfx branch dev           # shorthand: switch --branch dev
ii-p3drovfx list-forks           # the fork presets
ii-p3drovfx list-branches [fork] # remote branches of a fork
ii-p3drovfx restart              # restart Quickshell (alias: run)
ii-p3drovfx doctor               # resolved paths, active fork/branch/commit, tooling
ii-p3drovfx version              # what is deployed (fork, branch, commit)
ii-p3drovfx deps [list|add|remove]   # optional feature packages
ii-p3drovfx hyprset <args>       # write one Hyprland key or animation
ii-p3drovfx hyprmerge <args>     # merge a Hyprland config into your local one
ii-p3drovfx remove-cli           # remove the symlinks

Fork presets: p3drovfx (also mine) — this repository, end4 — end-4/dots-hyprland, vynx (also upstream) — vaguesyntax/ii-vynx; or any GitHub URL. Each preset defaults to its main branch.

Options worth knowing

Option Meaning
-f, --fork <preset|url>, -b, --branch <name> Target
-l, --local <path> Deploy a local checkout (a fork clone, or an ii config dir) instead of GitHub. update will never guess a local path back: it refuses and prints the --local line to re-run
-y, --yes Answer every confirmation yes
--keep-config / --reset-config Whether ~/.config/illogical-impulse/config.json survives. Default: kept on updates and branch hops, reset on fork switches (a different fork has a different schema). A backup is always kept
--hypr / --no-hypr Overlay the fork's ~/.config/hypr (recommended — the shell is written against its binds and rules: Alt+Tab switcher, tiling assistant and Modes may not fully work with an older Hyprland config) or never ask
--backup / --no-backup Keep (default) or discard the replaced config
--force Redeploy even when already on the remote commit (otherwise update asks first)
--no-restart Leave Quickshell running
--rebuild-quickshell Rebuild Quickshell from source first
--skip-base-check Don't require illogical-impulse underneath
--ii-subdir <name> Override the ii* folder auto-detection in the clone
--log-file, --no-log, -v, -q, --ascii, --no-color Output control; the run log is ~/.local/state/ii-p3drovfx/setup.log

Options accept --flag=value as well as --flag value; everything after a bare -- goes to hyprset/hyprmerge. Old spellings (--no-confirm, --preserve-config, --update, --switch…) still work.

What install does

  1. Runs end-4's own ./setup for the base (illogical-impulse dotfiles) — never a copy kept in this repository — then deploys the fork's config on top. On Arch it then swaps the base installer's pinned quickshell for the AUR quickshell-git this fork targets, before any config lands (it asks first unless -y). The installer supports Arch, Fedora (COPR-aware), Gentoo and Nix (sdata/dist-*).
  2. Offers the fork's core packages (below).
  3. Installs the CLI links, restarts Quickshell and opens the Welcome app (Welcome App) once the shell answers. Every successful apply, install or switch opens it; update never does.

What a deployment does (update / switch / apply)

  1. The remote is fetched into a shallow cache under ~/.cache/ii-p3drovfx/repos; an update downloads only what changed. A cache that fails a check is deleted and fetched once more. update compares the remote commit with the deployed one first and asks before redeploying when they match.
  2. The new tree is staged, protected files are carried over (.env, user/generated/*.json, and the built Rust helpers with their build stamps: workspace_compactor, workspace_profile_manager, osk_autoshow, app_stats, touch_gestures, sni_watcher), and the swap is atomic with a rollback if anything fails — on any failure the previous config stays untouched. The replaced config is backed up under ~/.local/state/ii-p3drovfx/backups (last three kept).
  3. State files are written beside the config: .active-remote, .active-branch, .active-fork, .active-commit (and .active-local for --local deployments). The shell reads these to know what it is and whether it is behind.
  4. If you agreed, the fork's Hyprland files are overlaid on ~/.config/hypr except custom/ (which is yours) — hyprland/colors.lua and hyprlock/colors.conf are only seeded when missing, since matugen rewrites them on every wallpaper change.
  5. Quickshell is restarted (MALLOC_CONF=narenas:1 to keep memory down) and, for everything except update, the Welcome is opened.

Optional features: deps

The shell works without these; each turns one feature on. ii-p3drovfx deps prints the table and lets you pick; deps add calendar google-drive installs by id; deps remove … uninstalls only what deps itself installed (recorded in ~/.local/state/ii-p3drovfx). Settings → About & Updates shows the same table (scripts/deps/deps.py, which never installs anything itself — the terminal and sudo belong to the setup script). Which packages a feature needs on your distribution comes from defaults/dependencies.json; a package is "present" when a binary is on PATH, a Python module imports, or the package manager has it. AUR-only packages need yay or paru.

Id Installs Enables
calendar khal, vdirsyncer, python-icalendar [[Calendar and Timetable
google-drive rclone [[Drive backup
easyeffects easyeffects EasyEffects
phone, phone-camera KDE Connect, scrcpy, adb, DroidCam, v4l2loopback, mpv [[Phone Integration
fingerprint fprintd (+ pam-fprint-grosshack on Arch) [[Lock Screen
tailscale, vpn-proton, vpn-nord, vpn-warp the clients [[VPN and Tailscale
hotspot iw, dnsmasq, nftables Wi-Fi hotspot
screen-shaders hyprshade Screen filter shaders
video-wallpaper, wallpaper-engine, upscaling mpvpaper, socat, ffmpeg; Linux Wallpaper Engine; Upscayl [[Wallpaper System
dictation, ai-voice, ai-pdf voxtype; whisper; poppler Dictation, AI voice input, PDF attachments
docker docker Docker widget
openrgb openrgb + Python bindings RGB control
rust-helpers cargo Building the native helpers (gestures, tray, OSK, workspace, app stats) — see [[App Usage
preset-signin GitHub CLI [[Preset Store
updates-widget, clipboard-persist, dock-trash, appimage-icons, monitor-profiles pacman-contrib; wl-clip-persist; nautilus; squashfs-tools; hyprmon Their namesake features

Core packages (which, git, fd, zip/unzip, bluetoothctl, the Python GObject / D-Bus / Pillow bindings) are offered by install and update after asking.

In the shell: Settings → About & Updates

  • Update — Check now, the last-checked time and a badge on the bar (the "shell updates" indicator) when the remote has commits you don't. The check is one git ls-remote plus one GitHub API request; it never touches your config and nothing updates on its own. Automatic check (update.autoCheckInterval): disabled, every 10 minutes, hourly, daily (default) or weekly — plus once shortly after each shell start. Update now opens a terminal running the updater (so sudo and logs work), asks before applying, keeps your settings and restarts the shell. Also update Hyprland config (update.replaceHyprConfig, on) passes --hypr/--no-hypr.
  • What's new — the commits you don't have, grouped by kind (New features, fixes, look, internals) from type(scope): summary subjects, each linking to GitHub; when up to date, the last N commits of the branch. Summarize new commits with AI (update.aiSummary, off) asks the current model for a short plain-language summary once the update is aiSummaryMinCommits (10) commits deep; results are cached per commit range and never re-run on a reload. Local-only AI mode uses a local model.
  • Branch — stable (main, what has been tested) or dev (features as they land), for this fork only.
  • Fork — switching to another fork resets settings to its defaults and keeps a backup; the page documents the terminal command to come back (II-P3DROVFX fork p3drovfx).
  • Optional features — the deps table; Contributors, links to the repository, issues, docs and this wiki.

Troubleshooting

Symptom Try
Something looks off after an update ii-p3drovfx doctor (paths, active fork/branch/commit, tooling), then the log at ~/.local/state/ii-p3drovfx/setup.log
Roll back The previous ii folder is in ~/.local/state/ii-p3drovfx/backups/ (last three)
A helper reads "stale" after an update The built binaries are carried across updates; rebuild with scripts/rust-helpers.sh outdated / build <name>
update says "already up to date" --force to redeploy
Welcome doesn't open It only opens after apply/install/switch; run qs -c ii ipc call welcome open

Under the hood

Piece Role
setup-ii-p3drovfx.sh The script (CLI, UI layer, fork/branch logic, staging, rollback, Hyprland overlay)
update-fork.sh Thin compatibility stub
sdata/ The base installer data and per-distro dependency handling (dist-arch, dist-fedora, dist-gentoo, dist-nix)
defaults/dependencies.json, scripts/deps/deps.py The deps catalogue and planner
services/ShellUpdates.qml, ShellUpdateSummary.qml In-shell update probe and AI summary
modules/settings/configs/AboutConfig.qml About & Updates
scripts/rust-helpers.sh Rust helper build stamps and rebuild reporting

Related pages

← Back to Home

Clone this wiki locally