Documentation / CLI Reference
CLI Reference
Run
aphotic --helpfor the full, always-current list — commands are auto-discovered, so this page can’t drift silently for long, butaphotic --helpis the ground truth.
The command list below is generated from those headers by tools/ci/gen_cli_reference.py; the docs drift check on every PR to dev and main keeps it honest. Hand-written notes that headers can’t carry follow the list.
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
aphotic agent– Track AI coding-agent usage and feed the agent event streamaphotic agent usage-update– Parse the transcripts of every scan harness and write agent-usage.jsonaphotic agent harnesses– Merge harness descriptors from plugins and drop-ins into harnesses.jsonaphotic agent emit <event>– Write one validated v2 agent event through the hook writeraphotic agent run --harness NAME -- <command...>– Wrap a command with session_start and session_endaphotic diff– Report drift between aphotic.toml and what’s actually installed/running--json– Machine-readable drift report
aphotic doctor– Check dependencies and report version/config driftaphotic perf– Performance snapshot and budget check (GPU, shell, Hyprland)aphotic perf snapshot [--samples N=10] [--label TEXT]– Append an N-sample snapshot to history.jsonlaphotic perf budget [--from-history]– PASS/OVER check against perf-budget.json; exit 1 when any OVERaphotic perf history [--last N=10]– Table of recent snapshotsaphotic reload– Reload Aphotic shell modules, optionally the full session--full– Also reload Hyprland config--modules-only– Reload only quickshell modules (default)
aphotic runtime– Show surfaces, runtime context, resource posture and shell activityaphotic runtime back– Close whatever owns the keyboard on the focused screen[--json]– Print the raw JSON instead of the summary
aphotic shell– Start the quickshell daemon, or forward an IPC call to itaphotic shell <ipc-call> ...– Forward args toqs -c aphotic ipc call ...-d, --daemon– Start in daemon mode (backgrounded)
aphotic status– One-screen snapshot of profile, layers, plugins, services and version drift--json– Machine-readable snapshot
Config
aphotic bar– Set or cycle the bar layout, or set its corner style (full/capsule/dock/taskbar/minimal)aphotic bar style <full|capsule|dock|taskbar|minimal>– Set the bar layoutaphotic bar corners <sharp|soft|round>– Set the bar corner styleaphotic bar cycle– Cycle to the next layoutaphotic config– Get, set, or edit Aphotic shell configurationaphotic config get <key>– Print a config value (dot.path notation)aphotic config set <key> <value>– Write a value and trigger a reloadaphotic config edit– Open APHOTIC_CONFIG_FILE in $EDITOR, validate on saveaphotic context– Show or switch the runtime context (default/focus/dev/game/present)aphotic context list– List contexts, the active one starredaphotic context current– Print the active contextaphotic context set <name>– Switch contextaphotic context revert– Back to the context before the last switchaphotic displaymanager– Report or switch the active display manager (sddm/greetd)aphotic displaymanager status– Report which display manager is enabled/active (default)aphotic displaymanager switch <sddm|greetd> [--confirm-tested]– Switch the active display manageraphotic greeter– Sync the greetd greeter’s palette snapshot and wallpaperaphotic greeter sync– Copy the current palette/wallpaper into the greeter snapshot (default)aphotic plugin– List, install, enable/disable, or remove pluginsaphotic plugin list [--remote] [--json] [--category <name>]– List installed (or available-remote) pluginsaphotic plugin install <name> [--link]– Install a plugin from APHOTIC_PLUGINS_REPOaphotic plugin enable|disable <name>– Toggle a plugin without uninstalling itaphotic plugin remove <name>– Uninstall a pluginaphotic plugin validate <dir>– Check a plugin folder’s manifest and files before installing itaphotic plugin api [--json]– The shell runtime API version and the calls a plugin may declareaphotic plugin trust-security-index– Opt into the separate security-category plugin indexaphotic plugin untrust-security-index– Revoke that opt-in (hides security-category plugins again)aphotic scheme– Set the active colour schemeaphotic scheme set -n <name>– Apply a named schemeaphotic sddm– Sync the SDDM login background, set a custom greetingaphotic sddm sync– Copy the current wallpaper into the SDDM theme (default)aphotic sddm greeting [text]– Set (or print, with no text) the login screen’s greetingaphotic theme– List, set, cycle, or download themesaphotic theme list [--remote] [--json]– List downloaded (or available-remote) themesaphotic theme set <name>– Apply a theme by nameaphotic theme next|prev– Cycle to the next/previous themeaphotic theme download <name>– Download a theme from APHOTIC_THEMES_REPOaphotic theme update <name>|--all– Refresh a downloaded theme’s files from the repoaphotic theme remove <name>– Delete a downloaded (non-core) themeaphotic theme refresh-gtk– Re-deploy the GTK4/libadwaita stylesheet and restart idle GTK4 appsaphotic theme ensure-default– Apply the install-time theme if none is set yet (startup.lua only)aphotic vpn– Connect/disconnect an OpenVPN profileaphotic vpn status– Show every active VPN connection, across providersaphotic vpn list [--json]– List VPN providers and their connectionsaphotic vpn connect [path]– Connect, using the given .ovpn or the saved config pathaphotic vpn connect --provider <id> [name]– Connect through one provider adapteraphotic vpn disconnect [--provider <id> [name]]– Disconnectaphotic vpn autostart– Connect only if Settings.vpnAutoConnect is true (called from startup.lua)aphotic wallpaper– Set, randomize, or cycle the wallpaperaphotic wallpaper fetch [theme..] [--all] [--dry-run]– Download a theme’s wallpapers from installed packsaphotic wallpaper packs– List installed wallpaper packs and what they coveraphotic wallpaper index [theme..]– Record image sizes so ultrawide screens get ultrawide images-f, --file <path>– Set a specific wallpaper (must live under a theme folder)--random– Pick a random wallpaper from the active theme--next– Advance to the next wallpaper in the active theme, in order
Lifecycle
aphotic backup– Snapshot, list, revert, or prune dotfile backupsaphotic backup create [--label <name>]– Snapshot current dotfiles stateaphotic backup list– List available snapshotsaphotic backup revert [--yes] <id>– Restore a specific snapshotaphotic backup clean [--keep N]– Prune old snapshots (default keep 10)aphotic packages– Advisory pending-update check (official + AUR), never applies anythingaphotic packages check [--notify]– Print (or notify) pending official/AUR update countsaphotic packages set-timer <off|daily|weekly>– Enable/disable/reschedule aphotic-package-check.timeraphotic reconcile– Converge installed plugins to match aphotic.toml’s [plugins] listaphotic reconcile (no args)– Dry run: show what would change--apply– Enable/disable plugins to match aphotic.toml (auto-snapshots first)--json– Machine-readable report
aphotic recovery– Diagnose repeated shell startup failures and recover from themaphotic recovery status [--json]– What failed, how often, and what is suspectedaphotic recovery present– Show the recovery surface (or a terminal menu)aphotic recovery menu– The terminal menu on its ownaphotic recovery apply <action> | disable-suspect | safe-mode | restore-last– continueaphotic recovery record <r> <s>– Record a unit exit (called by aphotic-shell.service)aphotic recovery clear– Forget the recorded failuresaphotic report– Scaffold and render pentest/CTF engagement reportsaphotic report new <name>– Create a new engagement directory with a report templateaphotic report list– List existing engagementsaphotic report render <name>– Render an engagement’s report.md to PDF via pandocaphotic restore– Deploy upstream Aphotic dotfiles (populate/overwrite semantics)--populate– Only write files that don’t already exist (safe, default)--overwrite– Back up current files then overwrite with defaults
aphotic rollback– Restore the most recent pre-reconcile snapshot--yes– Skip the confirmation prompt
aphotic safemode– Hold every plugin back so the shell starts as core onlyaphotic safemode on [--reason <text>]– Hold plugins back and note whyaphotic safemode off– Load plugins againaphotic safemode status– Whether safe mode is on, and whyaphotic sync– Config-only update: re-deploy config, refresh plugins, report missing packages--check– Report only. Nothing is pulled, deployed or restarted--json– Machine-readable report, for Settings -> About--no-pull– Skip the git pull, sync whatever is checked out
aphotic update– Update the dots repo and re-deploy config--dots-only– Only git-pull, skip restore + reload--channel <stable|edge>– Override the saved channel for this update
aphotic whatsnew– Show a release-notes banner if the installed version changed--force– Show the current version’s banner even if already seen
AI
aphotic ai– Check AI backend status, switch the active provider profileaphotic ai status– Show reachability of Claude Code / Ollama, loaded modelsaphotic ai profile <provider>[:<model>]– Switch the AI panel’s active provider (ollama/claude/gemini/chatgpt), optionally the ollama model
Build
aphotic iso– Build a Aphotic live or installer ISOaphotic iso build --live– Build a bootable live ISOaphotic iso build --installer– Build an installer ISO
Fun
aphotic play– Play terminal games like hangman, snake, and number guessingaphotic play hangman– Play hangman gameaphotic play snake– Play snake gameaphotic play guess– Play number guessing game
Build note. The iso build command exists; the ISO doesn’t yet. It 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.
AI note. 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.
Fun note. 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).
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
- Supported Features — where the CLI fits among everything else
- Command Center — the AI Chat tab this CLI’s
aicommands back - Bar Styles — the full per-style option reference behind
aphotic bar