Skip to content

Preset Store

Jump to bottom
Scrimas edited this page Sep 1, 2026 · 4 revisions

Preset Store

Someone else's whole desktop, installed from GitHub in one click — and yours published back the same way, without ever opening a browser.

A preset is your visual setup captured as a file: bar layout, sidebar, widgets, dock, colors, wallpaper, banner. The Preset Manager has always let you save and export those locally. The Preset Store turns that into something shareable.

There is no server and no central index. A published preset is an ordinary public GitHub repository carrying a preset.json manifest, tagged with the topic ii-p3drovfx-preset. The store is simply what GitHub returns for that topic; installing is a git clone, updating is a git pull --ff-only, and publishing is gh repo create followed by adding the topic. Nobody has to merge anything for your preset to appear, and nothing stops working if this project does.

⚠️ Presets are not reviewed. They are published by other people and this project inspects none of them. Applying one changes your settings, and settings can carry commands the shell will run. Use them at your own discretion — no responsibility is taken for what one does to your system. The shell shows this notice permanently on the Presets page for the same reason it is repeated here.

The three tabs

Settings → Presets is split in three:

Tab What lives there
My presets Every preset on this machine — the ones you saved, imported or installed. Save, apply, export, import, delete, and the share button that publishes one
Store Search GitHub for presets by the store topic, look at screenshots, install
Published The presets you have published, with a button to push a new version of each

Installing a preset

Open Store, and the tab searches GitHub for the topic on its own. You get a card per preset with its name, author, description, star count and — once it has been opened — its screenshots.

  • Search narrows the GitHub query itself, so it searches every published preset rather than filtering the page.
  • Sort by offers Stars, Recently updated or Name.
  • Refresh re-runs the search. Signed in to GitHub you get 30 searches a minute instead of 10, which is the difference between a store that reloads and one that stops.
  • Clicking a card opens the detail dialog: full description, version, screenshots, changelog, and Open on GitHub if you want to read the repository first.

Press Install and the preset is cloned and added to your list. That is all it does:

Installing only puts the preset in your list. Nothing changes until you apply it.

An installed preset then behaves exactly like one you saved yourself — same folder, same file names — because it is materialised straight into ~/.config/illogical-impulse/presets/. Everything that already worked on a local preset works on an installed one without knowing the store exists.

Applying it

Apply from My presets, and before anything happens the preset is inspected and you are told what it would do:

  • Commands it can run on your system — settings whose value is a command line the shell executes
  • Assistant permissions it widens — anything that gives the AI assistant more reach than it has now
  • Servers and search engines it redirects — endpoints the preset would point elsewhere
  • Other settings that read like commands — the catch-all for values that look executable but sit outside the known categories

If none of that is present, the dialog says so plainly: Nothing in this preset runs commands or sends your data anywhere new. If the preset could not be read at all, it says that instead, and leaves the decision to you.

Applying never replaces your configuration. The preset is layered over what you already have, and anything tied to this machine is kept as it is:

  • API keys, saved networks, paired devices and contacts — never taken from a preset
  • Your profile picture, name, greeting and weather location — never taken from a preset
  • Monitor names, save folders, phone addresses and other local paths — kept as yours

Your current settings are also snapshotted first, so the Undo preset button that appears afterwards puts everything back exactly as it was before.

Keeping presets up to date

The Store tab checks the presets you installed against their repositories and badges the ones with something new. Updating is pull only — a new version is downloaded, never applied behind your back:

Take an update from either side: the Store tab badges the card and its details carry an Update button, and in My presets the preset's own button turns into a download arrow.

  • For a preset you are not currently using, the new version simply lands in your list, ready for whenever you want it.
  • For the preset your settings actually came from, the shell says so — This is the preset your settings came from, and a new version of it was just downloaded — and offers to apply it, going through the same inspection dialog as any other apply.

Updates are git pull --ff-only, always. If an author rewrote their history the update fails loudly and tells you to reinstall, rather than leaving a half-merged configuration behind.

Publishing your own

Signing in

Publishing puts the preset in a repository of your own, so it needs your GitHub account — once, and never again afterwards.

Press Install it and sign in on the Presets page. A terminal opens and does the whole thing:

  1. Installs the github-cli package with whichever package manager you actually have — yay, paru, pacman, dnf, zypper, apt or nix-env. This is why it runs in a terminal rather than behind a panel: installing a package asks for your password, and a password prompt belongs in a tty.
  2. Runs gh auth login --hostname github.com --git-protocol https --scopes repo, which prints a one-time code you can enter on any device — no browser has to open on this machine.
  3. Closes when you press a key. The Presets page notices the new session on its own; there is nothing to come back and press.

