Command Reference

flopha last-version

Print the latest matching version.

flopha last-version [--pattern <pattern>] [--source <tag|branch>] [--checkout] [--format <text|json>]

Options:

• --pattern, -p: Match a custom version format. {semver} expands to {major}.{minor}.{patch}.
• --source, -s: Read versions from tags or branches. Default is tag.
• --checkout: Check out the resolved version after printing it.
• --format, -f: Output format — text (default) or json.

flopha next-version

Calculate the next version.

flopha next-version \
  [--initial-version <MAJOR.MINOR.PATCH>] \
  [--increment <major|minor|patch>] \
  [--auto] \
  [--rule <level:regex>] \
  [--pre <channel>] \
  [--pattern <pattern>] \
  [--source <tag|branch>] \
  [--create] \
  [--tag-message <message>] \
  [--push] \
  [--format <text|json>]

Options:

• --initial-version: Use a bare MAJOR.MINOR.PATCH directly when no version matches the pattern; otherwise use normal bump behavior.
• --increment, -i: Explicit bump level. Default is patch.
• --auto: Detect the bump from commit messages since the last version.
• --rule: Replace the built-in auto-detection rules. Requires --auto.
• --pre: Create a pre-release tag like -alpha.1 or -rc.1.
• --pattern, -p: Match and generate a custom version format. {semver} expands to {major}.{minor}.{patch}.
• --source, -s: Read versions from tags or branches. Default is tag.
• --create: Create the new tag or branch after printing it.
• --tag-message: Create an annotated tag with the given message. Requires --create and tag source.
• --push: Push the created tag or branch to origin. Requires --create.
• --format, -f: Output format — text (default) or json.

flopha log

Show matching versions newest first.

flopha log [--pattern <pattern>] [--source <tag|branch>] [--limit <number>] [--format <text|json>]

Options:

• --pattern, -p: Match a custom version format. {semver} expands to {major}.{minor}.{patch}.
• --source, -s: Read versions from tags or branches. Default is tag.
• --limit, -n: Limit the number of rows.
• --format, -f: Output format — text (default) or json.

flopha changelog

Generate a changelog from commits since the last (or a given) version.

flopha changelog \
  [--from <tag>] \
  [--to <tag>] \
  [--pattern <pattern>] \
  [--source <tag|branch>] \
  [--group <TITLE:REGEX>] \
  [--other <title>] \
  [--title <template>] \
  [--output <file>] \
  [--overwrite] \
  [--format <text|json>]

Options:

• --from: Tag to start from. Defaults to the latest matching tag.
• --to: Existing tag or ref to use as the upper bound for the changelog. The value must exist in Git because it limits which commits are included. It is exposed as {to} in --title.
• --pattern, -p: Match a custom version format. {semver} expands to {major}.{minor}.{patch}.
• --source, -s: Read versions from tags or branches. Default is tag.
• --group: Custom group rule as TITLE:REGEX. Repeatable. When any --group flags are given they replace the built-in defaults entirely. Commits not matching any group are collected under the fallback group.
• --other: Title for commits that match no group. Pass an empty string to suppress them entirely. Default: "Other Changes".
• --title: Heading template. Use {from} for the starting tag and {to} when --to is supplied. Defaults to "Changes in {to}" when --to is given, otherwise "Changelog since {from}". Use --title directly when naming an upcoming version before its tag exists.
• --output, -o: Write to a file instead of stdout. By default the new content is prepended to any existing file content.
• --overwrite: Replace the output file instead of prepending.
• --format, -f: Output format — text (default, Markdown) or json.

Default groups

When no --group flags are provided, commits are classified as:

Section	Matched commits
Breaking Changes	BREAKING CHANGE, BREAKING-CHANGE, or type!:
Features	feat: or feat(scope):
Bug Fixes	fix: or fix(scope):
Other Changes	Everything else

JSON output schema

{
  "title": "Changes in v1.2.0",
  "from": "v1.1.0",
  "to": "v1.2.0",
  "groups": [
    {
      "title": "Features",
      "entries": [
        { "subject": "add search command", "hash": "abc1234" }
      ]
    }
  ]
}

