Aether

    ╔═══════════════════════════════════════════════════════════════╗
    ║                                                               ║
    ║      █████╗ ███████╗████████╗██╗  ██╗███████╗██████╗          ║
    ║     ██╔══██╗██╔════╝╚══██╔══╝██║  ██║██╔════╝██╔══██╗         ║
    ║     ███████║█████╗     ██║   ███████║█████╗  ██████╔╝         ║
    ║     ██╔══██║██╔══╝     ██║   ██╔══██║██╔══╝  ██╔══██╗         ║
    ║     ██║  ██║███████╗   ██║   ██║  ██║███████╗██║  ██║         ║
    ║     ╚═╝  ╚═╝╚══════╝   ╚═╝   ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝         ║
    ║                                                               ║
    ║               Declarative System Management CLI               ║
    ║                                                               ║
    ╚═══════════════════════════════════════════════════════════════╝

A declarative CLI for managing packages and system settings from a single aether.yaml.

Status: early work in progress (0.1.0). Commands, config format and scroll schema all still change without notice, and the scroll library is close to empty. Usable to try out, not to depend on.

macOS only in practice: installs go through Homebrew and mas, and settings are written with defaults.

Install

Not published to PyPI yet (the aether-cli name on PyPI belongs to an unrelated project). Install from source:

git clone https://github.com/Aethryl/Aether.git
cd Aether
uv sync --group test
python install_local.py
aether --help

Quick start

aether init    # scan the system and write aether.yaml
aether sync    # install what is missing and apply settings

Configuration

packages:
  - name: git
  - name: visual-studio-code
    prefer: brew_cask
  - name: htop
    prefer: brew_formula

settings:
  macos:
    com.apple.dock:
      autohide: true
      tilesize: 48
      show-recents: false
    com.apple.finder:
      AppleShowAllFiles: true
      ShowPathbar: true
    NSGlobalDomain:
      AppleShowAllExtensions: true
      KeyRepeat: 2

Settings domains and the full set of supported keys are documented in docs/SYSTEM_SETTINGS.md.

Install types

Type	Description
brew_formula	Homebrew command-line tools
brew_cask	Homebrew desktop applications
macstore	Mac App Store applications (via mas)
dmg	DMG installer packages
manual	Manual installation, tracked only

File locations

	State	Config	Scrolls
Default	~/.config/aether/state.json	~/.config/aether/aether.yaml	packaged scrolls
DEV_DIR=true	./state.json	./aether.yaml	./aether/data/scrolls/

Commands

Command	Description
aether init	Bootstrap aether.yaml from the current system
aether sync	Bring the system in line with the config
aether add <pkg>	Add a package to the config
aether settings	Apply system settings only (--list-common to list them)
aether validate-scroll <name>	Validate a scroll against its schema

Common options: --dry-run to preview, --verbose for detail, --skip-settings to sync packages only.

Development

uv sync --group test
pytest
pytest --cov=aether --cov-report=term-missing

Markers: unit, integration, cli, slow (pytest -m "not slow"). See tests/TESTING_OVERVIEW.md.

License

MIT, see LICENSE.