JFrog CLI Control Manager

The JFrog CLI Control Manager (JFCM) is a developer-first execution and observability layer for the JFrog CLI (jf). It makes command-line runs predictable and auditable across laptops and continuous integration (CI) environments by controlling which binary is executed, validating behavior before rollout, and surfacing usage and performance insights.

What you get

• Execution control: pin for each project, enforce priority through a jf shim, run custom binaries safely
• Safety before rollout: side-by-side CLI output comparison and performance benchmarking
• Observability: usage history, statistics, and replay for faster triage and support
• Version convenience: streamlined installs, aliases, and latest when you need it

Key Features

• One-command installs and switching
• Automatic project pinning via a .jfrog-version file
• Shell priority management with a jf shim
• Power tools for diffing, benchmarking, and usage analytics

JFCM ensures the right jf version runs every time, locally and in CI.

Why the JFrog CLI Control Manager Exists

The JFrog CLI Control Manager (JFCM) exists primarily to streamline and centralize the challenging task of managing multiple versions of the JFrog CLI (the jf binary) across different projects and environments. Its core motivation is to solve the complexity of version control that often led to difficult, manual workarounds.

Key Reasons for JFCM's Existence

1. Eliminating manual control management challenges

JFCM was created specifically to end the need for "symlink hacking or hardcoded paths" when trying to switch between different JFrog CLI versions. It removes brittle configuration and provides a smooth jf shim for command redirection to the correct, active version, ensuring the correct binary is executed every time. This also avoids "works-on-my-machine" drift between developers and CI environments.

2. Facilitating seamless version switching and installation

Inspired by managers like nvm, sdkman, and volta, JFCM streamlines obtaining and activating versions:

• Install any released version of the jf binary
• Automatically fetch and use the latest version with jfcm use latest
• Define named aliases (for example, prod, dev) for specific versions
• Link locally built jf binaries for testing

3. Enabling project-specific control

Different projects can rely on specific JFrog CLI versions. JFCM automatically switches the active version based on a .jfrog-version file in the current directory, ensuring the correct version is always used.

4. Supporting advanced development and DevOps workflows

Beyond basic switching, JFCM enables safer upgrades and visibility into usage:

• Version testing and comparison: compare JFrog CLI command output between 2 versions with diff visualization
• Performance benchmarking: run detailed benchmarks across multiple jf versions
• Usage analytics: history and statistics on which versions and commands are used most

5. Prioritizing and ensuring correct execution

JFCM manages shell integration and PATH priority so the managed jf has the highest precedence over system-installed versions (Homebrew or defaults), guaranteeing the active version is the one executed.

Why JFCM exists

Teams ship faster when the right binary runs, behaves as expected, and is measurable:

• Kill manual hacks: no symlink juggling or PATH guesswork. The jf shim always points to the active build.
• Seamless switching: jfcm install <version> then jfcm use <version | alias | latest>
• Predictable environments: auto-activate the version in .jfrog-version per repository
• Safer upgrades: compare outputs and benchmark before adopting a new version in CI
• Operational insight: history and statistics expose adoption, hotspots, and regressions

Execution, Safety, and Observability for the JFrog CLI

jfcm is more than a version switcher. It is a versioned, observable, and safe execution layer for the JFrog CLI. It brings the rigor of tools such as nvm, pyenv, and volta to development and operations workflows. It is tailored for artifact management and continuous integration and delivery (CI/CD).

Problem Landscape

• Inconsistent jf versions across development, staging, and CI
• Upgrade hesitancy due to fear of breaking changes
• Performance regressions that go unnoticed
• Hard-to-reproduce bugs in support and quality assurance
• Custom builds overwriting global tools
• Manual PATH and configuration errors after switching

JFCM Solution

• Version isolation for each project, alias, or workflow
• Compare: command-level output diffs across versions
• Benchmark: performance checks with statistics and export
• History: observability of versions and commands over time
• Link: test custom or local binaries without touching global jf
• Hooks: pre-execution and post-execution hooks for standardization

Outcome: predictable pipelines, safer upgrades, faster triage, confident feature adoption.

Value by Role

The following table summarizes how JFCM helps different roles.

JFCM Features (Full Details)

1. Version Management

JFCM provides seamless handling and organization of JFrog CLI versions, so you can install, switch, and maintain different binaries:

• Installation: Installs any released jf binary version from JFrog's public release server (for example, jfcm install <version>)
• Activation and switching (use): Activates a specified version or alias (for example, jfcm use <version or alias>). Use jfcm use latest to fetch and activate the most recent version automatically
• Project-Specific Defaults: Automatic switching based on a .jfrog-version file in the current directory ensures consistency
• Aliasing: Define custom aliases for specific versions (for example, prod, dev)
• Local Linking: Link a locally built jf binary for use via JFCM
• Removal and Listing: jfcm remove <version>, jfcm clear, and jfcm list

