How caelestia-dots/scripts works
File structure
• Top‐level scripts:
• main.fish – the CLI dispatcher
• *.fish scripts (install/, toggles/, and standalone scripts) – implementations of each subcommand
• util.fish – shared utility functions
• completions/ – Fish completion definitions
• Patterns:
• Modular subcommands under folders (install/, toggles/, scheme/)
• A “plugin”-like system where each subdir groups scripts for one category
• Shared utilities and data used by multiple commands
• Mixed-language: Fish for CLI and orchestration; Python for more complex scheme logic
README for additional insights
• Confirms the CLI interface and available commands
• Installation is simply cloning the repo and running install/scripts.fish
a. Main components
• Fish Interpreter
• Entrypoint – main.fish (CLI parser & dispatcher)
• Subcommand modules:
– install/*
– toggles/*
– standalone scripts: screenshot.fish, record.fish, emoji-picker.fish, wallpaper.fish, clipboard.fish, clipboard-delete.fish, pip.fish
– scheme module: scheme/main.fish, gen-scheme.fish, gen-print-scheme.fish, autoadjust.py, score.py
• Shared utilities: util.fish
• Data store: data/ (config.json, emojis.txt, schemes/…)
• Completion definitions: completions/caelestia.fish
• External services & binaries: Hyprland, slurp, ffmpeg, fish shell, etc.
• User environment: PATH, ~/.local/bin
b. Relationships & interactions
• User invokes caelestia <command> → Fish interpreter loads main.fish
• main.fish parses the command name and arguments
• Dispatches to the corresponding script or function in install/, toggles/, scheme/, or standalone .fish files
• That script:
– Sources util.fish for shared functions
– If a scheme command, may spawn Python scripts (autoadjust.py, score.py) to process schemes, then returns results to Fish
– Invokes external binaries (e.g., slurp for screenshots, Hyprland commands for workspace actions)
– Optionally writes logs or updates files in the user’s home directory
• Fish completions script provides tab-completion for the CLI
c. Architectural patterns & design principles
• Modular “subcommand” structure – each feature is isolated in its own folder/script
• Shared library (util.fish) to avoid code duplication
• Command dispatcher (main.fish) implements the CLI façade pattern
• Layered approach: CLI → command module → util/data → external binaries
d. Key technologies & libraries
• Fish shell for scripting and CLI
• External CLI tools (Hyprland, ffmpeg, slurp, etc.)
• JSON for config (data/config.json)
Elements
• From user → Fish interpreter → main.fish
• From main.fish → subcommand scripts
• From scripts → util.fish and data/
• From scripts → external binaries
• From scheme.fish → Python scripts → back to Fish
• Python scripts in another
• Data files in a third
• External services/binaries in a fourth
Detailed breakdown
• Layer 1 (left): User’s terminal
• Layer 2: Fish interpreter → main.fish (CLI dispatcher)
• Layer 3: Branching into modules:
• install/
• toggles/
• scheme/ (with embedded Python processing)
• standalone scripts (screenshot.fish, record.fish, etc.)
• Layer 4: Common util.fish and data/
• Layer 5 (right): External tools and services
• Feedback loops where scripts read/write data, and where Python returns data to Fish