Skip to content

cli.md

Latest commit

 

History

History
545 lines (373 loc) · 12.8 KB

cli.md

File metadata and controls

545 lines (373 loc) · 12.8 KB
Raw

Command Line Interface

Aether provides a full CLI for scripting, automation, and headless theme management.

Quick Reference

# List saved themes
aether --list-blueprints

# Apply a saved theme
aether --apply-blueprint "my-theme"

# Generate theme from an image wallpaper
aether --generate ~/Wallpapers/sunset.jpg

# Import Base16 color scheme
aether --import-base16 ~/themes/dracula.yaml

# Import colors.toml (omarchy/ethereal format)
aether --import-colors-toml ~/themes/colors.toml

Commands

List Blueprints

List all saved blueprint themes:

aether --list-blueprints

Output shows theme names and timestamps.

Apply Blueprint

Apply a saved theme by name:

aether --apply-blueprint "theme-name"

This loads the blueprint and applies all configurations without opening the GUI.

Generate Theme

Extract colors from a wallpaper and apply as theme:

aether --generate /path/to/wallpaper.jpg

Options:

Option Description
--light-mode Generate light theme instead of dark
--extract-mode MODE Color extraction algorithm (see below)
--no-apply Generate templates only, don't activate theme
--output PATH Custom output directory (use with --no-apply)
--icon-theme automatic|ID Keep color-matched Yaru or write an explicit safe icon-theme directory ID

Extraction Modes:

  • normal (default) - Balanced extraction
  • monochromatic - Single-hue variations
  • analogous - Adjacent colors on color wheel
  • pastel - Soft, muted colors
  • material - Google Material-inspired
  • colorful - High saturation, vibrant
  • muted - Desaturated, subtle
  • bright - High brightness colors

Examples:

# Light theme with pastel colors
aether --generate ~/wallpaper.jpg --light-mode --extract-mode pastel

# Vibrant colorful theme
aether --generate ~/wallpaper.jpg --extract-mode colorful

# Generate templates without applying (no symlinks, no theme activation)
aether --generate ~/wallpaper.jpg --no-apply

# Generate to custom directory for use with external scripts
aether --generate ~/wallpaper.jpg --no-apply --output ~/my-themes/generated

# Generate with a specific installed icon theme (installation is not required on this machine)
aether --generate ~/wallpaper.jpg --no-apply --icon-theme Papirus-Dark

Omitting --icon-theme, or passing --icon-theme automatic, preserves Aether's existing palette-derived Yaru behavior. A safe explicit ID is written exactly even when it is not installed locally, so portable blueprints keep their intent. Excluding the Icons target still takes precedence and omits icons.theme.

Import Blueprint

Import a theme from URL or local file:

aether --import-blueprint "https://example.com/blueprint.json"
aether --import-blueprint "/path/to/theme.json"

Options:

Option Description
--auto-apply Apply immediately after importing

Example:

# Import and apply in one command
aether --import-blueprint "https://example.com/blueprint.json" --auto-apply

Import Base16 Scheme

Import a Base16 color scheme:

aether --import-base16 /path/to/scheme.yaml

Options:

Option Description
--wallpaper FILE Include wallpaper with the theme
--light-mode Generate light theme variant

Examples:

# Import Base16 scheme
aether --import-base16 ~/themes/dracula.yaml

# Import with wallpaper
aether --import-base16 ~/themes/nord.yaml --wallpaper ~/wallpaper.jpg

# Import as light theme
aether --import-base16 ~/themes/solarized.yaml --light-mode

Base16 schemes are available from tinted-theming/schemes (250+ schemes).

See Base16 documentation for format details and color mapping.

Import Colors.toml

Import a flat colors.toml file (compatible with omarchy/ethereal themes):

aether --import-colors-toml /path/to/colors.toml

Options:

Option Description
--wallpaper FILE Include wallpaper with the theme
--light-mode Generate light theme variant

Examples:

# Import colors.toml
aether --import-colors-toml /usr/share/omarchy/themes/ethereal/colors.toml

# Import with wallpaper
aether --import-colors-toml ~/themes/colors.toml --wallpaper ~/wallpaper.jpg

