Documentation / Advanced Usage

Advanced Usage

Real workflows and customization points for people who already have Aphotic installed and want to push past the defaults. For basic setup, see Installation; for the full command list, see CLI Reference.

Custom Hyprland Config

~/.config/hypr/custom.lua is the file for your own Hyprland tweaks. install.sh backs it up and puts it back on every run, and aphotic update never overwrites it. It’s loaded last (require("custom") at the end of hyprland.lua), so it can override earlier settings.

Aphotic’s Hyprland config is Lua, not the old hyprland.conf syntax, so write binds the way keybinds.lua does. mainMod is local to keybinds.lua, so spell the modifier out:

-- ~/.config/hypr/custom.lua
hl.bind("SUPER + F12", hl.dsp.exec_cmd("kitty"), { description = "Another terminal" })
hl.bind("SUPER + SHIFT + T", hl.dsp.exec_cmd("kitty -e btop"), { description = "System monitor" })

Anything valid in hyprland.lua or keybinds.lua is valid here. Run aphotic reload --full afterwards so Hyprland re-reads its config.

Profile + Layer Combinations

A profile picks the base package set, layers add on top, and any combination is valid:

# Lean coding box
./install.sh --profile minimal --with dev

# Daily driver: full desktop, game-mode-ready, dev tools on top
./install.sh --profile full --with gaming,dev

# AI workbench: local model backend plus the agent tooling it unlocks
./install.sh --profile full --with ai

# Everything, including the default exploit bundle (recon+web+network)
./install.sh --profile full --with gaming,dev,ai,exploit --accept-exploit-disclaimer

Layers dedupe against the base and each other, so stacking several is always safe to try. See Profiles & Layers for what each one actually installs, and Security for the exploit layer’s disclaimer requirement.

Scripting the CLI

aphotic is a real dispatcher meant to be scripted against, not just typed interactively:

# Theme + wallpaper together
aphotic theme set gruvbox
aphotic wallpaper --random

# Drive the running shell over IPC (same as `qs -c aphotic ipc call ...`)
aphotic shell dashboard toggle
aphotic shell notifs clear
aphotic shell lock engage

# One-screen state, machine-readable
aphotic status --json

Notifications from scripts need nothing Aphotic-specific: plain notify-send lands in the shell’s notification popups.

Full flag reference for every subcommand: CLI Reference.

Theming

Custom themes, the wallust pipeline, and per-app integration details (Firefox, VS Code, GTK) all live on Theming — this page won’t duplicate that.

Backup and Recovery

Aphotic has two separate backup mechanisms — automatic installer snapshots (~/.config-backup/, restored by ./uninstall.sh) and the manual aphotic backup CLI (~/.local/state/aphotic/backups/). The full distinction and command reference is in Installation § Backup System; the short version for day-to-day use:

aphotic backup create --label before-experiment
aphotic backup list
aphotic backup revert <id>

aphotic backup revert snapshots your current state first, so a revert is itself always reversible.

Terminal Games

Three small games ship with the CLI, each persisting stats to ~/.local/state/aphotic/game-scores.json:

aphotic play snake
aphotic play hangman
aphotic play guess

Troubleshooting

For anything not covered above — install failures, theme not applying, keybindings not firing — see Troubleshooting and the FAQ first; both are kept current with real known issues rather than duplicated here.