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`)

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

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.

Uh oh!

FilesExpand file tree

cli.md

Latest commit

History

cli.md

File metadata and controls

Command Line Interface

Quick Reference

Commands

List Blueprints

Apply Blueprint

Generate Theme

Import Blueprint

Import Base16 Scheme

Import Colors.toml

Omarchy Shell Selectors

Open with Tab

Color Utilities

Color Info

Color Convert

Contrast

Adjust Color

Darken / Lighten

Palette Operations

Extract Palette

Palette from Color

Gradient

Adjust Palette

Palette Info

Blueprint Management

Show Blueprint

Delete Blueprint

Export Blueprint

Inspection

List Apps

List Modes

Show Variables

Current Theme

Preview Template

Wallpapers

Search Wallhaven

List Wallpapers

Random Wallpaper

Favorites

List Favorites

Toggle Favorite

Is Favorite

Remote Control

JSON Output

Scripting Examples

Theme Rotation Script

Random Wallpaper Theme

Hyprland Keybind

Exit Codes

Environment Variables

AETHER_EXTRA_THEME_DIRS

`AETHER_EXTRA_THEME_DIRS`