UniStack is a single-binary, cross-platform orchestrator designed to simplify infrastructure deployments by offering a Docker Compose-like experience for both containerized and native environments. It streamlines operations with a modern CLI framework, robust tooling, and seamless cross-platform support.
Key Features:
Modern CLI Architecture: Built using Go 1.24+ and Cobra, providing a structured and extensible command-line interface.
Beautiful Output: Utilizes pterm for rich, colorful, and interactive terminal output.
Structured Logging: Implements Go's standard slog package for high-performance logging.
Cross-Platform Compatibility: Runs smoothly on macOS, Linux, and Windows.
Triple Guarantee Quality: Enforces 100% code purity through IDE checks, pre-commit hooks, and GitHub Actions.
Target Audience and Benefits:
Ideal for developers and DevOps teams seeking a unified solution to manage complex infrastructure deployments. UniStack enhances productivity by reducing boilerplate and standardizing development workflows, ensuring high-quality outputs with minimal effort.
Available via the Windows Package Manager, you can easily install or deploy using the winget command line, making it accessible and efficient for automated setups.
UniStack is a single-binary, cross-platform orchestrator that brings a Docker Compose-like experience to both containerized and native infrastructure deployments.
🌟 Features
Modern CLI Architecture: Built with Go 1.24+ and Cobra, providing a structured and extensible command-line application framework.
Beautiful Output: Utilizes pterm for rich, colorful, and interactive terminal output.
Structured Logging: Built-in support for Go's standard slog package for high-performance structured logging.
Robust Tooling: Includes built-in commands like doctor, self-update, cache, config, and license.
Triple Guarantee Quality: 100% code purity enforced through IDE checks, Pre-commit hooks, and GitHub Actions integrated quality gates.
Cross-Platform Ready: Runs seamlessly on macOS, Linux, and Windows.
🏗️ Architecture & Design
Overview
UniStack is engineered to solve the boilerplate problem when starting new Go CLI projects. It standardizes the development environment, architectural patterns, and automation pipelines out of the box.
Core Components
CLI Framework: Utilizes spf13/cobra and spf13/viper for powerful command parsing and configuration management.
UI & Logging: Integrated pterm for UI components and slog for structured event logging.
Database & Caching: SQLite-backed (via modernc.org/sqlite) local caching and transactional data storage.
Task Orchestration: Configured with UniRTM for managing local development workflows (lint, test, verify).
📖 Usage Guide
Prerequisites
Runtime: Go (>= 1.24).
Git: Global git installation required.
UniRTM: Required for task execution and orchestration.
Installation
Via NPM:
npm install -g @snowdreamtech/unistack
Via PyPI:
pip install snowdreamtech-unistack
Quick Start
Install UniRTM: Ensure unirtm is installed on your system.
Initialize: unirtm run setup (bootstraps core dependencies and hooks).
Install: unirtm run install (installs project dependencies).
Verify: unirtm run verify (ensures everything is green).
Build: go build -o unistack main.go
Available Commands
unistack version: Print the version number
unistack doctor: Check system health and diagnose issues
unistack self-update: Update to the latest version
Run unirtm run verify to ensure all quality gates are green (runs formatters, linters, tests, and security audits).
Ensure CHANGELOG.md is updated.
Troubleshooting
Problem: unirtm run verify fails with test errors.
Solution: Ensure your code passes all Go unit tests. UniStack enforces strict coverage and race condition checks.
Problem: Pre-commit hooks fail.
Solution: The hooks often auto-fix issues (like formatting). Stage the modified files and commit again.
🔒 Security Considerations
Security Model
Audit Logging: All critical operations and security scans are executed during the verify task using tools like trivy, gitleaks, and govulncheck.
Dependency Management: Powered by Dependabot to ensure all dependencies are kept up-to-date and secure.
🧑💻 Development Guide
Local Development Setup
git clone https://github.com/snowdreamtech/UniStack.git
cd UniStack
unirtm run setup
unirtm run install
🚀 Proxy Usage Scenarios
The GITHUB_PROXY (default: https://gh-proxy.sn0wdr1am.com/) is optimized for specific network acceleration scenarios. Misusing it for unsupported protocols (like Git) will result in errors.
Scenario
Supported?
Example / Note
Release Files
✅ Yes
.../releases/download/v1.0/tool.zip
Source Archives
✅ Yes
.../archive/master.zip or .tar.gz
Direct File Links
✅ Yes
.../blob/master/filename
Git Clone
❌ No
Do not use for git clone or insteadOf configs.
Project Folders
❌ No
Browsing/cloning via proxy is not supported.
> [!IMPORTANT]
> To prevent breaking toolchains (like unirtm), this template explicitly disables Git redirection via this proxy. Use it only for direct HTTP downloads in scripts.
📄 License
This project is licensed under the MIT License.
Copyright (c) 2026-present SnowdreamTech Inc.
See the LICENSE file for the full license text.
