Productify

Appearance

pfy version ​

pfy version reads and changes the version: field in project.yaml. Use it to show the current version, set an exact value, or bump major/minor/patch (with optional pre-release labels).

Synopsis ​

bash
pfy version <subcommand> [flags]

Description ​

The version command group provides tools for managing your project's semantic version stored in project.yaml. Supports showing, setting, and incrementing versions according to semver 2.0.0.

TIP

pfy version manages the project version. To print the CLI binary's own version, use the global pfy --version flag; it reports the version stamped into the binary at build time, not anything from project.yaml.

Subcommands ​

pfy version show ​

Display the current project version.

bash
pfy version show

Output:

1.2.3

Use Cases:

  • Check current version before release
  • Use in scripts: VERSION=$(pfy version show)
  • Verify version after bump

pfy version set ​

Set the project version to a specific value.

bash
pfy version set --version <version>

Flags:

  • --version (required): the new version string

set does not validate the value. Whatever you pass is written to project.yaml; a malformed value is only rejected by the next version bump. See Error Handling.

Examples:

bash
# Set to specific version
pfy version set --version 2.0.0

# Output:
# Version updated: 1.2.3 → 2.0.0
# Configuration saved to project.yaml

Use Cases:

  • Align with external version numbers
  • Reset version after major refactor
  • Match version to git tag

pfy version bump ​

Increment the project version using semantic versioning rules.

bash
pfy version bump --part <major|minor|patch>

Flags:

  • --part: Version component to increment (default: patch)
    • major: Breaking changes (1.2.3 → 2.0.0)
    • minor: New features (1.2.3 → 1.3.0)
    • patch: Bug fixes (1.2.3 → 1.2.4)
  • --pre: Pre-release label to attach or advance (e.g., --part minor --pre rc gives 1.2.3 → 1.3.0-rc.1). Omit it to cut a normal release.

Examples:

bash
# Increment patch version (default)
pfy version bump
# or explicitly:
pfy version bump --part patch
# 1.2.3 → 1.2.4

# Increment minor version
pfy version bump --part minor
# 1.2.3 → 1.3.0

# Increment major version
pfy version bump --part major
# 1.2.3 → 2.0.0

# Cut a release candidate
pfy version bump --part minor --pre rc
# 1.2.3 → 1.3.0-rc.1

# Reapplying the same label advances the counter
pfy version bump --part minor --pre rc
# 1.3.0-rc.1 → 1.3.0-rc.2

# Drop --pre to release the candidate
pfy version bump --part patch
# 1.3.0-rc.1 → 1.3.0

Behavior:

  • patch increments the third number and keeps major and minor
  • minor increments the second number and resets patch to 0
  • major increments the first number and resets minor and patch to 0
  • Bumping without --pre strips any pre-release or build metadata. A bump that would merely release an existing pre-release does exactly that rather than skipping ahead: 1.3.0-rc.1 with --part patch becomes 1.3.0, not 1.3.1, since semver orders 1.3.0-rc.1 < 1.3.0.
  • Reapplying the same --pre label advances its counter (rc.1 → rc.2) instead of restarting it or jumping to the next release.

Examples ​

Development Workflow ​

bash
# Check current version
pfy version show
# 1.0.0

# Make bug fix
# ... code changes ...
pfy version bump --part patch
# 1.0.0 → 1.0.1

# Add new feature
# ... code changes ...
pfy version bump --part minor
# 1.0.1 → 1.1.0

# Breaking change
# ... code changes ...
pfy version bump --part major
# 1.1.0 → 2.0.0

Release Script ​

bash
#!/bin/bash
# release.sh

# Bump version
pfy version bump --part minor

# Get new version
VERSION=$(pfy version show)

# Tag and push
git tag "v$VERSION"
git push --tags

echo "Released version $VERSION"

CI/CD Integration ​

Used automatically in CI/CD pipelines (see Auto-Versioning):

yaml
# GitHub Actions
- name: Bump version
  run: |
    pfy version bump --part patch
    echo "NEW_VERSION=$(pfy version show)" >> $GITHUB_ENV

