### Full Post-Release Cycle Example

Source: https://context7.com/robgonnella/releasaurus/llms.txt

This sequence demonstrates a complete release process, from starting the next release to publishing it.

```bash
releasaurus release   --forge github --repo "https://github.com/org/repo"
releasaurus start-next --forge github --repo "https://github.com/org/repo"
```

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

### Install Releasaurus via cargo-binstall

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/installation.md

Use this command for the quickest installation by downloading a pre-compiled binary. Recommended for most users.

```bash
cargo binstall releasaurus
```

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

### Install Releasaurus CLI

Source: https://context7.com/robgonnella/releasaurus/llms.txt

Install the Releasaurus CLI using cargo-binstall, cargo install, or build from source. Docker installation is also available. Verify the installation with the `--version` flag.

```bash
cargo binstall releasaurus
```

```bash
cargo install releasaurus
```

```bash
git clone https://github.com/robgonnella/releasaurus.git
cd releasaurus
cargo install --path .
```

```bash
docker pull rgonnella/releasaurus:latest
docker run --rm rgonnella/releasaurus:latest --help
```

```bash
releasaurus --version
```

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

### Build and Serve Local Documentation

Source: https://github.com/robgonnella/releasaurus/blob/main/README.md

Use this command to build and serve the project's documentation locally. Ensure you have mdbook installed.

```bash
cd book
mdbook serve --open
```

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

### Global Releasaurus Configuration Example

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/configuration-reference.md

Example of a complete global configuration for Releasaurus, including base branch, release depth, and commit behavior settings.

```toml
# Global settings
base_branch = "main"
first_release_search_depth = 400
separate_pull_requests = false
auto_start_next = false
breaking_always_increment_major = true
features_always_increment_minor = true

# Global prerelease
[prerelease]
suffix = "beta"
strategy = "versioned"

```

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

### Start next development cycle

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/commands.md

Optional step to begin the next development cycle after a release has been published.

```bash
# Step 4 (Optional): Start next development cycle
releasaurus start-next \
  --forge github \
  --repo "https://github.com/owner/repo"
```

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

### Configuration File Location Example

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/configuration.md

Illustrates the standard location for the `releasaurus.toml` configuration file within a project's root directory.

```text
my-project/
├── releasaurus.toml    # ← Configuration file
├── src/
└── README.md
```

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

### Plugin System Monorepo Example

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/configuration-monorepo.md

Configure a monorepo where plugins and addons release together with the main application, ensuring all manifests are updated correctly.

```toml
[[package]]
name = "app"
workspace_root = "."
path = "."
release_type = "node"
tag_prefix = "v"
sub_packages = [
    { name = "auth-plugin", path = "plugins/auth", release_type = "node" },
    { name = "analytics-plugin", path = "plugins/analytics", release_type = "node" },
    { name = "native-addon", path = "addons/native", release_type = "node" }
]
```

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

### Install Releasaurus from Crates.io

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/installation.md

Install and compile Releasaurus from Rust's package registry. This method takes longer but ensures system compatibility.

```bash
cargo install releasaurus
```

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

### Install Development Dependencies with Mise

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/contributing.md

Ensure Mise is installed and activated. This command installs the correct Rust version and other development dependencies, and sets up environment variables for the project.

```bash
mise trust
mise install
```

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

### Prerelease Versioning Lifecycle Examples

Source: https://context7.com/robgonnella/releasaurus/llms.txt

Illustrates the versioning lifecycle for both 'versioned' and 'static' prerelease strategies. Shows how commits and suffix changes affect the version number.

```text
Versioned lifecycle:
  v1.0.0 + feat commit    → v1.1.0-alpha.1
  v1.1.0-alpha.1 + fix   → v1.1.0-alpha.2
  switch suffix to "beta" → v1.1.0-beta.1
  remove [prerelease]     → v1.1.0

Static (Java SNAPSHOT) lifecycle:
  v1.0.0 + fix commit     → v1.0.1-SNAPSHOT
  v1.0.1-SNAPSHOT + feat  → v1.1.0-SNAPSHOT
  remove [prerelease]     → v1.1.0
```

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

### Custom Changelog Template Example

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/configuration-changelog.md

An example of a custom changelog template using TOML format, defining a specific structure for the release body.

```toml
[changelog]
body = """## Release v{{ version }}

Released on {{ timestamp | date(format="%Y-%m-%d") }}

{% for group, commits in commits | group_by(attribute="group") %}
### {{ group }}
{% for commit in commits %}
- {{ commit.message }} ({{ commit.short_id }})
{% endfor %}
{% endfor %} """

```

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

### Initialize and Use Github Forge with Releasaurus

Source: https://context7.com/robgonnella/releasaurus/llms.txt

This example shows how to set up a Github forge implementation, wrap it in a ForgeManager, and prepare for release orchestration. Ensure the GITHUB_TOKEN environment variable is set.

