CLI

Release tools for bash workflows - a comprehensive toolkit of bash scripts for various CI/CD purposes including version management, release automation, and workflow utilities.

This toolkit represents a collection of bash scripts for various purposes. At the time of this writing, this is a work in progress, with more utilities being added as scripts are centralized from various repositories.

note

Any and all contributions are welcome; just open a PR.

Quickstart

1. Install the tools

Choose your preferred installation method:

Using curl

bash <(curl -sSL "https://github.com/releasetools/cli/releases/download/v0.0.12/install.sh")

Using wget

bash <(wget -q -O- "https://github.com/releasetools/cli/releases/download/v0.0.12/install.sh")

Using Homebrew

brew tap releasetools/tap
brew install releasetools-cli

With curl or wget, the tools are installed to ~/.local/share/releasetools/cli/VERSION/ and a binary is symlinked at ~/.local/bin/releasetools.

The rt shorthand

The Homebrew formula additionally symlinks releasetools to rt, so rt version works after brew install. That alias is specific to Homebrew — the curl, wget and GitHub Action installs provide only releasetools. This page uses the long name throughout, since it works for every installation method.

2. Utilize the releasetools library

# With ~/.local/bin in your PATH:
export PATH=~/.local/bin:"$PATH"

# You can run commands, e.g.:
releasetools version
# vX.Y.Z

# Optionally, check that all dependencies for all modules are correctly installed
releasetools base::check_deps
# Ok.

# You can also check the install location
releasetools base::install_location
# /Users/user/.local/share/releasetools/cli/vX.Y.Z/releasetools.bash

Customizations

Several customizations can be applied prior to installation:

1. Installation Directory

Customize the location where the tools will be installed:

export RELEASETOOLS_INSTALL_DIR="$HOME/.local/share"
# proceed with the installation steps outlined above

2. Binary Location

Customize the path where the binary is symlinked:

export RELEASETOOLS_BINARY_DIR="$HOME/.local/bin"
# proceed with the installation steps outlined above

GitHub Action

The releasetools/cli library can be installed via a GitHub workflow:

Basic Usage

steps:
  # Install releasetools
  - uses: releasetools/cli@v0

  # Check that releasetools was installed correctly
  - run: releasetools base::check_deps

Advanced Configuration

A few customizations are available, if needed:

steps:
  # Install releasetools with customizations
  - uses: releasetools/cli@v0
    with:
      # Pin a specific version (defaults to latest)
      version: "v0.0.12"
    env:
      # Configure the installation directory
      RELEASETOOLS_INSTALL_DIR: /home/runner/.local/share
      # Configure where binaries are linked (e.g. a directory that is already in PATH)
      RELEASETOOLS_BINARY_DIR: /home/runner/.local/bin

  # Check that releasetools was installed correctly
  - run: releasetools base::check_deps

No dependencies to install

Every module is bash over git, gh and coreutils, so the action is a single download-and-link step.

Available Commands

The releasetools CLI provides various modules and commands. Here are some common usage patterns:

Base Module

# Check version
releasetools version

# Verify all dependencies are installed
releasetools base::check_deps

# Get installation location
releasetools base::install_location

Git Module

# Create and push a release tag
releasetools git::release --major --sign --force --push v1.0.0

# Print '-dirty' if the working directory has uncommitted changes, nothing if it is clean
releasetools git::is_dirty

# Print the version tag on HEAD, without the 'v' prefix (empty if HEAD is untagged)
releasetools git::version_tag

# Print the version tag on HEAD, or the short SHA if HEAD is untagged
releasetools git::version_or_sha

# Print the short SHA of HEAD, suffixed with '-dirty' if there are uncommitted changes
releasetools git::head_sha

# Print the most recent version tag on the origin remote
releasetools git::latest_version

git::release accepts --major/-m, --sign/-s, --push/-p and --force/-f, plus exactly one vX.Y.Z version. Unknown flags and non-semver versions are rejected rather than ignored.