Global Flags ​

All global pfy flags are available:

  • --verbose, -v: Show detailed output
  • --quiet, -q: Suppress non-essential output

Verbose Output ​

bash
pfy --verbose version bump --part minor

Output:

Incrementing minor version from 1.2.3...
Version updated: 1.2.3 → 1.3.0
Configuration saved to project.yaml

Quiet Output ​

bash
pfy --quiet version bump --part patch

No output (check exit code for success).

Version Format ​

Versions must follow Semantic Versioning 2.0.0:

Format: major.minor.patch

Where:

  • major: Breaking changes, incompatible API changes
  • minor: New features, backwards compatible
  • patch: Bug fixes, backwards compatible

Valid Examples:

0.1.0      # Initial development
1.0.0      # First stable release
1.2.3      # Version with all components
1.3.0-rc.1 # Pre-release
10.5.128   # Large version numbers

Invalid Examples:

1.2       # Missing patch
v1.2.3    # No 'v' prefix

Error Handling ​

Invalid Version Format ​

version set accepts any string, so the error surfaces on the next bump:

bash
$ pfy version set --version 1.2
Version updated: 1.2.3 → 1.2
Configuration saved to project.yaml

$ pfy version bump
Error: failed to increment version: invalid version format: 1.2 (expected format: x.y.z[-prerelease][+build])

Solution: set a three-part version (1.2.0) and bump again.

No project.yaml ​

If project.yaml does not exist, the CLI falls back to a default configuration, so pfy version show prints the default version:

bash
$ pfy version show
0.1.0

To manage a real project version, initialize the project first:

bash
pfy init --name my-project

Invalid Bump Part ​

bash
$ pfy version bump --part release
Error: invalid version part: release (expected: major, minor, or patch)

Solution: Use major, minor, or patch

Integration ​

With CI/CD Templates ​

For Node.js projects, pfy ci update bakes the project version into the generated build job:

bash
# Set version
pfy version set --version 1.5.0

# Generate CI templates
pfy ci update

# The Node.js pipeline builds my-app:1.5.0 and, on main, bumps and pushes
# my-app:1.5.1 plus my-app:latest

Go pipelines do not use the project version; see ci.

With Application Update-Version/Copy ​

The project version feeds the application-version commands:

bash
# Push the current project version to the Manager
pfy application update-version \
  --app my-app \
  --project my-saas \
  --version $(pfy version show)

# `application copy` without --version also defaults to the
# project.yaml version (then the source application's version)
pfy application copy \
  --project my-saas \
  --from-app my-app \
  --to-tenant customer-a \
  --slug my-app-copy

In Scripts ​

bash
#!/bin/bash

# Get current version
CURRENT=$(pfy version show)
echo "Current version: $CURRENT"

# Bump version
pfy version bump --part patch
NEW=$(pfy version show)

echo "Updated to: $NEW"

# Use in Docker build
docker build -t my-app:$NEW .

Configuration ​

Version is stored in project.yaml:

yaml
project_name: my-app
version: 1.2.3 # ← Managed by version command
ci:
  type: github
  language: go

Best Practices ​

1. Commit After Version Changes ​

Always commit version changes:

bash
pfy version bump --part minor
git add project.yaml
git commit -m "Bump version to $(pfy version show)"

2. Match Git Tags ​

Keep git tags synchronized:

bash
VERSION=$(pfy version show)
git tag "v$VERSION"
git push --tags

3. Automate in CI ​

Let CI handle patch bumps automatically (the generated Node.js pipeline already does; for Go add a step like this):

yaml
# .github/workflows/ci.yml
on:
  push:
    branches: [main]

jobs:
  version-and-deploy:
    steps:
      - name: Auto-bump patch version
        run: pfy version bump --part patch

4. Manual Bumps for Features/Breaking Changes ​

Reserve minor/major bumps for developers:

bash
# Before starting new feature
pfy version bump --part minor

# Before breaking change
pfy version bump --part major

See Also ​