```rust
use releasaurus_core::
{
    config::Config,
    forge::
    {
        github::Github,
        manager::{ForgeManager, ForgeOptions},
        config::Scheme,
        RepoUrl,
    },
};
use secrecy::SecretString;

#[tokio::main]
async fn main() -> color_eyre::Result<()> {
    // 1. Build a RepoUrl
    let url = RepoUrl {
        scheme: Scheme::Https,
        host: "github.com".into(),
        owner: "my-org".into(),
        name: "my-repo".into(),
        path: "my-org/my-repo".into(),
        port: None,
        token: None,
    };

    // 2. Construct the forge implementation
    let token: Option<SecretString> = std::env::var("GITHUB_TOKEN")
        .ok()
        .map(SecretString::new);
    let github = Github::new(url, token).await?;

    // 3. Wrap in a ForgeManager (set dry_run: true to preview only)
    let forge_manager = ForgeManager::new(
        Box::new(github),
        ForgeOptions { dry_run: false },
    );

    // 4. Load config + resolve packages via Resolver
    //    (see docs.rs/releasaurus-core for the full Resolver builder chain)

    // 5. Create the Orchestrator and drive the pipeline
    //    orchestrator.create_release_prs(&resolved_packages).await?;
    //    orchestrator.create_releases(&resolved_packages).await?;

    Ok(())
}

```

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

### Monorepo Configuration with Auto Start Next

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/configuration-monorepo.md

Enable automatic version bumping after a release globally, with the option to override this setting for individual packages.

```toml
auto_start_next = true

[[package]]
path = "./api"
release_type = "rust"
auto_start_next = false  # Override for this package

[[package]]
path = "./web"
release_type = "node"
# Uses global setting (true)
```

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

### Install and Run Releasaurus using Docker

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/installation.md

Utilize the official Docker image for Releasaurus. Pull the image and then run commands within a container.

```bash
# Pull the image
docker pull rgonnella/releasaurus:latest

# Run commands
docker run --rm rgonnella/releasaurus:latest --help
```

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

### Monorepo with Mixed Prerelease States

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/configuration-prerelease.md

Example of a monorepo configuration where different packages have distinct prerelease settings or are stable.

```toml
# Most packages stable, some experimental
separate_pull_requests = true

[[package]]
path = "./core"
release_type = "rust"
tag_prefix = "core-v"
# No prerelease - stable only

[[package]]
path = "./experimental"
release_type = "rust"
tag_prefix = "exp-v"
prerelease = { suffix = "alpha", strategy = "versioned" }

[[package]]
path = "./staging"
release_type = "node"
tag_prefix = "staging-v"
prerelease = { suffix = "beta", strategy = "versioned" }

```

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

### Override Global Auto Start Next for Package

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/configuration-reference.md

Use `auto_start_next` to override the global setting for a specific package, controlling whether the next version automatically starts.

```toml
[[package]]
path = "."
release_type = "node"
auto_start_next = false
```

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

### Verify Releasaurus Installation

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/installation.md

Confirm that Releasaurus has been installed correctly by checking its version.

```bash
releasaurus --version
```

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

### Releasaurus workflow example

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/commands.md

Demonstrates a typical Releasaurus workflow: generating release data, transforming author names using a Python script, and then recompiling notes with transformations.

```bash
# 1. Generate release data
releasaurus get next-release --out-file releases.json \
  --forge github --repo "https://github.com/owner/repo"

# 2. Transform data (e.g., replace author names with Slack IDs)
python transform_authors.py releases.json

# 3. Regenerate notes with transformations
releasaurus get recompiled-notes --file releases.json \
  --forge github --repo "https://github.com/owner/repo"
```

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

### Progressive Release Pipeline Configuration

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/configuration-prerelease.md

Illustrates a progressive release pipeline configuration, starting with alpha, moving to beta, and finally to stable. The prerelease configuration is commented out for each phase.

```toml
# Start in alpha, progress to beta, then stable
[[package]]
path = "."
release_type = "node"

# Phase 1: Configure alpha
# prerelease = { suffix = "alpha", strategy = "versioned" }

# Phase 2: Switch to beta when ready
# prerelease = { suffix = "beta", strategy = "versioned" }

# Phase 3: Remove prerelease for stable release

```

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

### Basic Release Workflow with Releasaurus Action

Source: https://github.com/robgonnella/releasaurus/blob/main/action/README.md

This example demonstrates a basic release workflow using the Releasaurus action. It includes steps for publishing a release and creating a release pull request. Ensure the GITHUB_TOKEN secret is available.

```yaml
name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      # Run release before release-pr to ensure pending releases are
      # published first
      - name: Publish Release
        uses: robgonnella/releasaurus/action@vX.X.X
        with:
          command: release
          command_args: >-
            --forge github
            --repo ${{ github.server_url }}/${{ github.repository }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Create Release PR
        uses: robgonnella/releasaurus/action@vX.X.X
        with:
          command: release-pr
          command_args: >-
            --forge github
            --repo ${{ github.server_url }}/${{ github.repository }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

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

### Releasaurus TOML Configuration Example

Source: https://context7.com/robgonnella/releasaurus/llms.txt

An optional TOML file placed at the repository root to enable version file updates, monorepo support, changelog customization, and prerelease workflows.

```toml
# releasaurus.toml — comprehensive example

