@versu/cli - Command-Line Interface

Command-line interface for Versu. This CLI provides all the power of Versu's semantic versioning engine through an easy-to-use command-line tool, perfect for local development and custom CI/CD systems.

Installation

Global Installation

npm install -g @versu/cli

Local Installation

npm install --save-dev @versu/cli

Using npx (no installation)

px @versu/cli

Usage

Basic Usage

Navigate to your project root and run:

versu

This will:

1. Detect your project type (Gradle, etc.)
2. Analyze commits since the last version
3. Calculate version bumps based on Conventional Commits
4. Update version files
5. Generate changelogs
6. Create git commits and tags
7. Push changes to remote

Dry Run

Preview what would happen without making changes:

versu --dry-run

Specify Project Root

versu /path/to/project

Specify Adapter

If auto-detection fails or you want to be explicit:

versu --adapter gradle

Command Reference

versu [REPOSITORYROOT]

Calculate and apply semantic version changes.

Arguments:

• REPOSITORYROOT - Path to the repository root (default: .)

Flags:

| Flag | Description | Default | | ------ | ------------- | --------- | | --dry-run | Run without writing or pushing changes | false | | --adapter <value> | Language adapter (e.g., gradle). Auto-detected if not provided | - | | --push-tags | Push tags to origin | true | | --no-push-tags | Don't push tags to origin | - | | --prerelease-mode | Generate pre-release versions instead of final versions | false | | --prerelease-id <value> | Pre-release identifier (e.g., alpha, beta, rc) | alpha | | --bump-unchanged | In prerelease mode, bump modules even when no changes are detected | false | | --add-build-metadata | Add build metadata with short SHA to all versions | false | | --timestamp-versions | Use timestamp-based prerelease identifiers (requires prerelease-mode) | false | | --append-snapshot | Add -SNAPSHOT suffix to all versions if supported by adapter | false | | --push-changes | Commit and push version changes and changelogs to remote | true | | --no-push-changes | Don't commit and push changes | - | | --generate-changelog | Generate or update changelog files for changed modules | true | | --no-generate-changelog | Don't generate changelogs | - |

📖 Detailed Pre-release Documentation: See @versu/core PRERELEASE.md for comprehensive examples and use cases.

Examples

Release Version

Apply semantic versions based on commits:

versu

Pre-release Versions

Generate beta pre-release versions:

versu --prerelease-mode --prerelease-id beta

Timestamp Versions

Generate timestamp-based pre-release versions for CI builds:

versu --prerelease-mode --prerelease-id alpha --timestamp-versions --add-build-metadata

This generates versions like: 1.2.3-alpha.20251208.1530+abc1234

Gradle SNAPSHOT Versions

Generate Gradle SNAPSHOT versions:

versu --append-snapshot

Development Workflow

Bump all modules (even unchanged) for development:

versu --prerelease-mode --bump-unchanged

Local Testing

Test without committing or pushing:

versu --dry-run --no-push-changes --no-push-tags

Manual Git Operations

Calculate versions without automatic git operations:

versu --no-push-changes --no-push-tags

Then manually review, commit, and push.

Configuration

Versu CLI uses the same configuration system as the core library. Configuration files are automatically detected in your repository root.

Supported Configuration Files

1. package.json (in a "versu" property)
2. .versurc (JSON or YAML)
3. .versurc.json
4. .versurc.yaml / .versurc.yml
5. .versurc.js (JavaScript)
6. versu.config.js (JavaScript)

Configuration Example

.versurc.json:

{
  "versionRules": {
    "defaultBump": "patch",
    "commitTypeBumps": {
      "feat": "minor",
      "fix": "patch",
      "perf": "patch",
      "refactor": "patch",
      "docs": "ignore",
      "test": "ignore",
      "chore": "ignore"
    },
    "dependencyBumps": {
      "major": "major",
      "minor": "minor",
      "patch": "patch"
    }
  },
  "changelog": {
    "root": {
      "context": {
        "prependPlaceholder": "<!-- CHANGELOG -->"
      }
    },
    "module": {
      "context": {
        "prependPlaceholder": "<!-- CHANGELOG -->"
      }
    }
  }
}