Already signed in with the permission publishing needs? The script says so and stops, rather than throwing away a working session. Signed in without the repo scope — which reads GitHub perfectly well and then fails at the exact moment it creates your repository — it signs you in again asking for it.

If you would rather type it yourself, Or run it yourself on the same panel carries the exact command:

bash ~/.config/quickshell/ii/scripts/preset_store_signin.sh

Once an OAuth app is registered for the shell, the same panel gains a Sign in to GitHub button that shows the device code in-shell, with no terminal at all. The terminal route stays either way.

Publishing

The share button on any of your presets opens the publish dialog:

  • Repository name — defaults to the preset's name, cleaned up
  • Description — the one line people read in the store
  • Release notes — optional, and First release. is used if you leave it empty
  • Screenshots — press Take a screenshot and the settings window hides itself, photographs your screen and comes back. These are the only pictures people see before installing, so they are worth taking.
  • Keep the repository private — publishes nothing to the store. Nobody can install it, including you on another machine.

Publishing then creates the repository, tags it with ii-p3drovfx-preset, and pushes. Do not be surprised if the store does not find it immediately: GitHub's search index takes a few minutes to notice a brand new repository.

What gets published, exactly:

Shipped Never shipped
Your settings, with keys, tokens, folders and monitor names stripped out API keys, saved networks, paired devices and contacts
The wallpaper and the sidebar banner, if the preset has them Your profile picture, name, greeting and weather location
The screenshots you took Phone addresses, account names and hardware ids
Anything from the keyring or .env

The export sanitizer runs on the way out and on the way in, so a preset published from a raw configuration cannot hand its author's tokens to whoever installs it.

Review what will be published — the button under that list — is how you check it rather than take its word. It opens everything that would be uploaded, before the repository exists:

  • the files and their sizes
  • the settings the sanitizer took out, by name
  • values that survived and still read like an address, an account or a command
  • the warning people will be shown when they install it
  • every setting that would ship, with a search box — type your own city, your name or a folder you recognise and see for yourself

Pushing an update

From the Published tab, Push update re-exports your current settings into the repository and pushes them. You pick how big the change is —

Choice Version
A fix patch — 1.0.0 → 1.0.1
Something new minor — 1.0.0 → 1.1.0
A different look major — 1.0.0 → 2.0.0

— and optionally leave a note. Leaving it empty is fine: the version and the date are already recorded, and demanding prose is a good way to stop people publishing fixes at all. Show diff lists exactly which settings changed since the published version before you commit to it, and an update that changes nothing says so instead of making an empty release.

Stop managing forgets the repository without touching either the preset or what is already published.

Version compatibility

Presets carry the configuration schema version they were written against, and the rule is migrate up, block newer:

  • Older preset — applied normally. The shell's own migrations carry its settings forward, and the dialog says This preset was made for an older version of the shell. Its settings are brought up to date as it is applied.
  • Same version — nothing to say.
  • Newer preset — refused. It names settings this build has never heard of, and merging them in would mangle them silently rather than apply them. The card carries a badge, Apply is greyed out, and updating the shell is what fixes it.
  • No version at all — treated as unknown rather than old, and allowed. Every preset exported before schema versioning existed would be locked out otherwise.

The refusal is enforced in three independent places — the apply dialog, the store cards, and the apply script itself — so a preset that slips past the inspection still cannot be applied by hand.

The manifest

A preset repository is anything carrying a valid preset.json at its root. Publishing from the shell writes it for you; writing one by hand is perfectly supported.

{
  "schema": 1,
  "name": "Midnight",
  "author": "octocat",
  "description": "A dark, quiet setup with a thin bar.",
  "version": "1.2.0",
  "configVersion": 16,
  "config": "config.json",
  "wallpaper": "wallpaper.jpg",
  "banner": "banner.jpg",
  "screenshots": ["screenshots/1.png", "screenshots/2.png"],
  "changelog": [
    { "version": "1.2.0", "date": "2026-09-01", "notes": "Thinner bar, softer shadows." }
  ]
}
Field Required Meaning
name yes The preset's name, and what it is installed as
config no Path to the settings file inside the repo — config.json by default. Never absolute, never ..
schema no Manifest format version (1)
author, description no Shown in the store; the author falls back to the repository owner
version no Semantic version, used to work out what an update contains
configVersion no The shell schema this preset was written against — see Version compatibility
wallpaper, banner no Images shipped alongside, 25 MB each at most. A wallpaper.* or banner.* at the repo root is picked up even when unlisted
screenshots no Up to 6 images, shown before installing, 8 MB each at most
changelog no Newest first; {version, date, notes}, and empty notes are allowed