2. Shell Integration and Priority Management

JFCM automatically configures your shell to ensure that managed jf binaries have the highest priority over system-installed versions. This is achieved by:

• Creating a shim (at ~/.jfcm/shim/jf) that redirects commands to the currently active version
• Updating the PATH environment variable to prioritize the JFCM shim directory
• Adding a shell function for enhanced priority handling (similar to the nvm approach)

3. Advanced Comparison and Benchmarking Features

Power tools highly beneficial for development and DevOps teams:

• Parallel Command Comparison (jfcm compare cli): Compare JFrog CLI command output between 2 versions simultaneously, with git-like diff visualization (side-by-side or unified), colored output, and comparison of execution timing, exit codes, and error output
• Changelog Comparison (jfcm compare changelog): Compare release notes and changelogs between 2 versions
• Performance Benchmarking (jfcm benchmark): Run detailed performance benchmarks across multiple JFrog CLI versions, configurable iterations, statistics (minimum, maximum, average), and exports (table, JSON, CSV)

4. Usage Analytics and Health Checks

• Usage History (jfcm history): Tracks version usage patterns, including command timing, usage trends, most-used versions and commands. History replay allows re-executing previous commands using !\{id\}
• Health Check (jfcm health-check): Comprehensive check covering environment, PATH, network connectivity, performance checks, and security checks. Includes --fix to address common issues

Installation

macOS (Homebrew)

brew tap jfrog/jfrog-cli-manager

brew install jfcm

If the formula isn't immediately found:

brew search jfcm
brew install https://raw.githubusercontent.com/jfrog/homebrew-jfrog-cli-manager/main/Formula/jfcm.rb

Build from Source (macOS/Linux)

git clone https://github.com/jfrog/jfrog-cli-manager.git
cd jfrog-cli-manager

make build
make install

Requirements: Go toolchain. The make install command copies the jfcm executable to ~/.jfcm/shim. You can also run make bootstrap to ensure ~/.jfcm/shim is added to your shell's PATH.

Post-Installation and Verification

After installation, the shim directory ($HOME/.jfcm/shim) must be prioritized at the beginning of your $PATH to ensure JFCM-managed jf versions take precedence.

Verify PATH:

echo $PATH

It should start with ~/.jfcm/shim.

Verify Installation:

jfcm --help
jfcm list

Upgrade and Uninstall

Upgrade JFCM

brew upgrade jfcm  # if installed via Homebrew

Uninstall JFCM

brew uninstall jfcm  # if installed via Homebrew

Complete removal:

rm -rf ~/.jfcm

This removes all installed jf versions, shim, config, and aliases.

Managing and Upgrading the JFrog CLI (jf) Versions

Once JFCM is installed, the following commands are used to manage the versions of the jf binary:

Installing Specific Versions

To install a specific jf binary from JFrog's public release server:

jfcm install <version>

# Example:
jfcm install 2.74.0

Switching to and Activating a Version (Effectively Upgrading)

The jfcm use command is crucial for activating a version and is the primary way to "upgrade" your active jf:

# Specific version or alias
jfcm use <version or alias>   # for example, jfcm use 2.74.0

# Latest:
jfcm use latest               # fetches or installs if necessary, then activates

Handling Project-Specific Versions

To ensure project-based version control:

# In your repository
echo "2.74.0" > .jfrog-version

You can also store a constraint (for example >=2.74.0, >2.74.0, <=2.80.0, <2.80.0, or =2.74.0). JFCM selects the highest installed version that satisfies the constraint.

echo ">=2.74.0" > .jfrog-version

# Then run:
jfcm use

JFCM will automatically use the version specified in that file.

Health Check and Troubleshooting

To troubleshoot installation or version switching issues:

jfcm health-check --verbose --fix

This verifies the setup (including PATH configuration) and attempts to resolve common issues. Add --verbose when you need more detail for troubleshooting.

Core Commands

The following table lists commands that handle installation, removal, switching, aliasing, and version policy for JFrog CLI versions.

Advanced Features Commands

JFCM uses multiple versions simultaneously for comparison, benchmarking, and analytics.

Compare Behavior Between 2 Versions

Run the same jf command twice and diff the outputs.

jfcm compare cli <v1> <v2> -- <jf command>

# Examples:
jfcm compare cli 2.74.0 2.73.0 -- --version
jfcm compare cli prod dev -- rt ping