# Global settings
base_branch = "main"
first_release_search_depth = 400
tag_search_depth = 100
separate_pull_requests = true   # one PR per package (monorepo)
auto_start_next = true          # auto-bump patch after release
breaking_always_increment_major = true
features_always_increment_minor = true

# Custom version bump triggers (additive on top of conventional commits)
custom_major_increment_regex = "\[BREAKING\]"
custom_minor_increment_regex = "\[FEATURE\]"

# Global prerelease configuration
[prerelease]
suffix = "beta"
strategy = "versioned"  # produces v1.1.0-beta.1, v1.1.0-beta.2 ...
# strategy = "static"   # produces v1.1.0-SNAPSHOT (Java style)

# Changelog settings
[changelog]
skip_ci = true
skip_chore = true
skip_miscellaneous = true
skip_merge_commits = true
skip_release_commits = true
include_author = false
aggregate_prereleases = true    # roll prerelease entries into stable notes
skip_shas = ["abc123d"]         # exclude specific commits

[[changelog.reword]]
sha = "def456e"
message = "fix: corrected security vulnerability"

```

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

### Get Command-Specific Help

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/commands.md

Display help information for a specific Releasaurus command. Replace `<cmd>` with the actual command name (e.g., `release-pr`).

```bash
# Command-specific help
releasaurus <cmd> --help
```

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

### Set Access Tokens for Git Providers

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/quick-start.md

Configure environment variables with your access tokens for GitHub, GitLab, or Gitea to authenticate with these services. Refer to the environment variables documentation for detailed setup.

```bash
# GitHub
export GITHUB_TOKEN="ghp_your_token_here"

# GitLab
export GITLAB_TOKEN="glpat_your_token_here"

# Gitea
export GITEA_TOKEN="your_token_here"
```

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

### Get General Help

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/commands.md

Display general help information for the Releasaurus CLI. This command provides an overview of available subcommands and global options.

```bash
# General help
releasaurus --help
```

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

### Start Next Release with Non-Default Base Branch

Source: https://context7.com/robgonnella/releasaurus/llms.txt

Use this command to initiate the next release cycle, specifying a custom base branch for your repository.

```bash
releasaurus start-next \
  --forge github \
  --repo "https://github.com/my-org/my-repo" \
  --base-branch develop
```

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

### Start Next Development Cycle

Source: https://context7.com/robgonnella/releasaurus/llms.txt

Begin the next development cycle by bumping patch versions in manifest files directly on the base branch. Skips packages that have never been tagged. Supports targeting specific packages.

```bash
releasaurus start-next \
  --forge github \
  --repo "https://github.com/my-org/my-repo"
```

```bash
releasaurus start-next \
  --forge github \
  --repo "https://github.com/my-org/my-repo" \
  --packages api,worker
```

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

### Start Next Release Cycle with Custom Base Branch

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/commands.md

Use this command to bump patch versions and prepare for the next development cycle, specifying a custom base branch.

```bash
releasaurus start-next \
  --forge github \
  --repo "https://github.com/owner/repo" \
  --base-branch develop
```

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

### Re-render Release Notes from JSON

Source: https://context7.com/robgonnella/releasaurus/llms.txt

Convert JSON output from `get next-release` back into formatted Markdown using a configured template. Enables custom transformations before final rendering.

```bash
# 1. Capture release data
releasaurus get next-release \
  --out-file releases.json \
  --forge github \
  --repo "https://github.com/my-org/my-repo"
```

```bash
# 2. Transform data (e.g., map author emails to Slack IDs)
python transform_authors.py releases.json
```

```bash
# 3. Re-render notes with the modified JSON
releasaurus get recompiled-notes \
  --file releases.json \
  --forge github \
  --repo "https://github.com/my-org/my-repo"
```

```bash
# Save rendered notes to file
releasaurus get recompiled-notes \
  --file releases.json \
  --out-file notes.json \
  --forge github \
  --repo "https://github.com/my-org/my-repo"
