Documentation / CLI Reference

CLI Reference

Run aphotic --help for the full, always-current list — commands are auto-discovered, so this page can’t drift silently for long, but aphotic --help is the ground truth.

aphotic is a real dispatcher, not a wrapper script: bin/aphotic sources one file per subcommand from lib/aphotic/commands/cmd_<name>.sh, each defining a single aphotic_cmd_<name>() function. Adding a subcommand is adding a file — the dispatcher, and aphotic --help’s grouped output, are both built entirely from @cmd/@cmd.desc/@cmd.group/@cmd.opt header annotations in that file. Commands with their own sub-verbs (like play) instead live in a commands/<name>/ subdirectory, one file per verb, sourced by the top-level cmd_<name>.sh — this keeps the sub-verb files from being auto-discovered as phantom top-level commands.

Core

Command	Purpose
`aphotic shell [-d\\|--daemon]`	Starts `qs -c aphotic` (the Quickshell daemon); `-d` backgrounds it. Any other args forward straight through to `qs -c aphotic ipc call ...`.
`aphotic reload [--full\\|--modules-only]`	Reloads Quickshell modules; `--full` also runs `hyprctl reload`. `--modules-only` is the default.
`aphotic doctor`	Dependency, path, and layer/plugin coherence checks, plus checkout version drift — the same output Settings → System’s live doctor panel shows. The drift check compares against the cached `origin/main` ref only when the checkout is on the `main` branch; a stable install (detached at a release tag) or an edge one (on `dev`) reports the branch instead of a count.
`aphotic status [--json]`	One-screen snapshot: profile, layers, plugin ok/missing/extra/disabled counts (when `aphotic.toml` declares `[plugins]`), checkout drift, daemon/display-manager state.
`aphotic diff [--json]`	Full drift report against `aphotic.toml` — missing packages, per-plugin missing/extra, daemon/display-manager state, checkout drift — plus a changes-required count. Read-only; `aphotic reconcile` acts on it.
`aphotic perf snapshot [--samples N] [--label TEXT]`	Samples the desktop’s cost (GPU, the shell, Hyprland) N times (default 10) and appends the result to the perf history.
`aphotic perf budget [--from-history]`	PASS/OVER check against the perf budget; exits 1 when anything is over.
`aphotic perf history [--last N]`	Table of recent snapshots (default 10).
`aphotic runtime [--json]`	What the shell has on screen right now: open surfaces, the runtime context, resource posture and shell activity.
`aphotic runtime back`	Close whatever owns the keyboard on the focused screen.
`aphotic agent usage-update`	Parses local Claude Code/Codex transcripts and writes `agent-usage.json` — what the bar’s agent icon’s usage panel reads. Run automatically every 15 minutes by a systemd timer when the `ai` layer is on; see Agentic Workflows.

Config

