ReleaseTools

https://release.tools/
Admin
ReleaseTools is an open-source suite of CI/CD utilities designed to streamline software releases,...
Tokens:24,765
Snippets:241
Trust Score:4.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install via wget

Source: https://release.tools/cli

Installs the releasetools CLI by piping a wget command into bash. Downloads the install script from the GitHub releases URL.

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

--------------------------------

### Install the releasetools CLI

Source: https://release.tools/

Install the releasetools CLI using a bash one-liner that downloads and runs the installer script from the specified URL.

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

--------------------------------

### Install CLI and Configure Mutex Action

Source: https://release.tools/intro

Commands to install the ReleaseTools CLI via bash and an example configuration for using the Mutex GitHub Action to lock a resource.

```bash
# Install CLI  
bash <(curl -sSL "https://github.com/releasetools/cli/releases/download/v0.0.12/install.sh")  
  
# Or use mutex in your GitHub Action  
- uses: releasetools/mutex@v1  
  with:  
    command: "lock"  
    id: "my-resource"
```

--------------------------------

### Install via Homebrew

Source: https://release.tools/cli

Installs the releasetools CLI using Homebrew by tapping a custom tap and installing the formula. This method also symlinks the binary as 'rt'.

```bash
brew tap releasetools/tap  
brew install releasetools-cli  
```

--------------------------------

### Install dependencies and pre-commit hooks

Source: https://release.tools/mutex

Install npm dependencies and run the prepare script to set up pre-commit hooks.

```bash
npm install  
npm run prepare  

```

--------------------------------

### Install via curl

Source: https://release.tools/cli

Installs the releasetools CLI by piping a curl command into bash. Fetches the install script from the GitHub releases URL.

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

--------------------------------

### Install plugin with Claude

Source: https://release.tools/release-notes

Commands to add and install the release-notes plugin using the Claude marketplace.

```bash
claude plugin marketplace add releasetools/agent-plugins  
claude plugin install release-notes@release-tools
```

--------------------------------

### Verify releasetools installation

Source: https://release.tools/cli

Verify the installation by checking the PATH, version, dependencies, and available commands.

```bash
# Check if releasetools is in PATH  
which releasetools  
  
# Verify version  
releasetools version  
  
# Check all dependencies  
releasetools base::check_deps  
  
# List available commands  
releasetools  

```

--------------------------------

### Install development dependencies

Source: https://release.tools/cli

Install the development dependencies listed in requirements.txt using pip.

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

```

--------------------------------

### Install releasetools CLI in GitHub Action

Source: https://release.tools/cli

Basic GitHub Action workflow step to install the releasetools CLI and verify the installation with `releasetools base::check_deps`.

```yaml
steps:  
  # Install releasetools  
  - uses: releasetools/cli@v0  
  
  # Check that releasetools was installed correctly  
  - run: releasetools base::check_deps  

```

--------------------------------

### Prepare a release for a subtree

Source: https://release.tools/release-notes

Example command to prepare a release entry for a specific plugin directory within a monorepo.

```bash
/release-notes:prepare 0.3.0 --path plugins/release-notes
```

--------------------------------

### Install plugin with Codex

Source: https://release.tools/release-notes

Commands to add and install the release-notes plugin using the Codex marketplace.

```bash
codex plugin marketplace add releasetools/agent-plugins  
codex plugin add release-notes@release-tools
```

--------------------------------

### Utilize the releasetools library

Source: https://release.tools/cli

Adds the CLI to PATH, runs version, dependency check, and install location commands. The version command outputs vX.Y.Z, dependencies check outputs 'Ok.', and install location outputs the full path to releasetools.bash.

```bash
# With ~/.local/bin in your PATH:  
export PATH=~/.local/bin:"$PATH"  
  
# You can run commands, e.g. (the installers also link the shorter name 'rt'):  
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
```

--------------------------------

### Install plugin with Hermes and Antigravity

Source: https://release.tools/release-notes

Commands to install the plugin for Hermes and Antigravity by cloning the repository.

```bash
hermes plugins install releasetools/agent-plugins/plugins/release-notes  
agy plugin install https://github.com/releasetools/agent-plugins
```

--------------------------------

### Base module commands

Source: https://release.tools/cli

Common base module commands: check the version, verify dependencies, and get the installation location.

```bash
# Check version  
releasetools version  
  