Repository layout:

preset.json          the manifest
config.json          the settings, sanitized
wallpaper.jpg        optional
banner.jpg           optional
screenshots/1.png    optional, up to 6
README.md            written for you when publishing from the shell

From the terminal

Everything the UI does is ~/.config/quickshell/ii/scripts/preset_store.py, and every command prints exactly one JSON line — failures included — so nothing has to guess whether a command broke or simply said nothing.

cd ~/.config/quickshell/ii/scripts

python3 preset_store.py auth status
python3 preset_store.py auth login

python3 preset_store.py discover --limit 30 --query "dark"
python3 preset_store.py fetch-manifest octocat/midnight
python3 preset_store.py install octocat/midnight [--name NAME] [--force]

python3 preset_store.py check-updates
python3 preset_store.py pull Midnight
python3 preset_store.py diff Midnight [--incoming]
python3 preset_store.py preview Midnight    # everything publishing would upload

python3 preset_store.py publish Midnight --description "..." [--notes "..."] \
    [--repo NAME] [--private] [--screenshot PATH]...
python3 preset_store.py push-update Midnight [--bump patch|minor|major | --version 2.0.0] \
    [--notes "..."] [--screenshot PATH]...

python3 preset_store.py links
python3 preset_store.py unlink Midnight
python3 preset_store.py uninstall Midnight

Applying and reverting stay where they always were, in presets.sh:

./presets.sh list
./presets.sh scan Midnight     # what applying it would change, as JSON
./presets.sh load Midnight
./presets.sh revert

On --screenshot: leaving the flag out entirely means leave the published screenshots alone, which is what an update that only changes settings wants. Passing it with no value means ship none.

Files on disk

Path Holds
~/.config/illogical-impulse/presets/ Every preset on this machine: <name>.json plus its wallpaper and banner copies
~/.config/illogical-impulse/presets/.active The preset your settings currently come from, if any
~/.config/illogical-impulse/preset-store/<owner>__<repo>/ The git clone behind an installed or published preset
~/.config/illogical-impulse/preset-store/links.json Which preset came from which repository, its version and whether you own it

Deleting an installed preset from the UI removes its link too. Deleting the file by hand leaves the link behind, and the store will then refuse to install that repository again — unlink is the way out.

Troubleshooting

The store is empty or search fails. GitHub rate-limits anonymous search to 10 queries a minute. Signing in raises it to 30. Refresh after a minute.

A preset I just published does not show up. GitHub's search index takes a few minutes to pick up a new repository. The Published tab shows it immediately regardless, and Open on GitHub confirms the topic was set.

Publishing refuses because the wallpaper is too large. A preset may ship 25 MB of wallpaper and 25 MB of banner. This is checked before the repository is created, because git keeps every version of a binary forever — an enormous wallpaper is a clone everyone who installs the preset pays for, on every release. Shrink it, save the preset again, and publish.

Publishing says it needs the GitHub CLI. Press Install it and sign in and let the terminal do it. Without the repo scope the token cannot create repositories, and the shell says exactly that rather than failing at the push.

An update refuses to install. Either the preset was written for a newer shell than yours — update the shell — or its author force-pushed and the fast-forward pull cannot apply. Reinstall it in that case.

A preset made things worse. Undo preset returns your settings to the snapshot taken just before the last apply. Anything you changed since then goes back with it.

Under the hood

File Role
scripts/preset_store.py The store: discovery, install, updates, diffs, publish, links. One JSON line per call
scripts/presets_helper.py Sanitizing, merging, the risk scan and the schema compatibility verdict — the single source of truth for all three
scripts/presets.sh Save, load, revert, delete, scan; owns .active
scripts/preset_store_signin.sh Installs the GitHub CLI and signs it in, in a terminal, idempotently
services/PresetStore.qml The shell-side singleton. One job at a time through a single process, and a config write guard around anything that touches config.json
modules/settings/configs/PresetsConfig.qml The Presets page: tabs, the inspection dialog and the permanent notice
modules/settings/configs/presets/ Store tab, Published tab, and the sign-in, detail, diff, publish and update dialogs

Related pages

← Back to Home

Clone this wiki locally