citrusver

🍋 CitrusVer

Next-generation version management for Node.js with beautiful CLI, comprehensive automation, and zero dependencies.

🌐 Website • 📖 Documentation • 📦 NPM • 🚀 Releases

🎉 What's New in v3.0.6

Latest Release: v3.0.6 introduces standalone compiled binaries - install CitrusVer without Node.js or npm!

New in v3.0.6

• 🚀 Standalone Binaries: Compiled with Bun for instant startup (macOS & Linux)
• 📦 One-Command Install: curl -fsSL https://citrusver.jakerains.com/install.sh | bash
• 🌐 Website Launch: New landing page at citrusver.jakerains.com
• 📖 Dynamic Documentation: Auto-updating version and domain detection
• ⚡ Zero Overhead: No npm installation or Node.js required for binary install

v3.0 Core Features

CitrusVer 3.0 introduced a fundamental redesign with a simpler, more predictable default behavior:

Breaking Changes

Default Behavior is Now Version-Only

• Running citrusver patch/minor/major now only updates package.json
• No automatic git commits, tags, or prompts by default
• Git operations are now opt-in via flags

Why This Change?

• More predictable and aligned with user expectations
• Faster for simple version bumps
• Better composability with other tools
• Still maintains all the powerful features when you need them

New Flag-Based System

Choose your workflow with intuitive flags:

• citrusver patch - Just bump the version (fast & simple)
• citrusver patch --commit - Bump + create commit
• citrusver patch --tag - Bump + commit + tag
• citrusver patch --push - Bump + commit + push
• citrusver patch --full - Complete workflow (v2 behavior)
• citrusver patch --quiet - Minimal output

🚀 12 Major New Features • 🎨 Beautiful CLI • ⚙️ Highly Configurable • 📦 Zero Dependencies

Transform your release workflow with intelligent version management, automatic changelogs, branch protection, and more!

Quick Links:

• 🌐 Visit the Website - Interactive docs, live demo, and installation guide
• 📦 NPM Package - Install with npm or npx
• 🚀 GitHub Releases - Download compiled binaries
• 📖 Full Documentation - Complete usage guide

Quick Install:

# Compiled binary (recommended - no Node.js required!)
curl -fsSL https://citrusver.jakerains.com/install.sh | bash

# NPM (also available)
npx citrusver patch

✨ Features

Core Features

• 🚀 Simple by Default - Just bump versions, nothing more (unless you want it)
• 🎨 Beautiful CLI - Colorful ASCII art and clear visual feedback
• 🎯 Flag-Based Control - Choose your workflow with intuitive flags
• 💬 Optional Git Operations - Commit, tag, and push when you need them
• 🔇 Quiet Mode - Minimal output for scripting and automation
• ⚙️ Highly Configurable - Extensive configuration via .citrusver.json
• 🚀 Zero Dependencies - Pure Node.js, no bloat

Advanced Features (with --full flag)

• 🔍 Dry Run Mode - Preview changes without committing
• 📝 Changelog Generation - Automatic CHANGELOG.md updates
• ✅ Confirmation Prompts - Review changes before applying
• 📦 Monorepo Support - Handle workspaces and multiple packages
• 🔄 Error Recovery - Automatic rollback on failures
• 🎯 Conventional Commits - Full conventional commit workflow
• 🛡️ Branch Protection - Prevent accidental releases from wrong branches
• 🔢 Version Strategies - Semver, date-based, prereleases, custom patterns
• 📊 NPM Registry Integration - Check versions, auto-publish
• 🎨 Interactive Mode - Select commit types, scopes, breaking changes
• 🔌 Plugin System - Extend functionality with custom plugins
• 📋 Config Templates - Quick setup with predefined configurations
• 🪝 Hooks System - Pre/post version hooks (with git operation flags)

📦 Installation

Compiled Binary (Recommended) ✨ NEW!

Fast, standalone installation with zero npm overhead:

curl -fsSL https://citrusver.jakerains.com/install.sh | bash