# Verify all dependencies are installed  
releasetools base::check_deps  
  
# Get installation location  
releasetools base::install_location  

```

--------------------------------

### GitHub Action: Install releasetools CLI

Source: https://release.tools/cli

Installation instructions for the releasetools CLI via GitHub Actions, including basic usage and advanced configuration options.

```APIDOC
## GitHub Action: Install releasetools CLI

### Description
Installs the `releasetools/cli` library in a GitHub Actions workflow. The action is a single download-and-link step with no dependencies to install.

### Usage
```yaml
steps:
  # Install releasetools
  - uses: releasetools/cli@v0

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

### Advanced Configuration
```yaml
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
```

### Parameters
#### Inputs
- **version** (string) - Optional - Pin a specific version (defaults to latest).

#### Environment Variables
- **RELEASETOOLS_INSTALL_DIR** (string) - Optional - Configure the installation directory.
- **RELEASETOOLS_BINARY_DIR** (string) - Optional - Configure where binaries are linked (e.g. a directory that is already in PATH).
```

--------------------------------

### Install mutex globally via npm and check version

Source: https://release.tools/mutex

Installs the mutex CLI globally from npm using the @1 tag to get the newest v1 release. Requires Node.js 24 or newer. npm does not update global installations automatically, so re-run to upgrade.

```bash
npm install --global @releasetools/mutex@1  
mutex version  

```

--------------------------------

### Install mutex plugin for Claude

Source: https://release.tools/mutex

Commands to add the marketplace and install the mutex plugin for Claude.

```bash
claude plugin marketplace add releasetools/agent-plugins  
claude plugin install mutex@release-tools  
```

--------------------------------

### Example version movement report

Source: https://release.tools/versions-guard

The tool outputs one line per project showing the version change, followed by a final verdict.

```text
packages/api 0.2.0 -> 0.2.1  
packages/web is new, at 0.1.0  
Every changed project moved its version far enough  

```

--------------------------------

### Customize installation directory

Source: https://release.tools/cli

Sets the environment variable RELEASETOOLS_INSTALL_DIR to customize where the tools are installed. Use before running the installation commands.

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

--------------------------------

### Install mutex plugin for Codex

Source: https://release.tools/mutex

Commands to add the marketplace and install the mutex plugin for Codex.

```bash
codex plugin marketplace add releasetools/agent-plugins  
codex plugin add mutex@release-tools  
```

--------------------------------

### Install Release Notes Plugin for Claude

Source: https://release.tools/intro

Commands to add the ReleaseTools plugin marketplace and install the release-notes plugin for a coding agent.

```bash
# Or add the plugin marketplace to your coding agent  
claude plugin marketplace add releasetools/agent-plugins  
claude plugin install release-notes@release-tools
```

--------------------------------

### Example release note block

Source: https://release.tools/release-notes

A sample release note formatted within a fenced block, used to declare observable changes.

```text
```release-note  
Batch mode processes up to 10,000 records per request. Enable it with the  
batch=true query parameter.  
```
```

--------------------------------

### releasetools net::await_url

Source: https://release.tools/cli

Waits for a URL to start serving, backing off 15s, 30s, 60s, 120s, 240s.

```APIDOC
## `releasetools net::await_url`

### Description
Wait for a URL to start serving, backing off 15s, 30s, 60s, 120s, 240s.

### Usage
```
releasetools net::await_url https://pypi.org/pypi/my-package/1.2.3/json
```

### Parameters
- `url` (string) - Required - The URL to wait for.

### Behavior
- Backs off with delays: 15s, 30s, 60s, 120s, 240s.
- Distinguishes transport failures from status codes (curl returns `000` for outages).

```

--------------------------------

### Advanced releasetools GitHub Action configuration

Source: https://release.tools/cli

Advanced GitHub Action configuration for installing releasetools with a pinned version and custom installation and binary directories. The `version` input defaults to latest, and the environment variables configure where the CLI is installed and linked.

```yaml
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  

```

--------------------------------

### Direct profile with ssl_negotiation

Source: https://release.tools/mutex

Example direct profile with ssl_negotiation set to 'direct'. This enables immediate TLS handshake, saving a round trip, but requires PostgreSQL 17 or newer.

```toml
[direct]  
mode = "direct"  
default = true  
ssl_negotiation = "direct"  

```

