Use JFrog CLI Package Alias

Package Alias Overview

Package Alias is a JFrog CLI feature that lets you run native package manager commands (npm install, mvn clean install, nuget restore, gradle build, pip install, go build) without the jf prefix. JFrog CLI intercepts these commands transparently and runs the equivalent jf <tool> command behind the scenes.

Package Alias is also known internally by the codename Ghost Frog (reflected in the JFROG_CLI_GHOST_FROG environment variable and [GHOST_FROG] debug logs). The codename captures the design intent: JFrog CLI is there when you need it, but invisible in your workflow.

📘

Note

Interception is opt-in. Aliases must be installed and on PATH, and you must set JFROG_CLI_GHOST_FROG=true in the environment where build commands run. For variable details, see JFrog CLI Environment Variables. Without that variable, alias binaries are present but commands run through the native tool unchanged.

Install and Set Up Package Alias

This guide covers installing Package Alias on a local machine, in GitHub Actions, and in other CI systems, then verifying that interception works.

• Local Development Setup
• GitHub Actions Setup
• Manual CI Setup (Non-GitHub)
• Verification Checklist

Prerequisites

Before installing package aliases, ensure:

1. JFrog CLI is installed: jf --version returns a version number (2.93.0 or above for package-alias support). For installation steps, see Download and Install the JFrog CLI
2. JFrog Platform is configured: jf config add has been run to set up a server connection
3. Build tool configurations are set: Run the appropriate configuration command for each tool you plan to alias:
   • jf npm-config (for npm)
   • jf mvn-config (for Maven)
   • jf gradle-config (for Gradle)
   • jf nuget-config (for NuGet)
   • jf pip-config (for pip)
   • jf go-config (for Go)
   • jf pipenv-config and other tool-specific configuration commands as needed

Supported Tools

Package Alias supports 14 package managers covered in JFrog CLI build tool commands: mvn, gradle, npm, yarn, pnpm, go, pip, pipenv, poetry, dotnet, nuget, docker, gem, bundle.

Local Development Setup

macOS and Linux

To install and enable package aliases on macOS or Linux:

1. Install aliases:

   Shell

   jf package-alias install

2. Add the alias bin directory to PATH in ~/.bashrc, ~/.zshrc, or ~/.profile:

   Shell

   export PATH="$HOME/.jfrog/package-alias/bin:$PATH"

3. Enable interception in the same shell configuration file or export it for the current session:

   Shell

   export JFROG_CLI_GHOST_FROG=true

4. Reload the shell and clear the command hash table:

   Shell

   source ~/.bashrc   # or ~/.zshrc, ~/.profile
   hash -r

5. Verify installation:

   Shell

   jf package-alias status

6. Confirm the alias is first on PATH, then run a test command:

   Shell

   which npm          # Should show ~/.jfrog/package-alias/bin/npm
   npm install        # Intercepted by Package Alias -> jf npm install

If JFROG_CLI_HOME_DIR is set, aliases are created under $JFROG_CLI_HOME_DIR/package-alias/bin instead of $HOME/.jfrog/package-alias/bin.

Windows

To install and enable package aliases on Windows:

1. Install aliases:

   PowerShell

   jf package-alias install

2. Add the alias bin directory to PATH (run in PowerShell as Administrator, or add via System Properties):

   PowerShell

   $aliasDir = "$env:USERPROFILE\.jfrog\package-alias\bin"
   [Environment]::SetEnvironmentVariable("PATH", "$aliasDir;$env:PATH", "User")

3. Enable interception:

   PowerShell

   [Environment]::SetEnvironmentVariable("JFROG_CLI_GHOST_FROG", "true", "User")

4. Restart the terminal.

5. Verify installation:

   PowerShell

   jf package-alias status

6. Confirm the alias is first on PATH, then run a test command:

   PowerShell

   where.exe npm     # Should show the alias directory path first
   npm install       # Intercepted by Package Alias -> jf npm install

Install Only Specific Tools

To install aliases for selected package managers only:

1. Run jf package-alias install with a comma-separated --packages list:

   Shell

   jf package-alias install --packages=npm,mvn,go