Features:

• Git-like diff visualization (side-by-side or unified)
• Colored output, and compares execution timing, exit codes, and stderr
• When to use it: version testing before upgrade, configuration diffs (for example, config show), and feature verification

Changelog Comparison

jfcm compare changelog <v1> <v2>

# Example:
jfcm compare changelog v2.75.1 v2.76.0

Compares release notes and changelogs between 2 JFrog CLI versions.

Compare the Same Command Across Servers

Run the same JFrog CLI command against 2 different server configurations and diff the results. Use this when you need to compare behavior across environments (for example, production and staging).

jfcm compare rt <server1> <server2> -- <jf-command> [arguments...]

Performance Benchmarking

Run performance tests across multiple versions:

jfcm benchmark <versions> -- <command> [options]

# Examples:
jfcm benchmark 2.74.0,2.73.0,2.72.0 -- rt search "*.jar" --format csv
jfcm benchmark prod,dev -- rt upload test.txt my-repository/ --iterations 5 --detailed

Features:

• Parallel execution and configurable iterations
• Stats (minimum, maximum, average) and performance ranking
• Export results as table, JSON, CSV

Usage Analytics (jfcm history)

Track and analyze historical usage of jf versions.

jfcm history                 # recent usage
jfcm history --stats         # aggregate statistics
jfcm history --version 2.74.0
jfcm history '!5'            # replay the command with id 5

Features:

• Tracks usage patterns (command, version, timestamps), limited to 1000 entries

• Detailed statistics, filter by version, and history replay via !\{id\}. You can narrow output with flags such as --command <pattern>, --failures-only, --show-output, --limit <n>, --format json, or --clear.

• Stored at ~/.jfcm/history.json

Shell Integration and Priority Management

The core goal of JFCM's shell integration is to ensure that when you run jf, the JFCM-managed version executes, not a system-installed binary (like Homebrew or OS defaults).

When you run jfcm use <version>, it:

1. Creates a shim at ~/.jfcm/shim/jf that redirects to the active version
2. Updates the PATH to prioritize the JFCM shim directory
3. Adds a shell function for enhanced priority handling (similar to the nvm approach)

Profile Snippet (Auto-Priority)

# jfcm PATH configuration - ensures jfcm-managed jf takes highest priority
export PATH="$HOME/.jfcm/shim:$PATH"

# jfcm shell function for enhanced priority (similar to nvm approach)
jf() {
    # Check if jfcm shim exists and is executable
    if [ -x "$HOME/.jfcm/shim/jf" ]; then
        # Execute jfcm-managed jf with highest priority
        "$HOME/.jfcm/shim/jf" "$@"
    else
        # Fallback to system jf if jfcm shim not available
        command jf "$@"
    fi
}

Debug Mode

export jfcm_DEBUG=1
# Shows which version is being executed
jf --version

Set jfcm_NO_HISTORY=1 to disable history recording. This helps in CI pipelines or when you run sensitive commands you do not want stored.

Troubleshooting PATH Issues

If jf is still using the system version instead of JFCM-managed version:

1. Run the health check command:

jfcm health-check --fix

This will verify all aspects of JFCM setup and attempt to fix issues.

2. Check which jf is being used:

which jf
# Should show: /Users/username/.jfcm/shim/jf

3. Verify PATH order:

echo $PATH
# ~/.jfcm/shim should appear before /usr/local/bin or /opt/homebrew/bin

4. Re-run use command:

jfcm use <version>
source ~/.zshrc  # or ~/.bashrc

5. Manual PATH fix:

Add this to your shell profile:

export PATH="$HOME/.jfcm/shim:$PATH"

6. Check for shell function conflicts:

type jf
# Should show the jfcm shell function, not a system binary

Advanced Examples

Comparing Configuration Changes

# Compare configuration differences between versions
jfcm compare cli 2.74.0 2.73.0 -- config show --format json

# Check if a specific feature works across versions
jfcm compare cli old new -- rt search "libs-release-local/*.jar" --limit 5

# Compare release notes and changelogs
jfcm compare changelog v2.75.1 v2.76.0

Performance Analysis

# Benchmark search performance across versions
jfcm benchmark 2.74.0,2.73.0,2.72.0 -- rt search "*" --limit 100 --iterations 3

# Test upload performance
jfcm benchmark prod,dev -- rt upload test.txt my-repository/ --iterations 5 --detailed

Usage Analytics

# See your most used JFrog CLI commands
jfcm history --stats

# Track version adoption over time
jfcm history --version 2.74.0

Automation and CI

# Export benchmark results for CI analysis
jfcm benchmark $OLD_VERSION,$NEW_VERSION -- rt ping --format json > performance.json