This installs a compiled binary to /usr/local/bin/citrusver. No Node.js modules, instant startup!

Available for:

• macOS (Apple Silicon & Intel)
• Linux (x86_64 & ARM64)

Binary sizes:

• macOS arm64: ~57 MB
• macOS x64: ~63 MB
• Linux x64: ~99 MB
• Linux arm64: ~92 MB

Quick Usage (no install needed)

npx citrusver patch
npx citrusver minor
npx citrusver major

Install as Dev Dependency

npm install --save-dev citrusver

Then add to your package.json scripts:

{
  "scripts": {
    "version:patch": "citrusver patch",
    "version:minor": "citrusver minor",
    "version:major": "citrusver major"
  }
}

Install Globally

npm install -g citrusver

🚀 Quick Start

Basic Usage (Version Only)

# Just bump the version - fast and simple!
npx citrusver patch    # 1.0.0 → 1.0.1
npx citrusver minor    # 1.0.0 → 1.1.0
npx citrusver major    # 1.0.0 → 2.0.0

# Prerelease versions
npx citrusver alpha    # 1.0.0 → 1.0.1-alpha.0
npx citrusver beta     # 1.0.0 → 1.0.1-beta.0

# That's it! Only package.json is updated.

With Git Operations

# Bump + create commit
npx citrusver patch --commit

# Bump + commit + tag
npx citrusver patch --tag

# Bump + commit + push to remote
npx citrusver patch --push

# Complete workflow (all features)
npx citrusver patch --full

Preview Changes First

# See what will happen without making changes
npx citrusver patch --dry-run
npx citrusver minor --commit --dry-run

Quiet Mode for Automation

# Minimal output - just the version number
npx citrusver patch --quiet
# Output: 1.0.1

📖 Usage Guide

Basic Commands

# Bump patch version (1.0.0 → 1.0.1)
citrusver patch

# Bump minor version (1.0.0 → 1.1.0)
citrusver minor

# Bump major version (1.0.0 → 2.0.0)
citrusver major

# Create alpha prerelease (1.0.0 → 1.0.1-alpha.0)
citrusver alpha

# Create beta prerelease (1.0.0 → 1.0.1-beta.0)
citrusver beta

# Custom prerelease identifier
citrusver prerelease --preid rc

How It Works

Default Behavior (No Flags):

• Updates package.json version
• Updates package-lock.json version (if exists)
• Shows success message
• That's it! No git operations, no prompts

With --commit Flag:

• Updates version files
• Prompts for optional commit message
• Stages package.json and package-lock.json
• Creates git commit
• Runs pre/post version hooks (if configured)

With --tag Flag:

• All --commit operations
• Creates annotated git tag (e.g., v1.0.1)

With --push Flag:

• All --tag operations (if autoTag is true)
• Pushes to remote with tags

With --full Flag:

• All advanced features enabled
• Branch protection checks
• Changelog generation
• Plugin hooks
• NPM publishing (if configured)

Flag Combinations

You can combine flags for custom workflows:

# Version only
citrusver patch

# Version + commit
citrusver patch --commit

# Version + commit + tag
citrusver patch --tag

# Version + commit + push (adds tag if autoTag is true)
citrusver patch --push

# Everything
citrusver patch --full

# Any combination with dry-run
citrusver patch --tag --dry-run

# Any combination in quiet mode
citrusver patch --commit --quiet

⚙️ Configuration

Create a .citrusver.json file in your project root:

{
  "messageStyle": "interactive",
  "autoTag": true,
  "autoPush": false,
  "preVersion": "npm test",
  "postVersion": "npm run build",
  "commitTemplate": "Release: {{message}}\n\nVersion: {{version}}"
}

Configuration Options

Basic Options

Option	Type	Default	Description
messageStyle	string	"interactive"	How to handle commit messages
autoTag	boolean	true	Create git tags automatically
autoPush	boolean	false	Push to remote after versioning
preVersion	string	null	Command to run before version bump
postVersion	string	null	Command to run after version bump
commitTemplate	string	null	Custom commit message template
confirmRelease	boolean	false	Show confirmation before applying
changelog	boolean	false	Generate CHANGELOG.md automatically