For more configuration examples, see the core package documentation.

Advanced Changelog Configuration:

Versu supports conventional-changelog-writer options for customizing changelog generation. For advanced customization with functions (transforms, sorting, templates), use JavaScript configuration files:

// versu.config.js
module.exports = {
  versionRules: {
    // ... version rules
  },
  changelog: {
    module: {
      options: {
        groupBy: 'type',
        commitsGroupsSort: (a, b) => {
          const order = { feat: 1, fix: 2, perf: 3 };
          return (order[a.title] || 99) - (order[b.title] || 99);
        },
        transform: (commit, context) => {
          // Custom commit transformation
          return commit;
        }
      }
    }
  }
};

Gradle Project Support

Gradle support is provided by the @versu/plugin-gradle package.

The CLI supports Gradle projects with:

• Multi-module projects via settings.gradle(.kts)
• Version management through root gradle.properties file
• Dependency detection via custom Gradle init script
• Both DSLs: Groovy and Kotlin

Example Project Structure

myproject/
├── settings.gradle.kts
├── build.gradle.kts
├── gradle.properties      # All module versions defined here
├── core/
│   └── build.gradle.kts
└── api/
    └── build.gradle.kts

Example gradle.properties

# Root module version
version=1.0.0

# Submodule versions
core.version=2.1.0
api.version=1.5.0

Commit Message Format

Versu uses Conventional Commits to determine version bumps:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Examples:

• feat(api): add new endpoint → minor bump
• fix(core): resolve memory leak → patch bump
• feat!: breaking API change → major bump

Breaking Changes

Breaking changes trigger major version bumps:

1. Using ! after the type: feat!: remove deprecated API

2. Using BREAKING CHANGE: in the footer:

   feat: update API
      
   BREAKING CHANGE: The old API is removed

CI/CD Integration

GitHub Actions

- name: Install Versu CLI
  run: npm install -g @versu/cli

- name: Install Adapter
  run: |
    # install required adapters
    npm install -g @versu/plugin-gradle

- name: Version modules
  run: versu --adapter gradle

GitLab CI

version:
  script:
    - npm install -g @versu/cli
    - npm install -g @versu/plugin-gradle
    - versu --adapter gradle

Jenkins

stage('Version') {
  steps {
    sh 'npm install -g @versu/cli'
    sh 'npm install -g @versu/plugin-gradle'
    sh 'versu --adapter gradle'
  }
}

Local Development

Add to your package.json:

{
  "scripts": {
    "version": "versu --dry-run",
    "version:release": "versu"
  }
}

Then run:

npm run version        # Dry run
npm run version:release # Actual release

Troubleshooting

Command Not Found

If versu is not found after global installation:

1. Check npm global bin path: npm bin -g
2. Ensure it's in your PATH
3. Try using npx: npx @versu/cli

Permission Denied on Push

If you get permission errors when pushing:

1. Ensure you have proper git credentials configured
2. Check if you have write access to the repository
3. Use --no-push-changes --no-push-tags to skip git operations

No Version Bump Detected

If versions aren't bumping:

1. Check commit messages follow Conventional Commits format
2. Verify you have commits since the last version
3. Check configuration if certain commit types are ignored
4. Use --dry-run to see what Versu detects

Adapter Not Detected

If auto-detection fails:

1. Verify your project has the expected build files
2. Explicitly specify the adapter: --adapter gradle
3. Check if your project structure is supported

Development

Building from Source

# From monorepo root
npm install
npm run build

# Or from CLI package
cd packages/cli
npm install
npm run build

Running Locally

# After building
node dist/index.js --dry-run

Publishing

npm publish --workspace packages/cli --access public

Related Packages

• @versu/core - Core library for custom integrations
• @versu/action - GitHub Actions integration
• @versu/plugin-gradle - Gradle adapter plugin

License

MIT License - see LICENSE for details.