The colors.toml format uses a flat structure with color0-color15, plus extended colors:

accent = "#7d82d9"
cursor = "#ffcead"
foreground = "#ffcead"
background = "#060B1E"
selection_foreground = "#060B1E"
selection_background = "#ffcead"
color0 = "#060B1E"
color1 = "#ff6188"
# ... color2-color14
color15 = "#ffcead"

Omarchy Shell Selectors

Wallpaper and blueprint selectors run as native omarchy-shell plugins rather than CLI widget modes:

omarchy-shell shell toggle aether.wallpapers '{}'
omarchy-shell shell toggle aether.blueprints '{}'

See Omarchy shell plugins for installation and controls.

Open with Tab

Launch GUI with a specific tab focused:

aether --tab <name>

Color Utilities

Standalone commands for working with colors. No running GUI needed.

Color Info

Show all representations of a hex color:

aether --color-info "#7cd480"
aether --color-info "#7cd480" --json

Color Convert

Convert a color between formats:

aether --color-convert "#7cd480" --to rgb
aether --color-convert "#7cd480" --to hsl
aether --color-convert "#7cd480" --to oklab
aether --color-convert "#7cd480" --to oklch

Contrast

Check WCAG contrast ratio between two colors:

aether --contrast "#0a180a" "#a5baa7"

Returns the ratio and AA/AAA pass/fail for normal and large text.

Adjust Color

Apply the 12-step adjustment pipeline to a single color:

aether --adjust-color "#7cd480" --vibrance 20 --saturation -10

Supports all adjustment flags: --vibrance, --saturation, --contrast, --brightness, --shadows, --highlights, --hue-shift, --temperature, --tint, --gamma, --black-point, --white-point.

Darken / Lighten

aether --darken "#7cd480" 70    # 0 = black, 100 = unchanged
aether --lighten "#7cd480" 20   # 0 = unchanged, 100 = white

Palette Operations

Extract Palette

Extract a 16-color palette from a wallpaper without applying it (read-only):

aether --extract-palette ~/wallpaper.jpg
aether --extract-palette ~/wallpaper.jpg --extract-mode pastel --light-mode --json

Palette from Color

Generate a full 16-color ANSI palette from a single base color:

aether --palette-from-color "#7cd480"

Gradient

Generate a color gradient between two colors:

aether --gradient "#0a180a" "#bed3c0"
aether --gradient "#0a180a" "#bed3c0" --steps 8

Defaults to 16 steps. Use --steps for a custom count.

Adjust Palette

Apply adjustments to an entire palette (JSON array or blueprint name):

aether --adjust-palette '["#0a180a","#a8ad42","#7cd480"]' --vibrance 20
aether --adjust-palette "Nord" --temperature 15

Palette Info

Analyze a palette for contrast, dark/light detection, and monochrome detection:

aether --palette-info '["#0a180a","#a8ad42","#7cd480","#a0c877","#53ba97","#7cc094","#8fd7b0","#a5baa7","#39513c","#a8ad42","#7cd480","#a0c877","#53ba97","#7cc094","#8fd7b0","#bed3c0"]'
aether --palette-info "Nord" --json

Blueprint Management

Show Blueprint

Display full details of a saved blueprint:

aether --show-blueprint "Nord"
aether --show-blueprint "Nord" --json

Delete Blueprint

aether --delete-blueprint "Old Theme"

Export Blueprint

Export a blueprint to a JSON file:

aether --export-blueprint "Nord"
aether --export-blueprint "Nord" --output ~/themes/nord.json

Inspection

List Apps

List all applications that Aether can generate themes for:

aether --list-apps
aether --list-apps --json

List Modes

List available extraction modes with descriptions:

aether --list-modes

Show Variables

Show all template variables that would be generated for a source (wallpaper or blueprint):

aether --show-variables ~/wallpaper.jpg
aether --show-variables "Nord" --json

Current Theme

Show the currently applied theme colors (reads from ~/.config/aether/theme/colors.toml):

aether --current-theme
aether --current-theme --json

Preview Template

Preview the rendered output of a specific app template:

aether --preview-template kitty ~/wallpaper.jpg
aether --preview-template alacritty "Nord" --json

Wallpapers

Search Wallhaven

