Skip to content

CLI Reference

Jump to bottom
Trevin edited this page Sep 28, 2026 · 7 revisions

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.

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.

See also

Clone this wiki locally