JFrog CLI Control Manager

Overview

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:

• End manual workarounds: 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 in Full Detail

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

The following tools benefit 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

Procedures

The following procedures walk you through installing, managing, and troubleshooting JFCM:

• Install JFCM
• Manage and upgrade JFrog CLI versions
• Troubleshoot PATH priority issues
• Upgrade or uninstall JFCM

Installation

Install JFCM on macOS with Homebrew or by building from source. If you have not installed the JFrog CLI yet, see Download and Install the JFrog CLI first. After installation, verify that the shim directory is first on your PATH.

This section covers the following procedures:

• Install JFCM on macOS with Homebrew
• Build JFCM from source
• Verify installation

Install JFCM on macOS with Homebrew

To install JFCM on macOS with Homebrew:

1. Tap the JFCM Homebrew repository:

   Bash

   brew tap jfrog/jfrog-cli-manager

2. Install JFCM:

   Bash

   brew install jfcm

   If the formula is not found, search for it or install directly from the repository URL:

   Bash

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

Build JFCM from Source on macOS and Linux

Prerequisite: A Go toolchain is required to build from source.

To build and install JFCM from source:

1. Clone the repository and change into the project directory:

   Bash

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

2. Build and install JFCM:

   Bash

   make build
   make install

   The make install command copies the jfcm executable to ~/.jfcm/shim. You can also run make bootstrap to add ~/.jfcm/shim 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 so JFCM-managed jf versions take precedence.

To verify JFCM installation:

1. Confirm PATH priority:

   Bash

   echo $PATH

   The output should start with ~/.jfcm/shim.

2. Confirm JFCM responds:

   Bash

   jfcm --help
   jfcm list

For upgrade or complete removal of JFCM, see Upgrade and Uninstall at the end of this page.

Managing and Upgrading JFrog CLI Versions

Once JFCM is installed, use the following procedures to install, activate, and pin JFrog CLI versions. For authentication after switching versions, see Authenticating via the CLI.

Installing Specific Versions

To install a specific jf binary:

1. Run jfcm install with the target version:

   Bash

   jfcm install <VERSION>

   Where:

   • <VERSION>: The JFrog CLI release version to install (for example, 2.74.0)

   For example:

   Bash

   jfcm install 2.74.0

Switching to and Activating a Version

To activate a JFrog CLI version:

1. Run jfcm use with a version, alias, or latest:

   Bash

   jfcm use <VERSION_OR_ALIAS>
   jfcm use latest

   Where:

   • <VERSION_OR_ALIAS>: An installed version number or a defined alias (for example, 2.74.0 or prod)
   • latest: Fetches or installs the newest release, then activates it

Handling Project-Specific Versions

To pin a JFrog CLI version for a repository:

1. Create a .jfrog-version file in the repository root:

   Bash

   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.

   For example:

   Bash

   echo ">=2.74.0" > .jfrog-version

2. Activate the pinned version:

   Bash

   jfcm use

   JFCM automatically uses the version or constraint in .jfrog-version.

Health Check and Troubleshooting

To verify JFCM setup and resolve common issues:

1. Run the health check with verbose output and auto-fix:

   Bash

   jfcm health-check --verbose --fix

   This verifies PATH configuration and related settings. 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 compare 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
• Statistics (minimum, maximum, average) and performance ranking
• Export results as table, JSON, CSV

Usage Analytics with 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 for 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 still resolves to a system binary instead of the JFCM-managed version, follow these steps.

To troubleshoot PATH priority issues:

1. Run the health check and apply fixes:

   Bash

   jfcm health-check --fix

2. Confirm which jf binary runs:

   Bash

   which jf

   The output should show ~/.jfcm/shim/jf.

3. Verify PATH order:

   Bash

   echo $PATH

   ~/.jfcm/shim should appear before /usr/local/bin or /opt/homebrew/bin.

4. Re-activate the version and reload your shell profile:

   Bash

   jfcm use <VERSION>
   source ~/.zshrc

   Where:

   • <VERSION>: The JFrog CLI version or alias to activate

5. If needed, add the shim directory to your shell profile manually:

   Bash

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

6. Check for shell function conflicts:

   Bash

   type jf

   The output 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 infrastructure
• 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 Quick Tips

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.

Quick Troubleshooting

Use the following table for quick fixes to common problems.

Upgrade and Uninstall

Use these procedures to upgrade or remove JFCM and all managed JFrog CLI versions.

To upgrade JFCM:

brew upgrade jfcm

To uninstall JFCM completely:

1. If installed via Homebrew, run:

   Bash

   brew uninstall jfcm

2. Remove the JFCM installation directory:

   Bash

   rm -rf ~/.jfcm

   This removes all installed jf versions, the shim at ~/.jfcm/shim/jf, the history file at ~/.jfcm/history.json, and configuration and aliases.

Frequently Asked Questions

This section provides answers to frequently asked questions about JFCM.

Related Topics

• Download and Install the JFrog CLI
• JFrog CLI
• Authenticating via the CLI
• JFrog CLI Environment Variables
• JFrog CLI Command Reference