Advanced Options

Option	Type	Default	Description
conventionalCommits	boolean	false	Enable conventional commit workflow
versionStrategy	string	"semver"	Version strategy: semver, date, custom
plugins	array	[]	List of plugins to load
branch.protected	array	["main", "master"]	Protected branch names
branch.allowForce	boolean	false	Allow force flag on protected branches
monorepo.enabled	boolean	false	Enable monorepo support
monorepo.packages	string	"packages/*"	Workspace packages pattern
monorepo.independent	boolean	false	Independent package versioning
npm.publish	boolean	false	Auto-publish to npm
npm.access	string	"public"	NPM package access level
npm.checkRegistry	boolean	false	Check if version exists on npm

Commit Templates

Use {{message}} and {{version}} placeholders:

{
  "commitTemplate": "🚀 Release {{version}}: {{message}}"
}

🆕 New Features Usage

Dry Run Mode

Preview what will happen without making changes:

citrusver patch --dry-run

Changelog Generation

Automatically update CHANGELOG.md:

citrusver minor --changelog

Conventional Commits

Use the enhanced interactive mode:

{
  "conventionalCommits": true
}

Prerelease Versions

Create alpha, beta, or custom prerelease versions:

Quick Commands:

# Create alpha version
citrusver alpha
# 1.0.0 → 1.0.1-alpha.0

# Create beta version
citrusver beta
# 1.0.0 → 1.0.1-beta.0

# Increment existing prerelease
citrusver alpha
# 1.0.1-alpha.0 → 1.0.1-alpha.1

Advanced Usage:

# Custom prerelease identifier (rc, canary, etc.)
citrusver prerelease --preid rc
# 1.0.0 → 1.0.1-rc.0

# Combine with git operations
citrusver alpha --commit      # Alpha + commit
citrusver beta --tag          # Beta + commit + tag
citrusver alpha --push        # Alpha + commit + push

Version Progression:

1.0.0 → citrusver alpha    → 1.0.1-alpha.0
      → citrusver alpha    → 1.0.1-alpha.1
      → citrusver beta     → 1.0.1-beta.0
      → citrusver beta     → 1.0.1-beta.1
      → citrusver patch    → 1.0.1

Initialize Configuration

Quick setup with templates:

# Interactive setup
citrusver init

# Use a template
citrusver init --template conventional
citrusver init --template monorepo

Running citrusver init also adds the CLI to your project's devDependencies, ensuring teammates pick it up on install.

Monorepo Support

Configure for workspaces:

{
  "monorepo": {
    "enabled": true,
    "packages": "packages/*",
    "independent": false
  }
}

Branch Protection

Prevent releases from wrong branches:

{
  "branch": {
    "protected": ["main", "master"],
    "releaseBranches": ["main", "release/*"]
  }
}

🎯 Common Workflows

Quick Version Bump (v3.0 Default)

# Fast and simple - just bump the version
citrusver patch
# Done! Manual commit later if needed

Traditional Release Workflow

# Bump version and create release commit
citrusver minor --tag
# Add custom message when prompted
git push origin main --tags

Automated CI/CD Pipeline

# Quiet mode for scripts
VERSION=$(citrusver patch --quiet)
echo "Bumped to $VERSION"

# Or with full automation
citrusver patch --push

Feature Release with Commit

# Develop your feature...
# When ready:
citrusver minor --commit
# Type: "Add user authentication system"
# Commit created automatically
git push

Migration from v2.x to v3.0

# v2.x behavior (default created commit + tag)
# Now use --tag flag for same behavior:
citrusver patch --tag

# Or use --full for complete v2.x experience:
citrusver patch --full

CI/CD Integration

{
  "preVersion": "npm test && npm run lint",
  "postVersion": "npm run build",
  "autoPush": true
}

Then use:

citrusver patch --commit  # Hooks run with git operation flags

🎨 Visual Experience

CitrusVer provides beautiful visual feedback with a clean, modern CLI:

Default Behavior (Version Only)

╭──────────────────────────────────────────────╮
│  🍋 CitrusVer · PATCH RELEASE                │
├──────────────────────────────────────────────┤
│  Current   1.0.0                             │
│  Next      1.0.1                             │
│                                              │
│  Fresh-squeezed semver for your repo         │
╰──────────────────────────────────────────────╯

🍋 Bumping patch version...

========================================
      ✅ VERSION BUMPED! ✅
========================================

     New Version: v1.0.1

     package.json has been updated

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

     🍋 Fresh release squeezed! 🍋

With --tag Flag (Commit + Tag)

╭──────────────────────────────────────────────╮
│  🍋 CitrusVer · MINOR RELEASE                │
├──────────────────────────────────────────────┤
│  Current   1.0.0                             │
│  Next      1.1.0                             │
│                                              │
│  Fresh-squeezed semver for your repo         │
╰──────────────────────────────────────────────╯

› Commit message for v1.1.0  (Enter to skip · Esc cancels): Add user authentication

🍋 Bumping minor version...
📦 Staging changes...
💾 Creating version commit...
🏷️  Creating version tag...

========================================
      ✅ VERSION BUMPED! ✅
========================================

     New Version: v1.1.0

     Changes have been committed
     Git tag has been created

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

Next Step:
git push origin HEAD --tags

🍋 Fresh release squeezed! 🍋

Quiet Mode (--quiet)

$ citrusver patch --quiet
1.0.1

🔧 Advanced Features

Pre/Post Hooks

Run commands before and after versioning:

{
  "preVersion": "npm test",
  "postVersion": "npm run build && npm run docs"
}

Auto Push

Automatically push to remote after versioning:

{
  "autoPush": true
}

Custom Templates

Create project-specific commit formats:

{
  "commitTemplate": "[{{version}}] {{message}}"
}

🔌 Plugin System

CitrusVer supports custom plugins to extend functionality:

Creating a Plugin

// .citrusver/plugins/my-plugin.js
class MyPlugin {
  constructor() {
    this.name = 'my-plugin';
    this.version = '1.0.0';
    this.hooks = {
      'pre-version': this.preVersion.bind(this),
      'post-version': this.postVersion.bind(this)
    };
  }

  async preVersion(context) {
    console.log('Running pre-version hook');
    // Your logic here
  }

  async postVersion(context) {
    console.log('Version bumped to:', context.version);
    // Your logic here
  }
}

module.exports = MyPlugin;

Using Plugins

{
  "plugins": ["./citrusver/plugins/my-plugin"]
}

Available Hooks

• pre-version - Before version bump
• post-version - After version bump
• pre-commit - Before creating commit
• post-commit - After creating commit
• pre-tag - Before creating tag
• post-tag - After creating tag
• changelog-generate - During changelog generation
• version-calculate - Custom version calculation

🌐 Website

Visit citrusver.jakerains.com for:

• 📖 Complete documentation with interactive examples
• 🎬 Live terminal demo showing CitrusVer in action
• 🚀 Quick installation guide
• 📚 Configuration reference
• 🔄 v3.0 migration guide

The website is built with Next.js and hosted on Vercel, featuring:

• Dynamic version display (always shows the latest npm version)
• Copy-to-clipboard install commands
• Responsive design for all devices
• Comprehensive usage guide

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

• Fork the repository
• Create your feature branch (git checkout -b feature/AmazingFeature)
• Commit your changes (git commit -m 'Add some AmazingFeature')
• Push to the branch (git push origin feature/AmazingFeature)
• Open a Pull Request

📄 License

MIT © Jake Rains

🙏 Acknowledgments

• Inspired by npm version but with better UX
• ASCII art created with love and lemons 🍋
• Built for developers who appreciate beautiful CLIs

Made with 🍋 by Jake Rains
Website • NPM • GitHub