--------------------------------

### Install mutex via mise with Node.js and allow_low_downloads

Source: https://release.tools/mutex

Installs Node.js 24 and the mutex npm package via mise in one command. The allow_low_downloads=true flag is required because the package is below mise's download-count threshold. Requires mise 2026.8.8 or newer. With mise activated, mutex runs directly; otherwise use 'mise exec -- mutex'.

```bash
mise use --global node@24 \  
  'npm:@releasetools/mutex[allow_low_downloads=true]@1'  
mutex version  

```

--------------------------------

### Verbose Database Connection Output

Source: https://release.tools/mutex

Example output when running a command with --verbose to verify the applied SSL mode.

```text
Database connection: sslmode=require applied as verify-full.  
```

--------------------------------

### Successful changelog verification output

Source: https://release.tools/changelog-guard

Example output when the changelog-guard successfully verifies that all changed projects have been recorded.

```text
packages/api 0.2.1  
Every changed project recorded what changed  
```

--------------------------------

### Install exact mutex version via mise

Source: https://release.tools/mutex

Installs a specific mutex version (1.4.0) immediately, bypassing the minimum_release_age delay. This is used by the project's own release to verify a publication seconds after making it.

```bash
mise use --global \  
  'npm:@releasetools/mutex[allow_low_downloads=true]@1.4.0'  

```

--------------------------------

### List locks with ownership filters

Source: https://release.tools/mutex

Examples of using the list command to filter locks by owner or retrieve all locks.

```bash
mutex list --owner "$CI_RUN"   # only that owner's locks  
mutex list                     # every lock, or $MUTEX_OWNER's when that is set  
mutex list --owner ''          # names nobody, so every lock again  
```

--------------------------------

### Versions guard failure message example

Source: https://release.tools/versions-guard

Example of the failure message the action produces when a version is not bumped enough. It shows the package, current version, required version, and the commit type that triggered the requirement.

```text
Version not bumped  
  packages/api is at 1.2.4, and a feat (read Cargo.toml) asks for at least  
  1.3.0 after 1.2.3. Somebody has 1.2.3 installed, and a client compares  
  versions to decide whether an update exists.  

```

--------------------------------

### Server log line format

Source: https://release.tools/mutex

Example log line appended to <working_dir>/mutex-<profile>.log for each server-side operation. Fields are separated by pipes and include timestamp, operation, target, user, client IP, and hostname.

```text
|2026-08-16T14:32:09.417Z|lock|deploy|alice|127.0.0.1|workstation.local|  

```

--------------------------------

### Use mutex in your GitHub Action

Source: https://release.tools/

Example GitHub Action step that uses the mutex action to acquire a lock with a command and an ID.

```yaml
- uses: releasetools/mutex@v1
  with:
    command: "lock"
    id: "my-resource"
```

--------------------------------

### profiles.toml with server and direct profiles

Source: https://release.tools/mutex

Example profiles.toml generated by 'mutex profile'. It defines a server profile as default and a direct profile as non-default. The server profile binds to localhost:5625 and sets a working directory.

```toml
[server]  
mode = "server"  
default = true  
bind_address = "localhost:5625"  
working_dir = "/home/alice/.config/releasetools-mutex"  
  
[direct]  
mode = "direct"  
default = false  

```

--------------------------------

### Customize binary location

Source: https://release.tools/cli

Sets the environment variable RELEASETOOLS_BINARY_DIR to customize where the binary symlink is created. Use before running the installation commands.

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

--------------------------------

### Clone the repository

Source: https://release.tools/cli

Clone the repository and navigate into the project directory to set up the development environment.

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

```

--------------------------------

### List all commands

Source: https://release.tools/cli

Running releasetools with no arguments prints every available command.

```bash
releasetools  

```

--------------------------------

### Create a new release with releasetools

Source: https://release.tools/cli

Create a new release using releasetools itself, specifying a major version bump, signing, forcing, and pushing.

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

```

--------------------------------

### releasetools (no arguments)

Source: https://release.tools/cli

Prints every available command when run with no arguments.

```APIDOC
## `releasetools`

### Description
Running `releasetools` with no arguments prints every available command.

### Usage
```
releasetools
```

```

--------------------------------

### Create a GitHub release with notes

Source: https://release.tools/release-notes