Command	Purpose
`aphotic config get <key>`	Print a config value by dot-path.
`aphotic config set <key> <value>`	Write a value and trigger a reload.
`aphotic config edit`	Open `APHOTIC_CONFIG_FILE` in `$EDITOR`, validated on save.
`aphotic theme list [--remote] [--json]`	List installed themes, or browse the remote index.
`aphotic theme set <name>`	Apply a theme by name.
`aphotic theme next` / `prev`	Cycle themes — also bound to `Super`+`,`/`.`.
`aphotic theme download <name>`	Download a community theme from the remote index.
`aphotic theme update <name>\\|--all`	Refresh a downloaded theme’s files from the repo.
`aphotic theme remove <name>`	Delete a downloaded (non-core) theme.
`aphotic theme refresh-gtk`	Re-deploy the GTK4/libadwaita stylesheet and restart idle GTK4 apps. Runs on every theme change; this is the manual trigger.
`aphotic theme ensure-default`	Apply the install-time theme if none is set yet (startup use).
`aphotic scheme set -n <name>`	Apply a named color scheme.
`aphotic wallpaper -f/--file <path>`	Set a specific wallpaper (must live under a theme folder).
`aphotic wallpaper --random`	Pick a random wallpaper from the active theme.
`aphotic wallpaper --next`	Advance to the next wallpaper in the active theme, in order.
`aphotic bar style <full\\|dock\\|taskbar\\|minimal\\|capsule>`	Switch bar style. See Bar Styles.
`aphotic bar cycle`	Cycle to the next bar style — also bound to `Super`+`Ctrl`+`Shift`+`B`. The Full style’s skin (Pill / Square / Signal line) has no `bar` subcommand; use Settings → Bar or `aphotic shell bar setSkin <pill\\|square\\|signal>`.
`aphotic context [list\\|current\\|set <name>\\|revert]`	Show or switch the runtime context: `default`, `focus`, `dev`, `game` or `present`. `revert` goes back to the context before the last switch.
`aphotic plugin list [--remote] [--refresh] [--json] [--category <name>]`	List installed plugins, or browse the remote index. The index is cached after the first fetch; `--refresh` fetches it again.
`aphotic plugin install <name> [--link]`	Install a plugin (`--link` symlinks instead of cloning, for local plugin dev).
`aphotic plugin update <name>`	Refresh a plugin’s files from the repo.
`aphotic plugin enable\\|disable <name>`	Toggle a plugin without uninstalling it.
`aphotic plugin remove <name>`	Uninstall a plugin.
`aphotic plugin trust-security-index` / `untrust-security-index`	Opt in (or back out) of the separate, untrusted-by-default security-category plugin index.
`aphotic plugin api [--json]`	The shell runtime API version this build speaks and the calls a plugin may declare in its manifest’s `[api]` table.
`aphotic plugin validate <dir>`	Check a plugin folder before installing it — manifest fields, every declared surface has a matching `[ui.*]` section and vice versa, every referenced component/script/hook path actually exists. Runs against the folder only, nothing installed.
`aphotic vpn status`	Show whether the managed OpenVPN process is up.
`aphotic vpn connect [path]`	Connect, using the given `.ovpn` or the saved config path.
`aphotic vpn disconnect`	Disconnect.
`aphotic vpn autostart`	Connect only if `Settings.vpnAutoConnect` is true — called from startup, not meant to be run by hand.
`aphotic sddm sync`	Copy the current wallpaper into the SDDM theme and rewrite its background line. Needs passwordless `sudo` for `cp`/`sed` to run automatically; otherwise warns and no-ops (see the commands README in the repo for the sudoers drop-in).
`aphotic sddm greeting [text]`	Set (or print, with no text) the login screen’s greeting.
`aphotic displaymanager [status\\|switch <sddm\\|greetd> --confirm-tested]`	Report the active display manager, or switch between SDDM and greetd (the Aphotic greeter). The installer makes the greeter the login screen; `switch sddm --confirm-tested` is the way back, and that choice sticks through later installs.
`aphotic greeter [sync]`	Copy the active palette and wallpaper into the Aphotic greeter’s snapshot. Runs on every theme or wallpaper change.

Lifecycle

Command	Purpose
`aphotic backup create [--label <name>]`	Snapshot the current dotfiles state.
`aphotic backup list`	List available snapshots.
`aphotic backup revert [--yes] <id>`	Restore a specific snapshot, after snapshotting the current state (`--yes` skips the confirmation).
`aphotic backup clean [--keep N]`	Prune old snapshots (default: keep 10).
`aphotic restore [--populate\\|--overwrite]`	Deploy Aphotic’s own default configs on top of (or into) your live config. `--populate` (default) only fills in files that don’t exist yet; `--overwrite` backs up first, then overwrites.
`aphotic update [--dots-only] [--channel <stable\\|edge>]`	Follows the saved release channel: `stable` checks out the newest release tag, `edge` switches to `dev` and pulls. Then `restore --populate` → `reload --full`. `--populate` never overwrites, so the Quickshell config (a copy, not a symlink) stays on the old version; run `./install.sh --config-only` for that. `--dots-only` stops after the git step; `--channel` overrides the saved channel once. See Installation → Updating.
`aphotic sync [--check\\|--json\\|--no-pull]`	Config-only update (the Sync button in Settings → About): `git pull --ff-only`, `./install.sh --config-only`, refresh plugins, and report missing profile packages without installing them. `--check` only reports state. The pull needs a branch, so on a stable install (detached at a tag) use `--no-pull`, or `./install.sh --config-only`, which moves to the newest tag itself.
`aphotic reconcile [--apply] [--json]`	Converge installed plugins to match `aphotic.toml`’s `[plugins]` list. Dry run by default, printing what would change; `--apply` enables/disables plugins to match (never installs one it doesn’t have), snapshotting first so `aphotic rollback` can undo it.
`aphotic rollback [--yes]`	Restore the most recent pre-reconcile snapshot — a thin wrapper over `aphotic backup revert`.
`aphotic whatsnew [--force]`	Shows the release-notes banner (via `hyprctl notify`) if the installed version changed since it was last shown. `--force` shows the current version’s banner even if already seen.
`aphotic report new <name>`	Scaffold a new pentest/CTF engagement directory with a report template.
`aphotic report list`	List existing engagements.
`aphotic report render <name>`	Render an engagement’s `report.md` to PDF via `pandoc`.
`aphotic safemode <on\\|off\\|status>`	Hold all plugins back so the core shell can start, then restore normal loading when ready.
`aphotic recovery <status\\|present\\|menu\\|apply\\|clear>`	Diagnose repeated shell startup failures and offer recovery actions without requiring a running shell.

