Superstack CLI

superstack is the command line interface to Superstack: sign in, claim devices, push Lua code, and stream logs from your fleet. It is a single static binary talking to the Superstack server's JSON API. The server is a separate project; this repo is the CLI only. It is laid out as follows:

├── .envrc                 # Loads the Nix dev shell via direnv
├── .github/dependabot.yml # Weekly action and module update PRs
├── .github/workflows      # CI on pull requests, release on v* tags
├── .gitignore
├── .goreleaser.yaml       # Build matrix and every publishing target
├── CLAUDE.md              # Coding principles and architectural overview
├── flake.lock             # Pins nixpkgs
├── flake.nix              # The superstack package, and the dev shell
├── go.mod
├── internal
│   └── commands           # One file per command, plus the shared server client
├── LICENSE
├── main.go                # Entry point, version constant, and the command table
├── main_test.go
└── README.md

Install

Each option needs a published release.

• Homebrew:

  brew install --cask siliconwitchery/tap/superstack

• Scoop:

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

• Arch Linux:

  yay -S superstack-bin

• Nix. Not in nixpkgs yet.

  nix profile install github:siliconwitchery/superstack-cli

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

Local development

1. Install Go 1.25 or newer.

2. Clone the repository:

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

3. Build and run:

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

Nix users: nix develop enters the dev shell, and with direnv hooked into your shell, direnv allow run once in the checkout loads it automatically from then on.

Release setup

Do everything below once.

1. Create public repositories siliconwitchery/homebrew-tap and siliconwitchery/scoop-bucket, each with a README.

2. Add a fine-grained token (Settings > Developer settings > Personal access tokens) as the Actions secret TAP_GITHUB_TOKEN:

   • Resource owner: siliconwitchery
   • Repository access: homebrew-tap and scoop-bucket
   • Permissions: Contents, read and write

3. Register at aur.archlinux.org, then:

   cd "$(mktemp -d)"
   ssh-keygen -t ed25519 -N "" -f aur_key
   cat aur_key.pub   # paste into SSH Public Key in your AUR account settings
   cat aur_key       # add as the Actions secret AUR_KEY
   rm aur_key aur_key.pub

4. Add one ruleset (Settings > Rules > Rulesets) targeting the default branch: require a pull request with 0 approvals, require the build status check, allowed merge method squash only, block force pushes, restrict deletions. Add a second targeting v* tags: block force pushes, restrict deletions.

5. Enable Automatically delete head branches (Settings > General).

Releasing

1. Create dev fresh from main:

   git fetch origin
   git switch -C dev origin/main

2. Change version in main.go, run the checks, commit, and push:

   CGO_ENABLED=0 go vet ./...
   CGO_ENABLED=0 go test ./...
   git diff --check
   git add main.go
   git commit -m "Version <version>"
   git push -u origin dev

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

4. 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"

5. Write the release notes into the empty release body on GitHub, following the shape in CLAUDE.md.

A tag carrying a prerelease suffix, v0.0.2-rc1, publishes a GitHub prerelease and skips every package manager. Tags cannot be moved or deleted.