How it works

Theme cache

Downloaded themes are cached in a folder tree under ~/.config/stellar/, organized by author, theme slug, and version:

~/.config/stellar/<author>/<slug>/<version>.toml
~/.config/stellar/config.json

config.json tracks which theme is currently applied, along with a checksum stellar uses to recognize its own applied file.

Applying themes

How stellar apply puts a config in place depends on the OS:

• Linux and macOS: ~/.config/starship.toml is symlinked to the cached config file. Editing a local theme file live-updates your prompt.
• Windows: symlinks need Developer Mode or admin privileges, so stellar copies the theme file over starship.toml instead.

You can force copy mode on any OS (useful for testing) by setting the STELLAR_APPLY_MODE=copy environment variable.

Customizing an applied theme

Theme descriptions often tell you to just edit the cached config directly at ~/.config/stellar/<author>/<slug>/<version>.toml. What happens to those edits depends on a few things:

• Linux and macOS: since starship.toml is a symlink to that cached file, edits live-update your prompt immediately - no need to re-apply.
• Windows: starship.toml is a copy, not a link (see above), so edits to the cached file don't show up until you re-run stellar apply <author>/<theme>. The same is true anywhere you've set STELLAR_APPLY_MODE=copy.
• stellar clean only removes themes stellar downloaded, and never the version you have applied, so it never touches the file you've been editing - except with --all (duh), which removes the applied theme as well.
• stellar remove refuses to delete the currently active theme (unless you pass --force), so it won't take your edits out from under you either.

cp ~/.config/stellar/<author>/<slug>/1.0.toml \
   ~/.config/stellar/<yourname>/<slug>/1.0.toml
stellar apply <yourname>/<slug>

Automatic backups

The first time you run stellar apply, if you have an existing ~/.config/starship.toml that isn't already managed by stellar, it gets backed up automatically before stellar creates the symlink (or copy):

~/.config/stellar/<your-username>/backup/1.0.toml

Backups are versioned - if stellar finds another unmanaged starship.toml later (for example one you hand-edited or restored), it's backed up as 2.0.toml, then 3.0.toml, and so on, so an earlier backup is never overwritten.

Backups survive stellar clean, whatever the flags (--all, --include-own) - they're only removed if you explicitly run stellar remove <username>/backup. Restore the newest backup with:

stellar apply <username>/backup

Or pin a specific version, for instance your very first original config:

stellar apply <username>/backup@1.0

Local & custom themes

You don't need to download anything from the hub to use stellar. Just hand-create a config at:

~/.config/stellar/<author>/<slug>/1.0.toml

The <author> directory name is arbitrary - use local/, dev/, or anything else you like, including an existing username. Then apply it the same way as any other theme:

stellar apply local/my-custom-theme

You can also copy an existing cached theme into your own folder and tweak it from there, or rename/move cached directories directly - stellar identifies themes purely by their path under ~/.config/stellar/.

Themes like these are yours, so stellar clean keeps them. Only stellar clean --include-own removes them, and it asks first.

Where themes come from

Community themes live on the stellar hub, the web app this documentation is part of. stellar apply and stellar preview fetch theme configs from the hub's API when they're not already cached locally.

Next steps