GitHub Module

# Extract vX.Y.Z from GITHUB_REF (or from git, when GITHUB_REF is unset)
releasetools github::get_version

# ...and also append VERSION=vX.Y.Z to the file named by $GITHUB_ENV
releasetools github::get_version --env

Listing Commands

Running releasetools with no arguments prints every available command:

releasetools

Use Cases

Release Automation

Automate your release process with standardized tagging:

name: Release

on:
  push:
    branches: [ main ]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: releasetools/cli@v0
      
      - name: Create Release
        run: |
          # Create and push a new release tag.
          # The version must be semver (vX.Y.Z) -- a date stamp such as v20260101
          # is rejected, since it has no minor or patch component.
          releasetools git::release --major --sign --push v1.2.3

Version Management

Manage versions across your projects:

# The version of the releasetools CLI itself
releasetools version

# The version tag on HEAD, or the short SHA if HEAD carries no tag
current_version=$(releasetools git::version_or_sha)

# Create a new release. git::release does not compute the next version for you --
# pass the full vX.Y.Z tag you intend to publish.
releasetools git::release --push v1.3.0

CI/CD Integration

Integrate with your existing CI/CD pipelines:

- name: Setup Release Tools
  uses: releasetools/cli@v0

- name: Validate Environment
  run: releasetools base::check_deps

- name: Deploy if Clean
  run: |
    # git::is_dirty prints '-dirty' when there are uncommitted changes and nothing
    # when the tree is clean, so test its output rather than its exit code.
    if [ -z "$(releasetools git::is_dirty)" ]; then
      echo "Working directory is clean, proceeding with deployment"
      # Your deployment commands here
    else
      echo "Working directory has uncommitted changes"
      exit 1
    fi

Development

You can find the code and development guidelines in the src/ directory.

Setting Up Development Environment

1. Clone the repository:

   git clone https://github.com/releasetools/cli.git
   cd cli

2. Install development dependencies:

   # Install any required dependencies
   pip install -r requirements.txt

3. Run tests:

   # Run the test suite
   ./scripts/test.sh

Contributing

We welcome contributions! Here's how you can help:

1. Fork the repository on GitHub
2. Create a feature branch for your changes
3. Write tests for new functionality
4. Follow existing code style and conventions
5. Submit a pull request with a clear description

Code Structure

• src/ - Main source code directory
• scripts/ - Build and utility scripts
• tests/ - Test files

Releasing

Once you have completed and tested the code, see the release instructions.

Creating a New Release

# Use releasetools itself to create releases
releasetools git::release --major --sign --force --push v1.0.0

Installation Verification

After installation, verify that releasetools is working correctly:

# Check if releasetools is in PATH
which releasetools

# Verify version
releasetools version

# Check all dependencies
releasetools base::check_deps

# List available commands
releasetools

Troubleshooting

Common Issues

releasetools: command not found

• Ensure ~/.local/bin is in your PATH
• Verify the installation completed successfully
• Check that the symlink was created: ls -la ~/.local/bin/releasetools
• If you installed with Homebrew, the binary is in Homebrew's prefix instead, and rt is available as a shorthand: command -v releasetools rt

Permission denied errors

• Make sure you have write permissions to the installation directories
• Consider customizing RELEASETOOLS_INSTALL_DIR and RELEASETOOLS_BINARY_DIR

Missing dependencies

• Run releasetools base::check_deps to identify missing requirements
• Install missing dependencies based on the error messages

GitHub Action failures

• Verify the action version is correct
• Check that required environment variables are set

Getting Help

If you encounter issues:

1. Check existing issues: Look at the GitHub Issues for similar problems
2. Run diagnostics: Use releasetools base::check_deps to identify environment issues
3. Check installation: Verify with releasetools base::install_location
4. Open an issue: Provide detailed information about your environment and the problem