Skip to content

CLI Reference

Jump to bottom
Trevin edited this page Oct 17, 2026 · 10 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.

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 stream
  • aphotic agent usage-update -- Parse local Claude/Codex transcripts and write agent-usage.json
  • aphotic agent harnesses -- Merge harness descriptors from plugins and drop-ins into harnesses.json
  • aphotic agent emit <event> -- Write one validated v2 agent event through the hook writer
  • aphotic agent run --harness NAME -- <command...> -- Wrap a command with session_start and session_end
  • aphotic 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 drift
  • aphotic perf -- Performance snapshot and budget check (GPU, shell, Hyprland)
  • aphotic perf snapshot [--samples N=10] [--label TEXT] -- Append an N-sample snapshot to history.jsonl
  • aphotic perf budget [--from-history] -- PASS/OVER check against perf-budget.json; exit 1 when any OVER
  • aphotic perf history [--last N=10] -- Table of recent snapshots
  • aphotic 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 activity
  • aphotic 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 it
  • aphotic shell <ipc-call> ... -- Forward args to qs -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 layout
  • aphotic bar corners <sharp|soft|round> -- Set the bar corner style
  • aphotic bar cycle -- Cycle to the next layout
  • aphotic config -- Get, set, or edit Aphotic shell configuration
  • aphotic config get <key> -- Print a config value (dot.path notation)
  • aphotic config set <key> <value> -- Write a value and trigger a reload
  • aphotic config edit -- Open APHOTIC_CONFIG_FILE in $EDITOR, validate on save
  • aphotic context -- Show or switch the runtime context (default/focus/dev/game/present)
  • aphotic context list -- List contexts, the active one starred
  • aphotic context current -- Print the active context
  • aphotic context set <name> -- Switch context
  • aphotic context revert -- Back to the context before the last switch
  • aphotic 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 manager
  • aphotic greeter -- Sync the greetd greeter's palette snapshot and wallpaper
  • aphotic greeter sync -- Copy the current palette/wallpaper into the greeter snapshot (default)
  • aphotic plugin -- List, install, enable/disable, or remove plugins
  • aphotic plugin list [--remote] [--json] [--category <name>] -- List installed (or available-remote) plugins
  • aphotic plugin install <name> [--link] -- Install a plugin from APHOTIC_PLUGINS_REPO
  • aphotic plugin enable|disable <name> -- Toggle a plugin without uninstalling it
  • aphotic plugin remove <name> -- Uninstall a plugin
  • aphotic plugin validate <dir> -- Check a plugin folder's manifest and files before installing it
  • aphotic plugin api [--json] -- The shell runtime API version and the calls a plugin may declare
  • aphotic plugin trust-security-index -- Opt into the separate security-category plugin index
  • aphotic plugin untrust-security-index -- Revoke that opt-in (hides security-category plugins again)
  • aphotic scheme -- Set the active colour scheme
  • aphotic scheme set -n <name> -- Apply a named scheme
  • aphotic sddm -- Sync the SDDM login background, set a custom greeting
  • aphotic 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 greeting
  • aphotic theme -- List, set, cycle, or download themes
  • aphotic theme list [--remote] [--json] -- List downloaded (or available-remote) themes
  • aphotic theme set <name> -- Apply a theme by name
  • aphotic theme next|prev -- Cycle to the next/previous theme
  • aphotic theme download <name> -- Download a theme from APHOTIC_THEMES_REPO
  • 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
  • aphotic theme ensure-default -- Apply the install-time theme if none is set yet (startup.lua only)
  • aphotic vpn -- Connect/disconnect an OpenVPN profile
  • aphotic vpn status -- Show every active VPN connection, across providers
  • aphotic vpn list [--json] -- List VPN providers and their connections
  • aphotic vpn connect [path] -- Connect, using the given .ovpn or the saved config path
  • aphotic vpn connect --provider <id> [name] -- Connect through one provider adapter
  • aphotic vpn disconnect [--provider <id> [name]] -- Disconnect
  • aphotic vpn autostart -- Connect only if Settings.vpnAutoConnect is true (called from startup.lua)
  • aphotic wallpaper -- Set, randomize, or cycle the wallpaper
    • -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 backups
  • aphotic backup create [--label <name>] -- Snapshot current dotfiles state
  • aphotic backup list -- List available snapshots
  • aphotic backup revert [--yes] <id> -- Restore a specific snapshot
  • aphotic backup clean [--keep N] -- Prune old snapshots (default keep 10)
  • aphotic packages -- Advisory pending-update check (official + AUR), never applies anything
  • aphotic packages check [--notify] -- Print (or notify) pending official/AUR update counts
  • aphotic packages set-timer <off|daily|weekly> -- Enable/disable/reschedule aphotic-package-check.timer
  • aphotic reconcile -- Converge installed plugins to match aphotic.toml's [plugins] list
  • aphotic 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 them
  • aphotic recovery status [--json] -- What failed, how often, and what is suspected
  • aphotic recovery present -- Show the recovery surface (or a terminal menu)
  • aphotic recovery menu -- The terminal menu on its own
  • aphotic recovery apply <action> | disable-suspect | safe-mode | restore-last -- continue
  • aphotic recovery record <r> <s> -- Record a unit exit (called by aphotic-shell.service)
  • aphotic recovery clear -- Forget the recorded failures
  • aphotic report -- Scaffold and render pentest/CTF engagement reports
  • aphotic report new <name> -- Create a new 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 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 only
  • aphotic safemode on [--reason <text>] -- Hold plugins back and note why
  • aphotic safemode off -- Load plugins again
  • aphotic safemode status -- Whether safe mode is on, and why
  • aphotic 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 profile
  • aphotic ai status -- Show reachability of Claude Code / Ollama, loaded models
  • aphotic 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 ISO
  • aphotic iso build --live -- Build a bootable live ISO
  • aphotic iso build --installer -- Build an installer ISO

Fun

  • aphotic play -- Play terminal games like hangman, snake, and number guessing
  • aphotic play hangman -- Play hangman game
  • aphotic play snake -- Play snake game
  • aphotic 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

Clone this wiki locally