to is only present when --to was supplied. Groups with no matching commits are omitted.

flopha release

Prepare or publish a release using flopha.toml.

flopha release [--config <file>] [--initial-version <MAJOR.MINOR.PATCH>] [--prepare | --require-version-match] [--dry-run] [--format <text|json>]

• --config, -c: Config path relative to the repository root. Default: flopha.toml.
• --initial-version: Override [version].initial_version for the first release.
• --prepare: Update configured manifests only, leaving changes unstaged for a release PR. No commit, tag, push, or GitHub Release is created.
• --require-version-match: Fail if manifests differ from the calculated version; otherwise publish without a version commit. Actual releases require committed files. Cannot be combined with --prepare.
• --dry-run: Preview without writing files or publishing. With --require-version-match, also validate the prepared files.
• --format, -f: Text (default) or JSON for previews and preparation. Preparation JSON is {"version":"<tag>"}; a no-op returns null.

Both --prepare and --require-version-match need at least one [[manifest]] target. Without either option, release updates and commits manifests before tagging and publishing. See Release Workflows for the PR preparation and recovery process.

flopha.toml

Every key is optional. An empty file releases with the defaults below and creates no GitHub Release.

[version]
# initial_version = "0.1.0"            # used directly only when no matching version tag exists
pattern = "v{major}.{minor}.{patch}"   # default
auto = true                            # detect bump level from conventional commits (default)
# increment = "patch"                  # used instead of auto-detection when auto = false
# rules = ["major:BREAKING CHANGE", "minor:^feat"]
# pre = "beta"                         # pre-release channel, e.g. v1.2.3-beta.1
# tag_message = "Release {tag}"        # annotated tag message; supports {tag} and {version}

[changelog]
enabled = true
# groups = ["Breaking Changes:BREAKING CHANGE", "Features:^feat"]
# other = "Other Changes"
# title = "Changes in {to}"

[release]
create = true                         # default: false; publish a GitHub Release
draft = false
# title = "{tag}"                     # supports {tag} and {version}
# body = "..."                        # falls back to the generated changelog, then generate_notes
# generate_notes = false
# repo = "owner/repo"                 # defaults to parsing the `origin` remote

[[manifest]]
path = "Cargo.toml"
type = "cargo"                        # sets [package].version (or [workspace.package].version) and Cargo.lock

[[manifest]]
path = "package.json"
type = "npm"                          # sets the top-level "version" field

[[manifest]]
path = "pyproject.toml"
type = "pyproject"                    # sets [project].version, falling back to [tool.poetry].version

[[manifest]]
path = "docs/VERSION"
type = "regex"
pattern = "(?m)^version=.*$"
replacement = "version={version}"     # {version} is substituted with the new version

• Safe to re-run: on a commit that is already tagged, release finishes that release (pushes the tag, creates a missing GitHub Release) instead of cutting a new one, and with no new commits it does nothing.
• When releasing with automatic manifest commits, the working tree must be clean and the branch up to date with origin. If pushing the release commit fails, the local commit and tag are undone.
• release.create needs a GitHub token in GH_TOKEN or GITHUB_TOKEN. Locally, an existing gh auth login also works.
• Cargo workspace targets use cargo metadata --no-deps --offline --locked to identify packages inheriting the workspace version; Cargo must be installed. Fixed-version members are preserved.
• version.source = "branch" is not supported. For branch-based versioning, use flopha next-version --source branch --create.

Global behavior

• --verbose, -v enables debug logging.
• The CLI fetches from the origin remote before resolving versions.
• The default version pattern is v{major}.{minor}.{patch}. Use v{semver} as a shorter equivalent.

When no version matches the pattern, next-version and release fail unless an initial version is supplied; --auto does not select one. Use three unsigned 32-bit components without leading zeros, tag prefixes, pre-release suffixes, or build metadata. Use --pre / version.pre for pre-releases. See First release for examples.