A modular template for building high-performance, cross-platform CLI tools for Liferay DXP, Liferay Cloud (LXC), and Client Extensions.
- Bot Pull Requests:
.github/rulesets/protect-main.jsonand a Repository Settings section set up the default branch the wayliferay-docker-managerdoes: pull requests required with 0 approvals, squash only, no bypass actors, and GitHub Actions allowed to open pull requests. no-issue-neededLabel: Dependabot pull requests carry it, alongside the defaultdependenciesand ecosystem labels.
- Version Gate: The release workflow rejects tags that don't match the
Cargo.tomlversion, so--versionalways reports the released version. --versionFlag: The CLI exposes--version, and the Homebrew formula test checks it.- Distribution Fixes: The distribution prompt keeps
formula.rb.exampleandscoop.json.examplefor future releases and skips Scoop updates the bucket already automates.
- Release Management & Changelog: Adopted release management architecture from
ai-agent-templatewithCHANGELOG.mdand automated release note extraction viascripts/release.py. - Dynamic Binary Derivation: Release workflows dynamically derive binary and asset names from
Cargo.toml, removing template placeholders. - Doctor Verification Gate: Added
scripts/doctor.pyand pre-commit hook integration to guard against unreplaced placeholders. - Intel macOS Release Target: Cross-compiles
x86_64-apple-darwinbinaries onmacos-latestrunners alongside Apple Silicon. - Pinned Actions & Dependabot: All GitHub Actions pinned to immutable commit SHAs with automated weekly Dependabot updates.
- Modernized Dependencies: Upgraded core and optional dependencies (
reqwest 0.13,scraper 0.27,serde 1.0,clap 4.5, etc.).
- Cross-Platform: GitHub Actions pre-configured for Windows, Linux, and macOS (ARM/Intel).
- Liferay Aware: Logic for path resolution and product version detection from
gradle.properties. - Modern CLI: Built on
clapfor a professional command-line experience.
.
├── .cargo/config.toml # Cargo aliases (lint, fmt-check)
├── .gemini/prompts/ # Automated Gemini CLI workflows
├── .github/
│ ├── dependabot.yml # Automated dependency maintenance
│ ├── rulesets/ # Default branch protection (see Repository Settings)
│ └── workflows/ # Multi-OS CI/CD (Release, Rust)
├── .githooks/pre-commit # Shared cross-platform git hook
├── scripts/
│ ├── doctor.py # Placeholder verification gate
│ └── release.py # Changelog extraction and tagging
├── src/
│ ├── main.rs # Command routing
│ ├── core/
│ │ ├── mod.rs # Core traits
│ │ └── env.rs # Project discovery logic
│ ├── utils/
│ │ ├── mod.rs # Utility re-exports
│ │ ├── git.rs # Git wrappers
│ │ └── xml.rs # Recursive XML logic
│ └── cli.rs # Command definitions
├── CHANGELOG.md # Keep a Changelog history
├── formula.rb.example # Homebrew template
├── scoop.json.example # Scoop template
├── .gitignore # Tracks Cargo.lock for reliable CI
├── Cargo.toml # Feature-based dependencies
└── LICENSE (MIT)
- Rust:
cargo,rustc,rustfmt,clippy. - Git Hooks: To ensure consistent code style, activate the shared pre-commit hooks:
- Run:
git config core.hooksPath .githooks. - On macOS/Linux:
chmod +x .githooks/pre-commit. - This hook automatically runs
scripts/doctor.py,cargo fmt, andcargo clippybefore each commit.
- Run:
- Click "Use this template" on GitHub to create your new repository.
- Automated Initialization: Once cloned, ask Gemini to set up your new tool:
Gemini will automatically gather your project metadata (name, description, features) and update core configuration files (
"Please execute .gemini/prompts/setup-new-tool.md to initialize my new project"Cargo.tomland thisREADME.md) for you. Release workflows automatically derive binary names directly fromCargo.toml. - Manual Customization:
- Customize subcommands in
src/cli.rs. - Update
LICENSEif necessary.
- Customize subcommands in
- First Release: Follow Releasing. Pushing a tag such as
v0.1.0builds and publishes binaries for all major operating systems.
Once a release is published and distribution channels are updated, users can install the tool using these commands:
brew tap [github-user]/homebrew-tap
brew install [tool-name]scoop bucket add [github-user] https://github.com/[github-user]/scoop-bucket
scoop install [tool-name]# Build locally
cargo build
# Run with arguments
cargo run -- --helpApply these once per new repository so that both people and bots change the default branch through pull requests, with no bypass actors:
REPO=[github-user]/[tool-name]
# Squash merges only, auto-merge on, and branches deleted after merge
gh api -X PATCH repos/$REPO -F allow_auto_merge=true -F delete_branch_on_merge=true \
-F allow_squash_merge=true -F allow_merge_commit=false -F allow_rebase_merge=false
# Let GitHub Actions open pull requests
gh api -X PUT repos/$REPO/actions/permissions/workflow \
-f default_workflow_permissions=write -F can_approve_pull_request_reviews=true
# Label for pull requests that intentionally have no linked issue (Dependabot uses it)
gh label create no-issue-needed -R $REPO --color ededed \
--description "PR intentionally has no linked issue (bot or trivial change)"
# Protect the default branch: pull request required, 0 approvals, squash only, linear history
gh api -X POST repos/$REPO/rulesets --input .github/rulesets/protect-main.jsonA workflow that needs to change the default branch should push a dated branch, open a pull request, add the no-issue-needed label, and run gh pr merge --auto --squash.
- Bump
versioninCargo.tomland runcargo buildto updateCargo.lock. - Move the
[Unreleased]entries inCHANGELOG.mdinto a new## [x.y.z] - YYYY-MM-DDsection. - Commit, then create an annotated tag and push it:
The release workflow fails if the tag isn't annotated, doesn't match
python3 scripts/release.py --tag vX.Y.Z git push origin vX.Y.Z
Cargo.toml, or has noCHANGELOG.mdsection. - For a tool's first release, add it to the distribution channels (see below). After that, the Homebrew tap and Scoop bucket pick up new releases automatically within a couple of hours.
To avoid "Unidentified Developer" warnings on macOS and ensure a secure, user-level installation on Windows, we recommend building from source via Homebrew or Scoop.
By default, Homebrew assumes your homebrew-tap and the tool's source repository are public.
If you wish to keep your distribution repositories private:
- Users must have a GitHub Personal Access Token (PAT) with
reposcope. - Users should export this token in their environment:
export HOMEBREW_GITHUB_API_TOKEN=your_token_here - Without a token,
brew tapandbrew installwill fail for private repositories.
This template includes an automated prompt for Gemini CLI to handle updating your Homebrew tap and Scoop bucket repositories with new releases.
Once a tool is in the tap and bucket, both update themselves from new GitHub releases, so this is only needed for a tool's first release. Ask Gemini:
"Please execute the steps in .gemini/prompts/update-distribution-channels.md to update my distribution repositories"Gemini will automatically:
- Extract metadata from
Cargo.toml. - Calculate the SHA256 hash of the release tarball.
- Generate and write the Homebrew formula (
formula.rb.example) and Scoop manifest (scoop.json.example). - Commit and push the updates to your local
homebrew-tapandscoop-bucketrepositories.
Last Updated: 2026-11-11 | Last Reviewed: 2026-11-11