{"id":29650061,"url":"https://github.com/mavogel/cli-template","last_synced_at":"2025-07-22T04:36:18.591Z","repository":{"id":301336752,"uuid":"1006553636","full_name":"mavogel/cli-template","owner":"mavogel","description":"Opionionated CLI template (built with cursor and claude max) See blog post https://manuel-vogel.de/posts/2025-06-22-ai-coding-setup-cursor-claude-max/","archived":false,"fork":false,"pushed_at":"2025-07-06T07:30:33.000Z","size":58,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-06T08:34:26.227Z","etag":null,"topics":["claude-code","cursor","golang"],"latest_commit_sha":null,"homepage":"https://mavogel.github.io/cli-template","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mavogel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing/guidelines.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-22T14:24:38.000Z","updated_at":"2025-07-06T07:30:32.000Z","dependencies_parsed_at":"2025-06-26T10:59:04.758Z","dependency_job_id":"dde618f6-736d-4639-b0fa-ce5bdd683c20","html_url":"https://github.com/mavogel/cli-template","commit_stats":null,"previous_names":["mavogel/cli-template"],"tags_count":4,"template":true,"template_full_name":null,"purl":"pkg:github/mavogel/cli-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mavogel%2Fcli-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mavogel%2Fcli-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mavogel%2Fcli-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mavogel%2Fcli-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mavogel","download_url":"https://codeload.github.com/mavogel/cli-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mavogel%2Fcli-template/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266428719,"owners_count":23927049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","cursor","golang"],"created_at":"2025-07-22T04:36:17.944Z","updated_at":"2025-07-22T04:36:18.583Z","avatar_url":"https://github.com/mavogel.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CLI Template\n\nA comprehensive Go CLI application template with modern tooling, automated testing, releases, and documentation.\n\n[![CI](https://github.com/mavogel/cli-template/actions/workflows/ci.yml/badge.svg)](https://github.com/mavogel/cli-template/actions/workflows/ci.yml)\n[![Release](https://github.com/mavogel/cli-template/actions/workflows/release.yml/badge.svg)](https://github.com/mavogel/cli-template/actions/workflows/release.yml)\n[![Documentation](https://github.com/mavogel/cli-template/actions/workflows/docs.yml/badge.svg)](https://github.com/mavogel/cli-template/actions/workflows/docs.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/mavogel/cli-template)](https://goreportcard.com/report/github.com/mavogel/cli-template)\n\n## 🚀 Features\n\n- **Modern CLI Framework**: Built with [Cobra](https://cobra.dev/)\n- **Comprehensive Testing**: Unit tests with coverage reporting\n- **Code Quality**: Integrated linting with golangci-lint\n- **Automated Releases**: Cross-platform builds with GoReleaser\n- **GitHub Actions**: CI/CD pipelines for testing, building, and deploying\n- **Documentation**: MkDocs with Material theme, auto-deployed to GitHub Pages\n- **Cross-Platform**: Builds for Linux, macOS, and Windows (amd64/arm64)\n- **Container Support**: Docker images and Kubernetes deployment examples\n- **Package Distribution**: Homebrew tap and GitHub Container Registry\n\n## 📋 Table of Contents\n\n- [Quick Start](#-quick-start)\n- [Installation](#-installation)\n- [Development Setup](#-development-setup)\n- [Usage](#-usage)\n- [Project Structure](#-project-structure)\n- [Development](#-development)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n## ⚡ Quick Start\n\n```bash\n# Install the CLI\ngo install github.com/mavogel/cli-template@latest\n\n# Try it out\ncli-template hello\ncli-template hello --name \"Developer\"\ncli-template --version\n```\n\n## 📦 Installation\n\n### Option 1: Go Install (Recommended)\n```bash\ngo install github.com/mavogel/cli-template@latest\n```\n\n### Option 2: Homebrew\n```bash\nbrew tap mavogel/homebrew-tap\nbrew install cli-template\n```\n\n### Option 3: Download Binary\nDownload the latest release from [GitHub Releases](https://github.com/mavogel/cli-template/releases).\n\n### Option 4: Container\n```bash\ndocker run --rm ghcr.io/mavogel/cli-template:latest --help\n```\n\n## 🛠 Development Setup\n\n### Prerequisites\n\nInstall the required tools using Homebrew:\n\n```bash\n# Install Go (if not already installed)\nbrew install go\n\n# Install development tools\nbrew install golangci-lint\nbrew install goreleaser\n\n# Install Docker for documentation (MkDocs)\n# Download from https://docker.com/products/docker-desktop\n# Or install via Homebrew Cask:\nbrew install --cask docker\n```\n\n### Setup Project\n\n```bash\n# Clone the repository\ngit clone https://github.com/mavogel/cli-template.git\ncd cli-template\n\n# Install Go dependencies\ngo mod download\n\n# Verify setup\nmake all\n\n# Run tests\nmake test\n\n# Build the application\nmake build\n\n# Serve documentation locally\nmake docs-serve\n```\n\n### Development Tools Overview\n\n| Tool | Purpose | Installation |\n|------|---------|-------------|\n| **Go** | Programming language | `brew install go` |\n| **golangci-lint** | Code linting | `brew install golangci-lint` |\n| **GoReleaser** | Release automation | `brew install goreleaser` |\n| **Docker** | Documentation (MkDocs) | `brew install --cask docker` |\n| **Make** | Build automation | Usually pre-installed |\n\n## 🎯 Usage\n\n### Basic Commands\n\n```bash\n# Show help\ncli-template --help\n\n# Show version\ncli-template --version\n\n# Hello command\ncli-template hello\ncli-template hello --name \"Alice\"\ncli-template hello -n \"Bob\"\n\n# Generate shell completions\ncli-template completion bash \u003e /usr/local/etc/bash_completion.d/cli-template\ncli-template completion zsh \u003e \"${fpath[1]}/_cli-template\"\n```\n\n### Configuration\n\nThe CLI looks for configuration files in:\n- `./cli-template.yaml` (current directory)\n- `~/.cli-template.yaml` (home directory)\n- `/etc/cli-template/config.yaml` (system)\n\nExample configuration:\n```yaml\nlog_level: info\noutput_format: text\nhello:\n  default_name: \"World\"\n```\n\n## 📁 Project Structure\n\n```\ncli-template/\n├── .github/\n│   └── workflows/          # GitHub Actions CI/CD\n├── cmd/                    # Command implementations\n│   ├── root.go            # Root command\n│   ├── hello.go           # Example subcommand\n│   └── *_test.go          # Command tests\n├── docs/                  # Documentation source\n├── dist/                  # Build artifacts (generated)\n├── bin/                   # Local build output\n├── .golangci.yml         # Linting configuration\n├── .goreleaser.yaml      # Release configuration\n├── Dockerfile            # Container build\n├── Makefile              # Build automation\n├── mkdocs.yml            # Documentation config\n├── go.mod                # Go module\n└── main.go               # Application entry point\n```\n\n## 💻 Development\n\n### Available Make Targets\n\n```bash\nmake help               # Show all available targets\nmake build              # Build the binary\nmake test               # Run tests\nmake test-coverage      # Run tests with coverage\nmake lint               # Run linting\nmake lint-fix           # Run linting with auto-fix\nmake clean              # Clean build artifacts\nmake deps               # Download dependencies\nmake run                # Run the application\nmake all                # Run all checks and build\n\n# Release\nmake release-check      # Validate GoReleaser config\nmake release-snapshot   # Create snapshot build\nmake release            # Create release (requires tag)\n\n# Documentation (requires Docker)\nmake docs-serve         # Serve docs locally at http://localhost:8000\nmake docs-build         # Build documentation\nmake docs               # Build and validate docs\n```\n\n### Testing\n\n```bash\n# Run all tests\nmake test\n\n# Run with coverage\nmake test-coverage\nopen coverage.html\n\n# Run specific tests\ngo test ./cmd -run TestHelloCommand\n\n# Benchmark tests\ngo test -bench=. ./...\n```\n\n### Linting\n\n```bash\n# Run all linters\nmake lint\n\n# Auto-fix issues where possible\nmake lint-fix\n\n# Run specific linter\ngolangci-lint run --enable-only=errcheck\n```\n\n### Building\n\n```bash\n# Local build\nmake build\n\n# Cross-platform snapshot\nmake release-snapshot\n\n# Check built artifacts\nls -la dist/\n```\n\n### Documentation\n\n```bash\n# Serve locally using Docker (http://localhost:8000)\nmake docs-serve\n\n# Build documentation using Docker\nmake docs-build\n\n# View built docs\nopen site/index.html\n```\n\n## 🚀 Releases\n\n### Automated Releases\n\n1. Create and push a tag:\n   ```bash\n   git tag v1.0.0\n   git push origin v1.0.0\n   ```\n\n2. GitHub Actions automatically:\n   - Builds cross-platform binaries\n   - Creates GitHub release\n   - Publishes Docker images\n   - Updates Homebrew tap\n\n### Manual Release Testing\n\n```bash\n# Test release configuration\nmake release-check\n\n# Create snapshot (no publishing)\nmake release-snapshot\n\n# Check artifacts\nls -la dist/\n```\n\n## 🔧 Customization\n\n### Adding New Commands\n\n1. Create `cmd/newcommand.go`:\n```go\npackage cmd\n\nimport (\n    \"fmt\"\n    \"github.com/spf13/cobra\"\n)\n\nvar newCmd = \u0026cobra.Command{\n    Use:   \"new\",\n    Short: \"Description of new command\",\n    Run: func(cmd *cobra.Command, args []string) {\n        fmt.Println(\"New command executed!\")\n    },\n}\n\nfunc init() {\n    rootCmd.AddCommand(newCmd)\n}\n```\n\n2. Add tests in `cmd/newcommand_test.go`\n3. Update documentation\n\n### Modifying for Your Project\n\n1. Update `go.mod` with your module name\n2. Replace `mavogel/cli-template` in all files\n3. Update `.goreleaser.yaml` repository settings\n4. Modify `mkdocs.yml` site information\n5. Update GitHub Actions repository references\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](https://mavogel.github.io/cli-template/contributing/guidelines/) for details.\n\n### Quick Contribution Steps\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes and add tests\n4. Run tests and linting: `make all`\n5. Commit with conventional commits: `git commit -m \"feat: add amazing feature\"`\n6. Push and create a Pull Request\n\n## 📖 Documentation\n\nFull documentation is available at [https://mavogel.github.io/cli-template/](https://mavogel.github.io/cli-template/)\n\n- [Installation Guide](https://mavogel.github.io/cli-template/getting-started/installation/)\n- [Development Guide](https://mavogel.github.io/cli-template/development/project-structure/)\n- [API Reference](https://mavogel.github.io/cli-template/reference/commands/)\n- [Contributing](https://mavogel.github.io/cli-template/contributing/guidelines/)\n\n## 🐛 Issues and Support\n\n- **Bug Reports**: [GitHub Issues](https://github.com/mavogel/cli-template/issues)\n- **Feature Requests**: [GitHub Issues](https://github.com/mavogel/cli-template/issues)\n- **Questions**: [GitHub Discussions](https://github.com/mavogel/cli-template/discussions)\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Cobra](https://cobra.dev/) - Powerful CLI framework\n- [GoReleaser](https://goreleaser.com/) - Release automation\n- [golangci-lint](https://golangci-lint.run/) - Go linting\n- [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) - Documentation theme\n\n---\n\n**Made with ❤️ for the Go community**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmavogel%2Fcli-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmavogel%2Fcli-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmavogel%2Fcli-template/lists"}