```

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

### Hybrid Release Mode with Local Path

Source: https://github.com/robgonnella/releasaurus/blob/main/action/README.md

This example shows how to use the Releasaurus action in hybrid mode with the `--local-path` option. It requires checking out the repository with the full commit history and all tags using `fetch-depth: 0`. The `actions/checkout` action must be configured accordingly.

```yaml
name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0 # required for --local-path
      - name: Create Release PR
        uses: robgonnella/releasaurus/action@vX.X.X
        with:
          command: release-pr
          command_args: >-
            --forge github
            --repo ${{ github.server_url }}/${{ github.repository }}
            --local-path ${{ github.workspace }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

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

### Start Next Release Cycle for All Packages

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/commands.md

Prepare for the next development cycle by bumping patch versions for all packages. This command creates chore commits directly on the base branch without creating PRs or tags.

```bash
releasaurus start-next \
  --forge github \
  --repo "https://github.com/owner/repo"
```

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

### get release

Source: https://context7.com/robgonnella/releasaurus/llms.txt

Retrieves an existing release by tag, fetching the tag name, commit SHA, and release notes for a specific existing release tag.

```APIDOC
## get release — Retrieve an Existing Release by Tag

Fetches the tag name, commit SHA, and release notes for a specific existing release tag.

### Usage

```bash
releasaurus get release \
  --tag v1.2.0 \
  --forge github \
  --repo "https://github.com/my-org/my-repo"

# Save to file
releasaurus get release \
  --tag v1.2.0 \
  --out-file release.json \
  --forge github \
  --repo "https://github.com/my-org/my-repo"
```

### Example JSON Output

```json
{
  "tag": "v1.2.0",
  "sha": "a1b2c3d4e5f6...",
  "notes": "## [1.2.0](...) - 2024-05-15\n### Bug Fixes\n- ..."
}
```
```

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

### Configure Changelog with Tera Templates

Source: https://context7.com/robgonnella/releasaurus/llms.txt

Customize changelog generation using TOML configuration and Tera templating. This example shows how to filter commit types and format the output, including breaking changes and author information.

```toml
[changelog]
skip_ci = true
skip_chore = true
skip_miscellaneous = true
include_author = true
aggregate_prereleases = true

body = """# [{{ version }}]({{ tag_compare_link }}) — {{ timestamp | date(format="%Y-%m-%d") }}

{% for group, commits in commits | filter(attribute="merge_commit", value=false) | sort(attribute="group") | group_by(attribute="group") %}
### {{ group }}
{% for commit in commits %}
{% if commit.breaking -%}
_({{ commit.scope }})_ **[BREAKING]**: {{ commit.title }} [({{ commit.short_id }})]({{ commit.link }}){% if include_author %} — {{ commit.author_name }}{% endif %}
{% if commit.breaking_description %}> {{ commit.breaking_description }}{% endif %}
{% else -%}
- {% if commit.scope %}_({{ commit.scope }})_ {% endif %}{{ commit.title }} [({{ commit.short_id }})]({{ commit.link }}){% if include_author %} — {{ commit.author_name }}{% endif %}
{% endif -%}
{% endfor %}
{% endfor %}"""

[[package]]
path = "."
release_type = "rust"

```

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

### Integrate Releasaurus with GitHub Actions

Source: https://context7.com/robgonnella/releasaurus/llms.txt

Automate release processes using the Releasaurus GitHub Action. This example demonstrates publishing releases and creating release pull requests within a GitHub Actions workflow.

```yaml
# .github/workflows/release.yml
name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      # Always run `release` first to publish any merged release PRs
      - name: Publish Release
        uses: robgonnella/releasaurus/action@vX.X.X
        with:
          command: release
          command_args: >-
            --forge github
            --repo ${{ github.server_url }}/${{ github.repository }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      # Then create the next release PR
      - name: Create Release PR
        uses: robgonnella/releasaurus/action@vX.X.X
        with:
          command: release-pr
          command_args: >-
            --forge github
            --repo ${{ github.server_url }}/${{ github.repository }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

```yaml
# Hybrid mode: use local checkout for git ops, forge API for PR/release
name: Release (hybrid)
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0        # required: full history + all tags
      - name: Create Release PR
        uses: robgonnella/releasaurus/action@vX.X.X
        with:
          command: release-pr
          command_args: >-
            --forge github
            --repo ${{ github.server_url }}/${{ github.repository }}
            --local-path ${{ github.workspace }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

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

### Convert release JSON to formatted notes

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/commands.md

Converts release JSON data (e.g., from `get next-release`) back into formatted release notes using a configured Tera template. This allows for custom transformations before final output.

```bash
releasaurus get recompiled-notes \
  --file releases.json \
  --forge github \
  --repo "https://github.com/owner/repo"
```

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

### Inspect Projected Releases (Bash)

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/troubleshooting.md

Use the `get next-release` command to preview Releasaurus's planned actions before creating a PR or making changes. This command can inspect all releases, specific packages, or save output to a file.

```bash
# See all projected releases
releasaurus get next-release \
  --forge github \
  --repo "https://github.com/owner/repo"

```

```bash
# Inspect specific package
releasaurus get next-release \
  --package my-pkg \
  --forge github \
  --repo "https://github.com/owner/repo"

```

```bash
# Save output to file for detailed inspection
releasaurus get next-release \
  --out-file releases.json \
  --forge github \
  --repo "https://github.com/owner/repo"

```

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

### Test locally without authentication

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/troubleshooting.md

Use this command to test version calculation, inspect commit analysis, validate configuration, preview release notes, debug tag matching, and test monorepo setup without authentication or remote changes.

```bash
releasaurus get next-release --forge local --repo "."
```

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

### Build and Run the Project with Just

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/contributing.md

Use `just` commands for common development tasks. `just build` compiles the project, `just build --release` creates a release build, and `just run` builds and executes the CLI.

```bash
just build # builds the project
just build --release # builds a release version
just run # builds and run the releasaurus cli in one command
# For example
just run --help
# Is equivalent to `cargo run -p releasaurus -- --help`
just help # show all available just recipes and their descriptions
```

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

### get recompiled-notes

Source: https://context7.com/robgonnella/releasaurus/llms.txt

Re-renders release notes from JSON data. This command converts the JSON output of `get next-release` back into formatted Markdown using the configured Tera template, enabling custom transformations before final rendering.

```APIDOC
## get recompiled-notes — Re-render Release Notes from JSON

Converts the JSON output of `get next-release` back into formatted Markdown using the configured Tera template. Enables custom transformations (e.g., replacing author names with Slack user IDs) before final rendering.

### Usage

```bash
# 1. Capture release data
releasaurus get next-release \
  --out-file releases.json \
  --forge github \
  --repo "https://github.com/my-org/my-repo"

# 2. Transform data (e.g., map author emails to Slack IDs)
python transform_authors.py releases.json

# 3. Re-render notes with the modified JSON
releasaurus get recompiled-notes \
  --file releases.json \
  --forge github \
  --repo "https://github.com/my-org/my-repo"

# Save rendered notes to file
releasaurus get recompiled-notes \
  --file releases.json \
  --out-file notes.json \
  --forge github \
  --repo "https://github.com/my-org/my-repo"
```

### Example Output

```json
[{ "name": "my-repo", "notes": "## [1.3.0](...)\n### Features\n..." }]
```
```

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

### Get Releasaurus Version

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/commands.md

Display the current version of the Releasaurus CLI. This is useful for checking compatibility or reporting issues.

```bash
# Version information
releasaurus --version
```

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

### Java Project with Static Snapshots

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/configuration-prerelease.md

Configure a Java project to use static 'SNAPSHOT' prereleases.

```toml
[prerelease]
suffix = "SNAPSHOT"
strategy = "static"

[[package]]
path = "."
release_type = "java"

```

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

### Get current releases from GitHub

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/commands.md

Retrieves information about the most recent release for all packages from a GitHub repository. This is useful for checking deployed versions.

```bash
releasaurus get current-release \
  --forge github \
  --repo "https://github.com/owner/repo"
```

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

### Retrieve an Existing Release by Tag

Source: https://context7.com/robgonnella/releasaurus/llms.txt

Fetch the tag name, commit SHA, and release notes for a specific existing release tag.

```bash
releasaurus get release \
  --tag v1.2.0 \
  --forge github \
  --repo "https://github.com/my-org/my-repo"
```

```bash
# Save to file
releasaurus get release \
  --tag v1.2.0 \
  --out-file release.json \
  --forge github \
  --repo "https://github.com/my-org/my-repo"
```

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

### Test Prerelease Configuration Locally

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/configuration-prerelease.md

Simulate prerelease version generation locally without making actual releases. This is useful for verifying your configuration settings.

```bash
releasaurus release-pr --forge local --repo "."
```

```bash
releasaurus release-pr \
  --prerelease-suffix beta \
  --forge local \
  --repo "."
```

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

### Get Projected Next Releases for Specific Package

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/commands.md

Filter projected next release information for a specific package. This is useful for debugging and custom automation.

```bash
releasaurus get next-release \
  --package my-pkg \
  --forge github \
  --repo "https://github.com/owner/repo"
```

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

### Get Projected Next Releases

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/commands.md

Query release information without making changes. This command retrieves projected next release information as JSON.

```bash
releasaurus get next-release \
  --forge github \
  --repo "https://github.com/owner/repo"
```

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

### Get Latest Published Release as JSON

Source: https://context7.com/robgonnella/releasaurus/llms.txt

Retrieve JSON for the most recently tagged release of each package. Useful for comparing deployed versions or driving notification scripts.

```bash
releasaurus get current-release \
  --forge github \
  --repo "https://github.com/my-org/my-repo"
```

```bash
# Single package
releasaurus get current-release \
  --package frontend \
  --forge github \
  --repo "https://github.com/my-org/my-repo"
```

```bash
# Save to file
releasaurus get current-release \
  --out-file current.json \
  --forge github \
  --repo "https://github.com/my-org/my-repo"
```

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

### Provide Authentication Token via Command Line

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/commands.md

Specify the authentication token directly on the command line using the `--token` flag. This is an alternative to environment variables.

```bash
--token "your_token_here"
```

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

### Verify Repository URL and Access (Bash)

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/troubleshooting.md

Ensure the repository URL is correctly formatted for your forge and that your authentication token has the necessary permissions to access it. Test with local mode if issues persist.

```bash
# Correct format examples
--forge github --repo "https://github.com/owner/repository"
--forge gitlab --repo "https://gitlab.com/group/project"
--forge gitea --repo "https://gitea.example.com/owner/repo"

```

```bash
# Clone the repository and test locally
git clone https://github.com/owner/repo
cd repo
releasaurus get next-release --forge local --repo "."

```

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

### Combine Multiple CLI Overrides

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/commands.md

Demonstrates combining global and package-specific CLI overrides for a release PR. Note the precedence rules when applying multiple settings.

```bash
releasaurus release-pr \
  --base-branch staging \
  --prerelease-suffix alpha \
  --set-package frontend.prerelease.suffix=beta \
  --forge github \
  --repo "https://github.com/owner/repo"
```

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

### Run All Tests Including Integration Tests

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/contributing.md

Execute all tests, including unit and integration tests, using the `just test-all` command. Specific integration tests for GitHub, GitLab, and Gitea can be run individually.

```bash
just test-all # run all tests including integration tests

# target just github integration tests
just test-github-integration
# target just gitlab integration tests
just test-gitlab-integration
# target just gitea integration tests
just test-gitea-integration
```

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

### Implement Custom Forge Trait for Releasaurus

Source: https://context7.com/robgonnella/releasaurus/llms.txt

This example demonstrates how to implement the `Forge` trait for a custom platform, enabling integration with Releasaurus. You must implement all async trait methods.

```rust
// Implement the Forge trait for a custom platform
use async_trait::async_trait;
use releasaurus_core::forge::traits::Forge;

pub struct MyCustomForge { /* fields */ }

#[async_trait]
impl Forge for MyCustomForge {
    fn repo_name(&self) -> String { "my-repo".into() }
    fn default_branch(&self) -> String { "main".into() }
    // ... implement all async trait methods (get_commits, create_pr, etc.)
    # fn release_link_base_url(&self) -> url::Url { todo!() }
    # fn compare_link_base_url(&self) -> url::Url { todo!() }
    # async fn load_config(&self, _: Option<String>) -> releasaurus_core::result::Result<releasaurus_core::config::Config> { todo!() }
    # async fn get_file_content(&self, _: releasaurus_core::forge::request::GetFileContentRequest) -> releasaurus_core::result::Result<Option<String>> { todo!() }
    # async fn get_release_by_tag(&self, _: &str) -> releasaurus_core::result::Result<releasaurus_core::forge::request::ReleaseByTagResponse> { todo!() }
    # async fn create_release_branch(&self, _: releasaurus_core::forge::request::CreateReleaseBranchRequest) -> releasaurus_core::result::Result<releasaurus_core::forge::request::Commit> { todo!() }
    # async fn create_commit(&self, _: releasaurus_core::forge::request::CreateCommitRequest) -> releasaurus_core::result::Result<releasaurus_core::forge::request::Commit> { todo!() }
    # async fn tag_commit(&self, _: &str, _: &str) -> releasaurus_core::result::Result<()> { todo!() }
    # async fn get_latest_tags_for_prefix(&self, _: &str, _: &str) -> releasaurus_core::result::Result<Vec<releasaurus_core::forge::request::Tag>> { todo!() }
    # async fn get_commits(&self, _: Option<String>, _: Option<String>) -> releasaurus_core::result::Result<Vec<releasaurus_core::forge::request::ForgeCommit>> { todo!() }
    # async fn get_open_release_pr(&self, _: releasaurus_core::forge::request::GetPrRequest) -> releasaurus_core::result::Result<Option<releasaurus_core::forge::request::PullRequest>> { todo!() }
    # async fn get_merged_release_pr(&self, _: releasaurus_core::forge::request::GetPrRequest) -> releasaurus_core::result::Result<Option<releasaurus_core::forge::request::PullRequest>> { todo!() }
    # async fn create_pr(&self, _: releasaurus_core::forge::request::CreatePrRequest) -> releasaurus_core::result::Result<releasaurus_core::forge::request::PullRequest> { todo!() }
    # async fn update_pr(&self, _: releasaurus_core::forge::request::UpdatePrRequest) -> releasaurus_core::result::Result<()> { todo!() }
    # async fn replace_pr_labels(&self, _: releasaurus_core::forge::request::PrLabelsRequest) -> releasaurus_core::result::Result<()> { todo!() }
    # async fn create_release(&self, _: &str, _: &str, _: &str) -> releasaurus_core::result::Result<()> { todo!() }
}
// Pass to: ForgeManager::new(Box::new(MyCustomForge { ... }), options)

```

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

### Command-Line Override for Beta Prereleases

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/configuration-prerelease.md

Use command-line flags to override prerelease settings for testing beta versions without modifying the configuration file.

```bash
releasaurus release-pr \
  --prerelease-suffix beta \
  --prerelease-strategy versioned \
  --forge github \
  --repo "https://github.com/org/repo"

```

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

### Use GitLab Token for Release PR

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/environment-variables.md

Releasaurus automatically uses the GITLAB_TOKEN environment variable for GitLab API authentication. This example shows usage for both GitLab.com and self-hosted instances.

```bash
# GitLab.com
releasaurus release-pr \
  --forge gitlab \
  --repo "https://gitlab.com/group/project"
```

```bash
# Self-hosted GitLab
releasaurus release-pr \
  --forge gitlab \
  --repo "https://gitlab.company.com/team/repo"
```

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

### Create release preparation PR

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/commands.md

Initiates the release process by creating a pull request for release preparation. This command can be run from any directory.

```bash
# Step 1: Create release preparation PR (run from anywhere)
releasaurus release-pr \
  --forge github \
  --repo "https://github.com/owner/repo"
```

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

### Get current release for a specific package

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/commands.md

Filters the current release information to a specific package within a GitHub repository. Use this to check the status of individual packages in a monorepo.

```bash
releasaurus get current-release \
  --package my-pkg \
  --forge github \
  --repo "https://github.com/owner/repo"
```

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

### Verify Authentication Tokens (Bash)

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/troubleshooting.md

Check if your authentication environment variables (GITHUB_TOKEN, GITLAB_TOKEN, GITEA_TOKEN) are set correctly. Alternatively, provide the token via the command line for specific operations.

```bash
# Check environment variable
echo $GITHUB_TOKEN
echo $GITLAB_TOKEN
echo $GITEA_TOKEN

# Or provide via command line
releasaurus release-pr \
  --forge github \
  --repo "https://github.com/owner/repo" \
  --token "your_token"

```

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

### Custom Tera Template for Changelog

Source: https://context7.com/robgonnella/releasaurus/llms.txt

Define a custom template for generating changelogs using Tera syntax. This example shows how to format version, compare links, and group commits by type.

```toml
body = """## [{{ version }}]({{ tag_compare_link }}) — {{ timestamp | date(format="%Y-%m-%d") }}
{% for group, commits in commits | filter(attribute="merge_commit", value=false) | group_by(attribute="group") %}
### {{ group }}
{% for commit in commits %}
- {% if commit.breaking %}**BREAKING**: {% endif %}{{ commit.title }} ({{ commit.short_id }})
{% endfor %}{% endfor %}"""
```

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

### Specify Additional Manifest Files for Version Updates (Simple)

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/configuration-reference.md

List additional files to update with the new version string. This simple format uses default regex patterns to find and replace version numbers in common formats.

```toml
[[package]]
path = "."
release_type = "rust"
additional_manifest_files = ["VERSION", "README.md", "docs/installation.md"]
```

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

### Set Authentication Tokens via Environment Variables

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/commands.md

Configure authentication tokens for different forges using environment variables. Releasaurus automatically selects the correct token based on the --forge flag.

```bash
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"
export GITLAB_TOKEN="glpat_xxxxxxxxxxxxxxxxxxxx"
export GITEA_TOKEN="xxxxxxxxxxxxxxxxxx"
```

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

### Start Next Release Cycle for Specific Packages

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/commands.md

Target specific packages when initiating the next development cycle. This bumps patch versions and creates chore commits directly on the base branch.

```bash
releasaurus start-next \
  --forge github \
  --repo "https://github.com/owner/repo" \
  --packages pkg-a,pkg-b
```

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

### get next-release

Source: https://context7.com/robgonnella/releasaurus/llms.txt

Inspects the projected next release by returning JSON describing the version, commits, and changelog without making any changes. This is useful for custom notifications, CI gates, and debugging configuration.

```APIDOC
## get next-release — Inspect the Projected Next Release

Returns JSON describing what would be released (version, commits, changelog) without making any changes. Useful for custom notifications, CI gates, and debugging configuration.

### Usage

```bash
# Print all projected releases as JSON
releasaurus get next-release \
  --forge github \
  --repo "https://github.com/my-org/my-repo"

# Filter to a specific package
releasaurus get next-release \
  --package api \
  --forge github \
  --repo "https://github.com/my-org/my-repo"

# Save to file for downstream processing
releasaurus get next-release \
  --out-file releases.json \
  --forge github \
  --repo "https://github.com/my-org/my-repo"

# Test locally
releasaurus get next-release --forge local --repo "."
```

### Example JSON Output

```json
[
  {
    "name": "my-repo",
    "version": "1.3.0",
    "tag": "v1.3.0",
    "notes": "## [1.3.0](...) - 2024-06-01\n### Features\n- add dark mode ...",
    "commits": [...] 
  }
]
```
```

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

### Display release notes for a specific tag

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/commands.md

Retrieves and displays the release notes for a given tag from a GitHub repository. This command helps in reviewing the content of past releases.

```bash
releasaurus get release \
  --tag v1.0.0 \
  --forge github \
  --repo "https://github.com/owner/repo"
```

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

### Get Projected Next Release as JSON

Source: https://context7.com/robgonnella/releasaurus/llms.txt

Inspect the projected next release details, including version, commits, and changelog, without making any changes. Useful for custom notifications and CI gates.

```bash
# Print all projected releases as JSON
releasaurus get next-release \
  --forge github \
  --repo "https://github.com/my-org/my-repo"
```

```bash
# Filter to a specific package
releasaurus get next-release \
  --package api \
  --forge github \
  --repo "https://github.com/my-org/my-repo"
```

```bash
# Save to file for downstream processing
releasaurus get next-release \
  --out-file releases.json \
  --forge github \
  --repo "https://github.com/my-org/my-repo"
```

```bash
# Test locally
releasaurus get next-release --forge local --repo "."
```

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

### Integrate Releasaurus with GitLab CI/CD

Source: https://context7.com/robgonnella/releasaurus/llms.txt

Utilize the Releasaurus Docker image within GitLab CI/CD pipelines for automated releases. This example shows how to configure jobs for publishing releases and creating release PRs.

```yaml
# .gitlab-ci.yml
variables:
  GIT_DEPTH: 0   # required only when using --local-path

publish-release:
  image:
    name: rgonnella/releasaurus:vX.X.X
    entrypoint: [""]
  script:
    - releasaurus release --forge gitlab --repo $CI_PROJECT_URL
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

release-pr:
  image:
    name: rgonnella/releasaurus:vX.X.X
    entrypoint: [""]
  script:
    - releasaurus release-pr --forge gitlab --repo $CI_PROJECT_URL
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

# If runner reuses workspace (GIT_STRATEGY: fetch), unshallow explicitly
before_script:
  - git fetch --unshallow || true
```

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

### Configure Prerelease Strategy and Suffix

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/configuration-reference.md

Set the prerelease identifier and versioning strategy. 'versioned' adds an incremental counter, while 'static' uses the suffix as-is.

```toml
[prerelease]
suffix = "beta"
strategy = "versioned"
```

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

### Testing Configuration Locally

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/configuration.md

Use the command line to test your Releasaurus configuration locally without making remote changes. This command simulates a release PR against your local repository.

```bash
# Test against your local repository
releasaurus release-pr --forge local --repo "."

# Review the output to verify settings
# Then run against your remote forge when ready
```

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

### Use Gitea Token for Release PR

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/environment-variables.md

Releasaurus automatically selects the GITEA_TOKEN environment variable based on the --forge flag for Gitea/Forgejo instances. This example shows usage for self-hosted Gitea and Forgejo.

```bash
# Self-hosted Gitea
releasaurus release-pr \
  --forge gitea \
  --repo "https://git.company.com/org/repo"
```

```bash
# Forgejo instance
releasaurus release-pr \
  --forge gitea \
  --repo "https://forgejo.example.com/user/project"
```

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

### Test local repository from current directory

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/troubleshooting.md

Use the --forge local and --repo "." flags to test your Releasaurus configuration and diagnose issues against your local repository from the current directory without requiring authentication or making remote changes.

```bash
releasaurus release-pr --forge local --repo "."
```

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

### Create a Release Pull Request

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/quick-start.md

Initiate a release by creating a pull request. This command analyzes commits, generates a changelog, and prepares a PR for review on the specified repository.

```bash
releasaurus release-pr \
  --forge github \
  --repo "https://github.com/your-org/your-repo"
```

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

### get current-release

Source: https://context7.com/robgonnella/releasaurus/llms.txt

Inspects the latest published release by returning JSON for the most recently tagged release of each package. Packages with no tags are omitted. This is useful for comparing deployed versions across a monorepo or driving notification scripts.

```APIDOC
## get current-release — Inspect the Latest Published Release

Returns JSON for the most recently tagged release of each package. Packages with no tags are omitted. Useful for comparing deployed versions across a monorepo or driving notification scripts.

### Usage

```bash
releasaurus get current-release \
  --forge github \
  --repo "https://github.com/my-org/my-repo"

# Single package
releasaurus get current-release \
  --package frontend \
  --forge github \
  --repo "https://github.com/my-org/my-repo"

# Save to file
releasaurus get current-release \
  --out-file current.json \
  --forge github \
  --repo "https://github.com/my-org/my-repo"
```
```

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

### Build Releasaurus from Source

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/installation.md

Build the latest development version of Releasaurus from its source code. Requires Rust 1.80+ and Git.

```bash
git clone https://github.com/robgonnella/releasaurus.git
cd releasaurus
cargo install --path .
```

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

### Configure Per-Package Prerelease Settings

Source: https://github.com/robgonnella/releasaurus/blob/main/book/src/commands.md

Configure prerelease settings on a per-package basis within the releasaurus.toml file. This allows different prerelease suffixes and strategies for individual packages.

```toml
[[package]]
path = "./packages/stable"
release_type = "rust"
# No prerelease - stable releases

[[package]]
path = "./packages/experimental"
release_type = "rust"
prerelease = { suffix = "beta", strategy = "versioned" }  # Beta releases
```