GitHub Actions Setup

Use the setup-jfrog-cli action with package-alias inputs (available in v4 after merge of setup-jfrog-cli PR #341). The action runs jf package-alias install and adds the alias bin directory to PATH for subsequent steps.

To set up Package Alias in GitHub Actions:

1. Set JFROG_CLI_GHOST_FROG: "true" at the job or workflow level. The action doesn't set this for you.

2. Use JFrog CLI 2.93.0 or above (or latest). If the requested version is older, or jf package-alias install fails, the action logs a warning and continues. Subsequent steps won't use package aliases.

3. The action respects JFROG_CLI_HOME_DIR for the alias bin path when set

env:
  JFROG_CLI_GHOST_FROG: "true"

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: jfrog/setup-jfrog-cli@v4
        with:
          enable-package-alias: true
          package-alias-tools: npm,mvn,go,pip
          # version: 2.93.0   # optional; omit or use latest unless pinning an older release
        env:
          JF_URL: ${{ vars.JF_URL }}
          JF_ACCESS_TOKEN: ${{ secrets.JF_ACCESS_TOKEN }}

      - run: jf package-alias status

      - run: npm install          # Intercepted by Package Alias
      - run: mvn clean install    # Intercepted by Package Alias

PATH Priority and Re-Pinning Aliases

When enable-package-alias: true is set, the action runs jf package-alias install and appends the shim directory to GITHUB_PATH (default: $HOME/.jfrog/package-alias/bin, or $JFROG_CLI_HOME_DIR/package-alias/bin when JFROG_CLI_HOME_DIR is set).

In GitHub Actions, each entry written to GITHUB_PATH is prepended to PATH at the start of the next step. The most recently added entry gets the highest priority. If a later step installs a package manager (for example actions/setup-java, a Maven install action, or actions/setup-node), that step also writes to GITHUB_PATH and pushes the Ghost Frog shim directory down in priority. The runner then resolves the native tool (for example mvn) instead of the shim.

To re-pin aliases after installing tools:

      - name: Install Maven 3.9.11
        uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: "17"

      - name: Re-pin Ghost Frog aliases
        run: echo "${HOME}/.jfrog/package-alias/bin" >> $GITHUB_PATH

If you set JFROG_CLI_HOME_DIR, re-pin using that path instead:

      - name: Re-pin Ghost Frog aliases
        run: echo "${JFROG_CLI_HOME_DIR}/package-alias/bin" >> $GITHUB_PATH

📘

Tip

Add one re-pin step immediately after each tool-install step that runs after setup-jfrog-cli. If build commands run between multiple installs, re-pin after the last install before those commands execute.

Manual CI Setup (Non-GitHub)

For Jenkins, GitLab CI, Azure Pipelines, or other environments without the setup-jfrog-cli action:

To set up Package Alias in non-GitHub CI:

1. Install JFrog CLI 2.93.0 or above if it isn't already installed:

   Shell

   curl -fL https://install-cli.jfrog.io | sh

2. Configure the JFrog Platform connection:

   Shell

   jf config add my-server --url="$JFROG_URL" --access-token="$JFROG_ACCESS_TOKEN" --interactive=false

3. Configure the build tools you plan to alias:

   Shell

   jf npm-config --repo-resolve=npm-virtual --server-id-resolve=my-server
   jf mvn-config --repo-resolve-releases=maven-virtual --repo-resolve-snapshots=maven-virtual --server-id-resolve=my-server

4. Install package aliases:

   Shell

   jf package-alias install --packages=npm,mvn

5. Add the alias bin directory to PATH:

   Shell

   export PATH="$HOME/.jfrog/package-alias/bin:$PATH"

   For GitHub Actions without setup-jfrog-cli package-alias inputs, persist the path across steps:

   Shell

   echo "$HOME/.jfrog/package-alias/bin" >> $GITHUB_PATH

6. Enable interception:

   Shell

   export JFROG_CLI_GHOST_FROG=true

7. Verify installation:

   Shell

   jf package-alias status

8. Run build commands (intercepted when JFROG_CLI_GHOST_FROG=true):

   Shell

   npm install
   mvn clean install

Verification Checklist

To verify Package Alias installation and interception:

After installation, run through the following checklist.

📘

Note

jf package-alias status can report "Package aliasing is active" when the configuration is enabled and PATH is set, but interception still requires JFROG_CLI_GHOST_FROG=true in the environment where you run build commands.

Before and After Workflow Comparison

npm

Before Package Alias

jf config add my-server --url=... --access-token=...
jf npm-config --repo-resolve=npm-virtual --server-id-resolve=my-server
jf npm install --build-name=my-app --build-number=1
jf rt build-publish my-app 1

After Package Alias

jf config add my-server --url=... --access-token=...
jf npm-config --repo-resolve=npm-virtual --server-id-resolve=my-server
jf package-alias install --packages=npm     # One-time setup
export PATH="$HOME/.jfrog/package-alias/bin:$PATH"
export JFROG_CLI_GHOST_FROG=true

npm install                                  # Intercepted -> jf npm install
jf rt build-publish my-app 1

Maven

Before Package Alias

jf config add my-server --url=... --access-token=...
jf mvn-config --repo-resolve-releases=maven-virtual --repo-resolve-snapshots=maven-virtual --server-id-resolve=my-server
jf mvn clean install --build-name=my-java-app --build-number=1
jf rt build-publish my-java-app 1

After Package Alias

jf config add my-server --url=... --access-token=...
jf mvn-config --repo-resolve-releases=maven-virtual --repo-resolve-snapshots=maven-virtual --server-id-resolve=my-server
jf package-alias install --packages=mvn      # One-time setup
export PATH="$HOME/.jfrog/package-alias/bin:$PATH"
export JFROG_CLI_GHOST_FROG=true

mvn clean install                             # Intercepted -> jf mvn clean install
jf rt build-publish my-java-app 1

Complete Command Reference

All package-alias commands are subcommands of jf package-alias. The parent command is registered as hidden in JFrog CLI's command list. Only three subcommands are available: install, uninstall, and status.

To enable or disable interception globally, or to change per-tool behavior, edit config.yaml. For field definitions, see Configuration file reference.

jf package-alias install

Install package manager aliases by creating symlinks (Unix) or binary copies (Windows) in the alias bin directory.

Synopsis

jf package-alias install [--packages=<TOOL_LIST>]

Flags

Behavior

1. Creates $JFROG_CLI_HOME_DIR/package-alias/ and $JFROG_CLI_HOME_DIR/package-alias/bin/ (defaults to $HOME/.jfrog/... when JFROG_CLI_HOME_DIR is unset).
2. Resolves the real path of the current jf binary (follows symlinks).
3. For each selected tool, creates a symlink (Unix) or copy (Windows) in the bin directory.
4. Removes aliases for tools not in the --packages list (if specified).
5. Writes config.yaml with enabled: true, tool modes, enabled tools list, and the SHA256 hash of the jf binary.
6. Prints PATH setup instructions.

Examples

# Install aliases for all 14 supported tools
jf package-alias install

# Install aliases for specific tools only
jf package-alias install --packages=npm,mvn,go

# Install aliases for a single tool
jf package-alias install --packages=npm

Output

[Info] Creating package alias directories...
[Info] Created 14 aliases in /Users/you/.jfrog/package-alias/bin
[Info] Configured packages: mvn, gradle, npm, yarn, pnpm, go, pip, pipenv, poetry, dotnet, nuget, docker, gem, bundle
[Info]
[Info] To enable package aliasing, add this to your shell configuration:
[Info]   export PATH="/Users/you/.jfrog/package-alias/bin:$PATH"
[Info]
[Info] Then run: hash -r
[Info]
[Info] Package aliasing is now installed. Run 'jf package-alias status' to verify.

Error Messages

jf package-alias uninstall

Remove all package manager aliases and delete the alias directory.

Synopsis

jf package-alias uninstall

Flags

None

Behavior

1. Checks if the alias bin directory exists. If not, prints "Package aliases are not installed." and exits.
2. Removes all alias symlinks/copies from the bin directory.
3. Deletes the entire $JFROG_CLI_HOME_DIR/package-alias/ directory (including config.yaml).
4. Prints instructions for removing the PATH entry from the user's shell configuration.

Example

jf package-alias uninstall

Output

[Info] Removed 14 aliases
[Info]
[Info] To complete uninstallation, remove this from your shell configuration:
[Info]   Remove 'export PATH="/Users/you/.jfrog/package-alias/bin:$PATH"' from your shell rc file
[Info]
[Info] Then run: hash -r

jf package-alias status

Display the current state of package aliasing: installed, enabled, PATH configured, and per-tool configuration.

Synopsis

jf package-alias status

Flags

None

Behavior

Checks and reports:

1. Installation status: Whether the alias bin directory exists.
2. Enabled state: Whether enabled: true is set in config.
3. PATH configuration: Whether the alias bin directory is in the current PATH.
4. Per-tool status: For each configured tool, shows:
   • Mode (jf or pass)
   • Whether the alias file exists in the bin directory (alias=[OK] or [MISSING])
   • Whether the real (native) tool binary exists in PATH, excluding the alias directory (real=[OK] or [MISSING])
5. Go subcommand policies: If any go.* subcommand modes are configured in config.yaml, they are listed.
6. Windows staleness warning: If the SHA256 of the current jf binary differs from the stored hash, warns that alias copies may be stale.

Output (when installed and active)

[Info] Package Alias Status
[Info] ===================
[Info] Status: INSTALLED
[Info] Location: /Users/you/.jfrog/package-alias/bin
[Info] State: ENABLED
[Info] PATH: Configured [OK]
[Info]
[Info] Tool Configuration:
[Info]   mvn        mode=jf    alias=[OK] real=[OK]
[Info]   gradle     mode=jf    alias=[OK] real=[OK]
[Info]   npm        mode=jf    alias=[OK] real=[OK]
[Info]   yarn       mode=jf    alias=[OK] real=[MISSING]
[Info]   pnpm       mode=jf    alias=[OK] real=[OK]
[Info]   go         mode=jf    alias=[OK] real=[OK]
[Info]   pip        mode=jf    alias=[OK] real=[OK]
[Info]   pipenv     mode=jf    alias=[OK] real=[MISSING]
[Info]   poetry     mode=jf    alias=[OK] real=[MISSING]
[Info]   dotnet     mode=jf    alias=[OK] real=[OK]
[Info]   nuget      mode=jf    alias=[OK] real=[OK]
[Info]   docker     mode=jf    alias=[OK] real=[OK]
[Info]   gem        mode=jf    alias=[OK] real=[OK]
[Info]   bundle     mode=jf    alias=[OK] real=[OK]
[Info]
[Info] Package aliasing is active. You can now run:
[Info]   mvn install
[Info]   npm install
[Info]   go build
[Info] ...and they will be intercepted by JFrog CLI

Output (when not installed)

[Info] Package Alias Status
[Info] ===================
[Info] Status: NOT INSTALLED
[Info]
[Info] Run 'jf package-alias install' to set up package aliasing

📘

Note

This command doesn't check JFROG_CLI_GHOST_FROG. Even when status reports aliasing as active, commands are only intercepted when JFROG_CLI_GHOST_FROG=true is set in the runtime environment.

Configuration File Reference (config.yaml)

Location: $JFROG_CLI_HOME_DIR/package-alias/config.yaml (default: $HOME/.jfrog/package-alias/config.yaml)

There are no jf package-alias enable, disable, exclude, or include CLI commands. Use config.yaml to control behavior:

enabled: true
tool_modes:
  npm: jf
  pnpm: pass
enabled_tools:
  - npm
  - mvn
  - go
subcommand_modes:
  go.mod.tidy: pass
jf_binary_sha256: "<sha256-of-jf-binary>"

Disable interception globally:

• Set JFROG_CLI_GHOST_FROG=false or unset the variable (fastest kill switch), or
• Set enabled: false in config.yaml

Run a specific tool natively:

• Set tool_modes.<tool>: pass in config.yaml (for example, pnpm: pass)

Default pass-through tools: pnpm, gem, and bundle use pass at runtime when they have no entry in tool_modes. After jf package-alias install, these tools typically show mode=jf in status because install records jf in config. To keep them on native execution, set pass explicitly in tool_modes.

Environment Variables

Troubleshooting

Aliases Not Intercepting

Symptom: Running npm install uses the real npm instead of routing through JFrog CLI.

Possible causes and fixes:

Infinite Recursion or Hang

Symptom: Running a tool hangs or crashes with a stack overflow.

Cause: The alias bin directory was not removed from PATH before looking up the real tool, so the alias found itself.

Fix: This should not happen under normal operation (DisableAliasesForThisProcess prevents it). If it does:

1. Kill the process
2. Check if DisableAliasesForThisProcess logged a warning (set JFROG_CLI_LOG_LEVEL=DEBUG)
3. Verify PATH configuration: the alias dir should be in PATH, and jf package-alias status should show both alias and real tool

Real Binary Not Found

Symptom: Error could not find real <tool> when running a command with config disabled or tool in pass mode.

Cause: The native tool is not installed or not in PATH (after filtering out the alias dir).

Fix: Install the native tool and ensure it is in PATH. Run jf package-alias status to check the real= column for each tool.

Config Lock Timeout

Symptom: Error timed out waiting for config lock: .../.config.lock.

Cause: A previous process crashed while holding the lock (common in CI when a job is killed).

Fix:

# Remove the stale lock file
rm ~/.jfrog/package-alias/.config.lock

# Or increase the timeout for high-concurrency environments
export JFROG_CLI_PACKAGE_ALIAS_LOCK_TIMEOUT=30s

Windows Alias Staleness

Symptom: jf package-alias status warns "Windows alias copies may be stale compared to current jf binary."

Cause: The jf.exe binary was updated after aliases were installed. Since Windows uses copies (not symlinks), the alias executables are now outdated.

Fix: Reinstall aliases to refresh the copies:

jf package-alias install

Symlink Permission Errors

Symptom: Failed to create alias for <tool>: operation not permitted during install.

Cause: The file system doesn't allow symlink creation (for example, in some container environments or on Windows without Developer Mode).

Fix:

• Unix containers: Ensure the user has write permissions to $JFROG_CLI_HOME_DIR
• Windows: Enable Developer Mode (Settings > Update and Security > For developers), or run as Administrator

Spaces in Home Path

Symptom: Aliases fail to work when $HOME or $JFROG_CLI_HOME_DIR contains spaces (for example, /Users/My User/).

Fix: Package Alias uses filepath functions that handle spaces correctly. If issues occur, ensure your shell configuration quotes the PATH entry:

export PATH="$HOME/.jfrog/package-alias/bin:$PATH"   # Quoted correctly

GitHub Actions: native tool runs instead of shim

Symptom: mvn, npm, or another aliased command uses the real binary. Ghost Frog interception does not occur in GitHub Actions.

Cause: A step after setup-jfrog-cli installed the tool (for example actions/setup-java or actions/setup-node) and wrote to GITHUB_PATH, pushing the shim directory down in PATH priority.

Fix: Re-pin the alias bin directory after each tool-install step. See PATH Priority and Re-Pinning Aliases.

GitHub Actions: Package Alias Skipped

Symptom: Action logs a warning. Subsequent steps don't intercept commands.

Cause: JFrog CLI version below 2.93.0, jf package-alias install failed, or enable-package-alias was not set to true.

Fix: Pin version: 2.93.0 or higher (or use latest), verify CLI supports jf package-alias, and confirm JFROG_CLI_GHOST_FROG=true is set at job level.

Frequently Asked Questions

This section provides answers to frequently asked questions.

Related Topics

• JFrog CLI Build Tool Commands
• JFrog CLI
• Download and Install the JFrog CLI
• Configure the JFrog CLI
• GitHub Actions
• JFrog CLI Environment Variables