Repository navigation
Install
Two install methods: AppImage (works today) and Flatpak (draft). All installs are user-local; nothing here needs root.
The app shells out to node for every stack operation, so Node.js 22+ must be on PATH — no install method bundles it. If it is missing, first launch tells you exactly that. Get it from nodejs.org or a version manager; distro packages often lag.
Running the AppImage also needs FUSE 2 and the WebKitGTK 4.1 runtime (the AppImage does not bundle the webview):
| Distro | FUSE 2 | WebKitGTK 4.1 runtime |
|---|---|---|
| Debian/Ubuntu | sudo apt install libfuse2 |
sudo apt install libwebkit2gtk-4.1-0 |
| Fedora | sudo dnf install fuse-libs |
sudo dnf install webkit2gtk4.1 |
| Arch | sudo pacman -S fuse2 |
sudo pacman -S webkit2gtk-4.1 |
Without FUSE 2, launching fails with a mount error; without the webview libs it fails with a missing libwebkit2gtk-4.1.so error.
Build it (bundle lands at src-tauri/target/release/bundle/appimage/Stack_<version>_amd64.AppImage):
npm ci
npx tauri build --bundles appimageOr download the AppImage from the release page. Then install from a stack-app checkout:
scripts/install-appimage.sh <Stack_x.y.z_amd64.AppImage> --icons src-tauri/iconsWithout --icons, the installer extracts the single icon embedded in the AppImage instead (slower, 512px only). What it does:
- copies the AppImage to
~/.local/bin/stack-app.AppImage - writes
~/.local/share/applications/stack-app.desktopplus hicolor icons (idstack-app) - runs
scripts/provision-stack.sh(skip with--no-provision, or point at an existing checkout with--stack <dir>) - symlinks the checkout's
bin/stackto~/.local/bin/stack, so thestackterminal command is onPATH(skipped with a warning when something else already owns that name; removed on uninstall only if it still points at a stack checkout) - refreshes the desktop and icon caches
Options: --prefix <dir> (default ~/.local), --reinstall.
No checkout? The AppImage also runs standalone — chmod +x it and launch directly — but then there is no menu entry and no auto-provisioning; the app's first-run picker covers the stack path.
Upgrade: re-run the installer with the new AppImage plus --reinstall (or accept the in-app update when offered — that upgrades in place). Your stack path and settings survive.
Uninstall:
scripts/uninstall-stack-app.sh # keeps app config
scripts/uninstall-stack-app.sh --config # also forgets stack path, recentsNever touches the stack checkout or your projects.
Draft only. The manifest, desktop file, and CI sketch exist, but the generated npm/cargo vendor sources are not committed and no build has been validated — see https://github.com/escacs/stack-app/blob/main/flatpak/README.md for status and how to finish it. Provisioning inside the sandbox story: run scripts/provision-stack.sh on the host first; the sandbox cannot authenticate to GitHub for you.
Tauri also builds deb and rpm targets. When attached to a release they install system-wide (sudo apt/dnf install ./stack_x.y.z_arch.ext) with the desktop entry included; afterwards provision the stack checkout with scripts/provision-stack.sh from a checkout (or pick the folder in the app on first run).
scripts/provision-stack.sh runs at the end of every installer. In order:
-
Already have one? If
~/escacs/stack,$ESCACS_STACK, or the already-pinned app setting is a usable checkout (gitHEADplustools/stack/cli.mjs), it is kept and pinned in the app settings. -
ghclone — whenghis installed and authenticated, clonesescacs/stackto~/escacs/stackand pins it. -
ssh clone — batch-mode
git clone(fails fast, never prompts). -
Folder picker — otherwise first launch shows the setup screen: authenticate (
gh auth login) and re-run the script, or clone manually and pick the folder.
The pin is written to ~/.config/codes.escacs.stack/config.json as stackPath (the settings override wins in the app's resolve order), which is why GUI launches find it without shell env vars. $ESCACS_STACK is still honoured when set. The script never sees credentials — auth stays inside gh/ssh. Re-run it any time; it never overwrites an existing checkout.
The stack repo is private, so provisioning uses your existing GitHub auth (gh or ssh) and falls back to the app's first-run folder picker when there is none.
See also: First Run, Troubleshooting, Portability.
Stack desktop client + CLI wiki — condensed from the repo docs. App repo: https://github.com/escacs/stack-app. CLI repo (private): https://github.com/escacs/stack.