Command to create a GitHub release using the generated RELEASE_EDITMSG file as the release notes.

```bash
gh release create "v${VERSION}" --notes-file "$(git rev-parse --path-format=absolute --git-path RELEASE_EDITMSG)"
```

--------------------------------

### Run tests

Source: https://release.tools/cli

Run the project's test suite using the provided script.

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

```

--------------------------------

### Example of version mismatch error

Source: https://release.tools/versions-guard

Shows the error message generated when files defined in the manifest contain conflicting version numbers.

```text
Version not bumped  
  services/api declares 2.1.0 in services/api/package.json and 2.0.0 in  
  services/api/VERSION. Whichever a client reads is the one that decides  
  whether it updates, so they have to say the same thing.  
```

--------------------------------

### Define projects in .releasetools.yaml

Source: https://release.tools/changelog-guard

Specify the project paths, manifest files, and changelog locations in the .releasetools.yaml file at the repository root.

```yaml
projects:  
  - path:  
      - packages/api  
      - packages/web  
    manifest: package.json  
    changelog: CHANGELOG.md  
```

--------------------------------

### Set VERSION from git::version_tag

Source: https://release.tools/cli

Replacement for the removed github::get_version. Writes the tag printed by git::version_tag into GITHUB_ENV as VERSION.

```bash
echo "VERSION=$(releasetools git::version_tag)" >>"$GITHUB_ENV"  

```

--------------------------------

### Changelog update failure message

Source: https://release.tools/changelog-guard

Example of the error message reported when a project's changelog lacks the required section for the current version.

```text
Changelog not updated  
  packages/api/CHANGELOG.md has no section for 2.1.0. Add one above the  
  older releases: what changed, and the reason not to act that a later  
  change cannot get from the diff.  
```

--------------------------------

### Version management commands with releasetools CLI

Source: https://release.tools/cli

Shell commands for managing versions: display the CLI version, get the current version tag or short SHA, and create a release. Note that git::release requires the full vX.Y.Z tag; it does not compute the next version automatically.

```bash
# 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  
```

--------------------------------

### releasetools release::prechecks

Source: https://release.tools/cli

Runs prechecks for a release: version format, clean working tree, tag free on remote, version after newest release tag, HEAD on branch, and registry returns 404.

```APIDOC
## `releasetools release::prechecks`

### Description
Run prechecks for a release. Checks in order: version is `x.y.z`, working tree is clean, tag is free on remote, version is after the newest release tag, HEAD is on the branch, and registry answers 404 for it.

### Usage
```
releasetools release::prechecks 1.2.3 \
  --branch main \
  --check-registry-url "https://pypi.org/pypi/my-package/1.2.3/json"
```

### Parameters
- `version` (string) - Required - The version to check (must be `x.y.z`).
- `--branch` (string) - Required - The branch to check HEAD is on.
- `--check-registry-url` (string) - Required - The registry URL to check for 404.

### Behavior
- Checks are performed in order, cheapest first.
- A prerelease sorts below the release it leads to (e.g., `2.0.0` is after `v2.0.0-rc1`).

```

--------------------------------

### Net module commands

Source: https://release.tools/cli

Net module commands: net::status prints an HTTP status code, net::await_url waits for a URL to start serving with backoff 15s, 30s, 60s, 120s, 240s. Transport failures are distinct from status codes because curl reports outages as 000. Every request carries a User-Agent, which crates.io requires.

```bash
# Print an HTTP status code  
releasetools net::status https://pypi.org/pypi/my-package/1.2.3/json  
  
# Wait for a URL to start serving, backing off 15s, 30s, 60s, 120s, 240s  
releasetools net::await_url https://pypi.org/pypi/my-package/1.2.3/json  

```

--------------------------------

### Declare a project with multiple manifest files

Source: https://release.tools/versions-guard

Shows a project whose version is kept in two manifest files, both listed under manifest. The guard checks that both stay in step.

```yaml
projects:  
  - path: plugins/mutex  
    manifest:  
      - .claude-plugin/plugin.json  
      - .codex-plugin/plugin.json  
    changelog: CHANGELOG.md  

```

--------------------------------

### Clone the Mutex repository

Source: https://release.tools/mutex

Clone the repository from GitHub and navigate into the project directory.

```bash
git clone https://github.com/releasetools/mutex.git  
cd mutex  

```
Tokens:
Raw