Superstack CLI

superstack is the command line interface to Superstack: log in, create fleets, claim devices, and manage who can reach them. It is a single static binary for managing Superstack from a terminal.

Uploading Lua code and streaming logs are not available yet.

Install

• macOS, with Homebrew:

  brew install --cask siliconwitchery/tap/superstack   # install
  brew upgrade --cask superstack                       # update

• Windows, with Scoop and git:

  scoop bucket add siliconwitchery https://github.com/siliconwitchery/scoop-bucket
  scoop install superstack                             # install
  scoop update superstack                              # update

• Arch Linux, from the AUR:

  yay -S superstack-bin                                # install and update

• NixOS, with Nix nix-command and flakes enabled:

  nix profile install github:siliconwitchery/superstack-cli#superstack   # install
  nix profile upgrade superstack                                         # update

• Any platform. Download an archive from the releases page, unpack it, and move superstack onto your PATH. Repeat to update.

Local development

1. Clone the repository:

   git clone https://github.com/siliconwitchery/superstack-cli.git ~/projects/superstack-cli
   cd ~/projects/superstack-cli

2. Install the toolchain:

   • Any platform: Go 1.25 or newer.
   • Nix: nix develop from inside the clone, or direnv allow once with direnv hooked into your shell.

3. Build and run:

   CGO_ENABLED=0 go build -o superstack .
   ./superstack

4. Run the tests while you work. Go caches per package, so a change to one part leaves every other part cached:

   CGO_ENABLED=0 go test ./...

5. Run every check before opening a pull request:

   gofmt -l .
   go mod tidy
   git status --porcelain -- go.mod go.sum
   CGO_ENABLED=0 go vet ./...
   CGO_ENABLED=0 go test ./...

Releasing

1. Create dev fresh from main:

   git fetch origin
   git switch -C dev origin/main

2. Change version in main.go.

3. Run every check:

   gofmt -l .
   go mod tidy
   git status --porcelain -- go.mod go.sum
   CGO_ENABLED=0 go vet ./...
   CGO_ENABLED=0 go test ./...
   git diff --check

4. Commit and push:

   git add main.go
   git commit -m "Version <version>"
   git push -u origin dev

5. Open the dev pull request, review it, and merge it with squash.

6. Return to main, remove the stale branch, and tag the commit that merging created:

   git switch main
   git pull --ff-only
   git branch -D dev
   tag="v$(sed -n 's/^const version = "\(.*\)"$/\1/p' main.go)"
   git tag "$tag" && git push origin "$tag"

7. Write the release notes into the empty release body on GitHub.

A prerelease suffix, v0.0.2-rc1, skips every package manager. Tags cannot be moved or deleted.