AI

Command Purpose

aphotic ai status Reachability check for the claude CLI and Ollama, plus a list of Ollama’s currently loaded models.

aphotic ai profile <provider>[:<model>] Switch the AI panel’s active provider (ollama, claude, codex, gemini, chatgpt; a provider the panel doesn’t offer, such as codex, falls back to the first one it does) from the terminal — writes straight to ~/.config/aphotic/ai-config.json, which a running shell watches live, no reload needed. The :<model> suffix only means something for ollama (e.g. aphotic ai profile ollama:llama3.1:8b); it’s quietly ignored for any other provider.

Command	Purpose
`aphotic ai status`	Reachability check for the `claude` CLI and Ollama, plus a list of Ollama’s currently loaded models.
`aphotic ai profile <provider>[:<model>]`	Switch the AI panel’s active provider (`ollama`, `claude`, `codex`, `gemini`, `chatgpt`; a provider the panel doesn’t offer, such as `codex`, falls back to the first one it does) from the terminal — writes straight to `~/.config/aphotic/ai-config.json`, which a running shell watches live, no reload needed. The `:<model>` suffix only means something for `ollama` (e.g. `aphotic ai profile ollama:llama3.1:8b`); it’s quietly ignored for any other provider.

aphotic ai fit (llmfit model recommendations) moved out of core into a plugin; once a plugin adds a subcommand to ai, aphotic ai --help lists it.

See Command Center for how the AI Chat tab and Settings → AI panel use this backend.

Build

The command exists; the ISO doesn’t yet. aphotic iso build errors out on purpose until a real archiso profile (packages.x86_64, airootfs/, profiledef.sh) exists at iso/profile/ — nobody has authored one. See Release Notes/Project Status for whether that’s changed.

Command	Purpose
`aphotic iso build --live`	Build a bootable live ISO via `mkarchiso`, once a real profile exists.
`aphotic iso build --installer`	Build an installer ISO, once a real profile exists.

Packages

Command	Purpose
`aphotic packages check [--notify]`	Advisory-only pending-update check (official repos via `checkupdates`, AUR via your helper’s `-Qua`) — never applies anything. `--notify` delivers it as a Hyprland notification instead of stdout.
`aphotic packages set-timer <off\\|daily\\|weekly>`	Enable/disable/reschedule the background version of the check above (`aphotic-package-check.timer`) — what Settings → System’s pending-update-check control calls.

Fun — terminal games

aphotic play runs three small terminal games, written in bash with no external dependencies. All three persist stats to one shared file, ~/.local/state/aphotic/game-scores.json (one top-level object per game).

Command	What it is
`aphotic play hangman`	Classic word-guessing — guess letters before running out of wrong guesses. Tracks a win/loss record.
`aphotic play snake`	Classic snake — WASD to steer, eat food to grow, board sizes to your actual terminal, speeds up as your score climbs. Avoid walls and yourself. Tracks a high score.
`aphotic play guess`	Number guessing — the game picks a number 1–100, you guess and it tells you higher/lower. Tracks your best (fewest) attempts.

Extending

If you’re adding a subcommand: copy an existing cmd_*.sh as a starting point, keep the cmd_foo.sh → aphotic_cmd_foo() naming convention, and use the shared helpers in globalcontrol.sh (aphotic_log/ok/warn/err, aphotic_confirm, aphotic_require, aphotic_json_get/set) rather than reimplementing them. A command with its own sub-verbs goes in commands/<name>/*.sh (no cmd_ prefix on those files) instead of one flat cmd_<name>.sh. Full conventions: CONTRIBUTING.md and commands/README.md in the main repo.