# Compare outputs in automated testing
jfcm compare cli baseline canary --unified --no-color -- rt search "*.jar"

# Always use the latest version in CI pipelines
jfcm use latest
jf --version

Advanced Configuration in JFCM

JFCM manages configuration settings related to usage tracking, performance, and installation health. You can fine-tune the tool's behavior and analyze its operations.

History Management

• History is automatically tracked in ~/.jfcm/history.json
• The history log is limited to ~1000 entries to prevent unlimited growth
• Tracked data includes command execution timing and associated metadata
• Usage history provides insights into most used versions and commands
• Options: filter by version (--version 2.74.0), show detailed statistics (--stats), or replay using !\{id\} (for example, jfcm history '!5')

Health Check Features

Feature Category → Detailed Checks:

• Installation Status: verifies JFCM directories, shim setup, PATH configuration
• Priority Verification: ensures the managed jf has priority over system-installed versions
• System Environment: checks OS compatibility, architecture, shell detection
• Binary Execution: tests running both jfcm and jf
• Network Connectivity: confirms reachability to GitHub API and JFrog releases infra
• Performance and security: includes performance checks and basic security checks (file permissions, suspicious file detection)
• Advanced output and fixes: --fix auto-resolves common issues, and supports JSON output for CI/CD

Performance Optimization

• Commands are designed to run in parallel when possible to speed up comparisons and benchmarks
• Supports configurable timeouts for long-running operations
• Efficient diff algorithms are used when comparing large command results

Debugging for CI Pipelines

• Debug Mode: jfcm_DEBUG=1 reveals detailed shim execution information (which version is executed)
• Automation: you can export benchmark results as JSON or CSV. Comparison output supports --unified and --no-color for reliable, deterministic diffs in CI.

Note The JFrog CLI Control Manager (JFCM) addresses the challenges of managing multiple JFrog CLI (jf) versions across projects and environments. It streamlines management, automatic installation, version switching, and analytics, drawing inspiration from nvm, sdkman, and volta.

CI/CD Tips (Quick)

Always Latest

jfcm use latest
jf --version

Baseline vs Canary

jfcm compare cli baseline canary --unified --no-color -- rt search "*.jar"

Export Performance Data

Use --format json or --format csv for dashboards and regression alarms.

Troubleshooting (Quick)

Use the following table for quick fixes to common problems.

Upgrade and Uninstall

Upgrade JFCM

brew upgrade jfcm

Uninstall JFCM (Homebrew)

brew uninstall jfcm

Manual Removal (Primary Method)

rm -rf ~/.jfcm

This removes:

• All installed versions of the JFrog CLI (jf)
• The JFCM shim (located at ~/.jfcm/shim/jf)
• The history tracking file (~/.jfcm/history.json)
• Config and aliases

FAQ

What is JFCM?

A version manager and, more importantly, an execution and observability layer for the JFrog CLI (jf) that installs, activates, and prioritizes specific versions.

What can JFCM do?

Auto-installation, version switching, performance benchmarking, parallel version comparison, usage analytics, safe custom binary linking, and health checks.

How do I install a specific version?

Use jfcm install <version> (for example: jfcm install 2.74.0).

How do I switch the active version?

Use jfcm use <version or alias> or jfcm use latest. With a .jfrog-version file present, jfcm use (no args) auto-activates it.

How does JFCM make sure the managed version runs?

It creates a lightweight shim at ~/.jfcm/shim/jf and updates your shell's PATH to ensure the managed version has the highest priority.

How can I see what versions are installed?

Use jfcm list to show all installed versions and the active one.

How do I remove an old version?

Use jfcm remove <version> (for example, jfcm remove 2.72.1). To remove all installed versions, use jfcm clear.

Can I set a version for a specific project?

Yes. Add a .jfrog-version file to your repository containing the desired version number (for example, 2.74.0), then run jfcm use.

How do I compare versions safely before upgrading?

Use jfcm compare cli <v1> <v2> -- <jf command> for behavior diffs, and jfcm compare changelog to review release notes.

What is performance benchmarking used for?

jfcm benchmark runs performance tests across multiple JFrog CLI versions to detect regressions and analyze slow operations. Use --format json or --format csv for CI.

How do I check if my JFCM setup is working?

Run jfcm health-check. You can use the --fix option to automatically resolve common configuration issues.

How do I use a local or custom build?

jfcm link --from <path> --name local and then jfcm use local.

How do I uninstall JFCM completely?

Manually remove the installation directory using rm -rf ~/.jfcm. If installed via Homebrew, you can also use brew uninstall jfcm.