Search wallhaven.cc from the command line:

aether --search-wallhaven "dark forest"
aether --search-wallhaven "mountains" --sorting relevance --purity 100 --page 2 --json

Options:

Option Description
--categories Filter categories (default "111" = all)
--purity Purity filter (default "100" = SFW)
--sorting Sort by: date_added, relevance, random, views, favorites, toplist
--order Sort order: desc, asc
--page Page number
--at-least Minimum resolution (e.g. "1920x1080")
--colors Filter by color hex (without #)

List Wallpapers

List local wallpapers from ~/Wallpapers:

aether --list-wallpapers
aether --list-wallpapers --json

Random Wallpaper

Pick a random wallpaper from the local directory:

aether --random-wallpaper

Favorites

List Favorites

aether --list-favorites
aether --list-favorites --json

Toggle Favorite

aether --toggle-favorite ~/Wallpapers/forest.jpg
aether --toggle-favorite ~/Wallpapers/forest.jpg --type wallhaven

Is Favorite

aether --is-favorite ~/Wallpapers/forest.jpg

Remote Control

When Aether is running, you can control the editor in real time using bare subcommands (no -- prefix). These connect to the running instance via a Unix domain socket.

aether status                      # show editor state
aether extract ~/wallpaper.jpg     # load wallpaper into editor
aether set-color 4 "#53ba97"       # change a palette color
aether adjust --vibrance 20        # move sidebar sliders
aether set-mode pastel             # change extraction mode
aether toggle-light-mode           # flip light/dark
aether apply                       # apply current theme
aether load-blueprint "Nord"       # load blueprint into editor
aether apply-blueprint "Nord"      # apply blueprint directly
aether set-wallpaper ~/wall.jpg    # set wallpaper path

See Remote Control for the full IPC reference and AI integration guide.

JSON Output

All commands support --json for machine-readable output:

aether --color-info "#7cd480" --json
aether --extract-palette ~/wallpaper.jpg --json
aether status --json

Scripting Examples

Theme Rotation Script

#!/bin/bash
# Rotate through themes by time of day

themes=("morning" "afternoon" "evening" "night")
hour=$(date +%H)

if [ $hour -lt 6 ]; then
    aether --apply-blueprint "${themes[3]}"
elif [ $hour -lt 12 ]; then
    aether --apply-blueprint "${themes[0]}"
elif [ $hour -lt 18 ]; then
    aether --apply-blueprint "${themes[1]}"
else
    aether --apply-blueprint "${themes[2]}"
fi

Random Wallpaper Theme

#!/bin/bash
# Generate theme from random wallpaper

wallpaper=$(find ~/Wallpapers -type f \( -name "*.jpg" -o -name "*.png" \) | shuf -n 1)
aether --generate "$wallpaper"

Hyprland Keybind

Add to ~/.config/hypr/hyprland.conf:

# Native Omarchy shell selectors
bind = SUPER ALT, W, exec, omarchy-shell shell toggle aether.wallpapers '{}'
bind = SUPER ALT, B, exec, omarchy-shell shell toggle aether.blueprints '{}'

# Generate theme from current wallpaper
bind = $mainMod ALT, T, exec, aether --generate $(hyprctl hyprpaper listactive | head -1 | cut -d' ' -f2)

Exit Codes

Code Meaning
0 Success
1 Error (file not found, invalid blueprint, etc.)

Environment Variables

Aether respects standard XDG directories:

  • ~/.config/aether/ - Configuration and blueprints
  • ~/.cache/aether/ - Thumbnails and temporary files
  • ~/.local/share/aether/ - Downloaded wallpapers

AETHER_EXTRA_THEME_DIRS

Colon-separated list of additional directories to scan for themes shown in the System Themes tab. These are searched before the omarchy defaults (~/.config/omarchy/themes, $OMARCHY_PATH/themes or /usr/share/omarchy/themes, ~/.config/themes), so a theme with the same name in a custom directory wins.

AETHER_EXTRA_THEME_DIRS="$HOME/dotfiles/themes:$HOME/work/themes" aether

Useful if you keep themes in a non-omarchy location (e.g. your dotfiles repo) or run a distro that puts themes elsewhere.