🍋 CitrusVer

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

🎉 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

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):

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

With --commit Flag:

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

With --tag Flag:

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

With --push Flag:

1. All --tag operations (if autoTag is true)
2. Pushes to remote with tags

With --full Flag:

1. All advanced features enabled
2. Branch protection checks
3. Changelog generation
4. Plugin hooks
5. 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.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. 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