Skip to content

README.md

Latest commit

 

History

History
78 lines (55 loc) · 4.28 KB

README.md

File metadata and controls

78 lines (55 loc) · 4.28 KB
Raw

StackHub

English | 简体中文

StackHub is a native macOS menu bar app built with SwiftUI. Run commands and shell scripts, manage local services, and monitor GitHub Actions and GitLab CI from one panel.

Screenshots

Local projects and services CI activity Full-panel service logs
Project and service overview with sample data GitHub Actions and GitLab CI activity with sample data Service logs with sample data

English interface with sample data.

Features

  • Local services — Start, stop, and restart project services with custom commands, working directories, and ports. Commands load your .zshrc so tools such as jenv and nvm can configure the environment.
  • Per-service runtimes — Select an installed JDK or Node.js version, or specify a custom path. No version manager required.
  • Live logs — View service output with ANSI colors in a dedicated log view.
  • CI monitoring — Follow GitHub Actions and multiple GitLab instances. Each refreshes independently and keeps cached results when offline.
  • Secure credentials — Store GitHub and GitLab tokens in macOS Keychain.
  • In-app updates — Check for updates hourly. Click the blue download icon when an update is available to install and restart.
  • Bilingual interface — Switch between English and Simplified Chinese.

Install

Requires macOS 14 or later. Release downloads are for Apple Silicon.

  1. Download the ZIP from GitHub Releases.
  2. Extract it and move StackHub.app to Applications.
  3. Launch StackHub and click its menu bar icon. Add local services in Projects, or connect GitHub and GitLab in CI.

Configured ports are freed before a service starts; use only ports belonging to that service. Quitting or installing an update stops managed services; start them again when needed.

JDK and Node.js

Expand Runtime environment when editing a service. Default mode follows your system shell configuration without reading project version files, overriding runtimes, or logging default runtimes. Select an installed version or custom path to override it; the panel shows the resolved version, path, and source.

JDKs, Homebrew Node.js, and installed jenv/nvm versions are detected locally; custom paths work too. Missing requested versions prevent startup, without downloading or silently choosing another version. Changes apply after restarting the service and do not change other services or your terminal environment.

Command line

The app bundle ships a CLI that controls the running app, so terminal-started services are owned by StackHub just like UI-started ones. If StackHub is not running, the CLI launches it.

/Applications/StackHub.app/Contents/MacOS/stackhub-cli install   # links `stackhub` into your PATH

stackhub status                                  # projects, services, ports, state
stackhub start|stop|restart <project> [service...]
stackhub logs <project> <service> -n 100 -f
stackhub project add demo --cmd "pnpm dev" --port 3000 --dir ~/work/demo
stackhub project edit demo --name demo-web
stackhub service add demo api --cmd "go run ." --port 3100 --url http://localhost:3100
stackhub service edit demo api --cmd "go run ./cmd/api"
stackhub service rm demo api

Run stackhub help for every option, stackhub help <topic> (or <command> --help) for details, and stackhub help agents for a guide aimed at AI agents and scripts. Projects and services match by name (case-insensitive) or id; --json gives machine-readable output. Editing a running service saves the change but does not restart it. The CLI talks to the app over a private socket at ~/Library/Application Support/StackHub/control.sock (owner-only).

Build from source

Requires Xcode and Swift 5.9 or later.

cd swift-prototype
swift run StackHub

To build an app bundle, use scripts/package-app.sh.