unistack

README

UniStack

English | 简体中文

UniStack is a fast, flexible, and enterprise-grade Golang CLI template inspired by UniRTM and helloworld. It provides a robust foundation for building modern command-line applications in Go, featuring beautiful terminal output, structured logging, built-in caching, and a comprehensive CI/CD pipeline.

🌟 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

1. Install UniRTM: Ensure unirtm is installed on your system.
2. Initialize: unirtm run setup (bootstraps core dependencies and hooks).
3. Install: unirtm run install (installs project dependencies).
4. Verify: unirtm run verify (ensures everything is green).
5. 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
• unistack cache: Manage local cache
• unistack config: Manage configuration
• unistack license: Manage copyright license headers

🛠️ Operations Guide

Pre-deployment Checklist

1. Run unirtm run verify to ensure all quality gates are green (runs formatters, linters, tests, and security audits).
2. 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.

Star History