Native Mode

JFrog CLI provides two execution modes for package managers: Wrapped Mode (default) and Native Mode (opt-in). This page explains the difference, which tools support Native Mode, and how to configure each one.

This topic covers the following tasks:

• Maven Native Mode
• Gradle Native Mode
• npm Native Mode
• Poetry Native Mode
• Docker Native Mode
• NuGet Native Mode
• .NET Native Mode

Prerequisites

Before using any build-tool command, ensure the following are in place:

Build-Info Flags in Native Mode

The following flags are available on every build-tool command that supports build-info collection. They work in both Wrapped Mode and Native Mode.

--module Flag

The --module flag is used when a single build produces multiple logical components:

jf mvn clean install --build-name=my-app --build-number=1 --module=backend
jf mvn clean install --build-name=my-app --build-number=1 --module=frontend
jf rt build-publish my-app 1 --server-id=<your-server-id>

The resulting build-info for build my-app #1 contains two modules (backend and frontend), each with their own dependency trees.

--project Flag

The --project flag associates the build-info with a JFrog Project — an organizational unit in the JFrog Platform that groups repositories, builds, and security policies.

jf npm install --build-name=my-app --build-number=1 --project=my-team
jf rt build-publish my-app 1 --project=my-team --server-id=<your-server-id>

Wrapped Mode vs Native Mode

Which Tools Support Native Mode?

Native-only tools (build execution always runs native. The table's "Wrapped" concept doesn't apply to how jf <tool> itself runs):

Wrapped-only tools (no Native Mode support):

pip, Pipenv, Twine, Go, and Terraform operate only in Wrapped Mode.

Maven Native Mode

When JFROG_RUN_NATIVE=true is set, jf mvn runs Maven without injecting a generated settings.xml or applying .jfrog/projects/maven.yaml. You must configure Maven to resolve from Artifactory yourself using the Artifactory Set Me Up instructions for your Maven repository. The Set Me Up page generates a <server> entry with your Artifactory URL and credentials that you add to your ~/.m2/settings.xml.

To switch Maven to Native Mode when .jfrog/projects/maven.yaml exists:

1. Remove the wrapped-mode project file:

   Bash

   rm .jfrog/projects/maven.yaml

2. Enable Native Mode for the shell session:

   Bash

   export JFROG_RUN_NATIVE=true

Usage

To run a Maven build in Native Mode:

• Run:

  Bash

  export JFROG_RUN_NATIVE=true
  jf mvn clean install --build-name=my-app --build-number=1 --server-id=<your-server-id>

  Where:

  • <your-server-id>: The JFrog CLI server ID from jf config add

  For example:

  Bash

  export JFROG_RUN_NATIVE=true
  jf mvn clean install --build-name=my-app --build-number=1 --server-id=my-server

  To run the project's Maven Wrapper instead of mvn from PATH:

  Bash

  export JFROG_RUN_NATIVE=true
  jf mvnw clean install --build-name=my-app --build-number=1 --server-id=my-server

  jf mvnw requires mvnw or mvnw.cmd in the current directory or a parent directory. See Use Maven with JFrog CLI.

Expected output

When Native Mode is active (no .jfrog/projects/maven.yaml present), Maven runs directly and build-info is collected after the build completes:

[INFO] BUILD SUCCESS
[Info] Collecting build info for executed command...
[Info] Build info saved locally. Use 'jf rt bp my-app 1' to publish it to Artifactory.

What changes

• No settings.xml injection
• No .jfrog/projects/maven.yaml is read (requires the file to be absent — see the Important callout in this section)
• Build-info is collected after the build completes (post-execution, not via extractor injection)
• All Maven configuration comes from your own settings.xml
• Maven Wrapper: Native Mode jf mvn always uses mvn from PATH. It does not detect or run mvnw or mvnw.cmd. To use the project's Maven Wrapper, run jf mvnw instead. jf mvnw requires the wrapper script in the current directory or a parent directory and does not fall back to PATH. If .jfrog/projects/maven.yaml exists, jf mvnw behaves like jf mvn and follows jf mvn-config --use-wrapper. Requires JFrog CLI 2.117.0 or later.

Gradle Native Mode

When JFROG_RUN_NATIVE=true is set, jf gradle runs Gradle without injecting the Artifactory Gradle plugin or applying .jfrog/projects/gradle.yaml. You must configure Gradle to resolve from Artifactory yourself using the Artifactory Set Me Up instructions, which generate the repository URL and credential configuration you add to your build.gradle or gradle.properties.

To switch Gradle to Native Mode when .jfrog/projects/gradle.yaml exists:

1. Remove the wrapped-mode project file:

   Bash

   rm .jfrog/projects/gradle.yaml

2. Enable Native Mode for the shell session:

   Bash

   export JFROG_RUN_NATIVE=true

Usage

To run a Gradle build in Native Mode:

• Run:

  Bash

  export JFROG_RUN_NATIVE=true
  jf gradle clean build --server-id=<your-server-id>

  Where:

  • <your-server-id>: The JFrog CLI server ID to use for build-info (required in Native Mode)

  For example:

  Bash

  export JFROG_RUN_NATIVE=true
  jf gradle clean build --server-id=my-server

What changes

• No Artifactory Gradle plugin injection
• No .jfrog/projects/gradle.yaml is read (requires the file to be absent — see the Important callout in this section)
• Build-info is still collected when --build-name and --build-number are provided
• All Gradle configuration comes from your own build scripts

npm Native Mode

When JFROG_RUN_NATIVE=true is set (or the deprecated --run-native flag is used), jf npm delegates entirely to the native npm client and uses your .npmrc for all configuration. You must configure your .npmrc with the Artifactory registry URL and authentication token using the Artifactory Set Me Up instructions for your npm repository.

Usage

To run npm commands in Native Mode:

1. Enable Native Mode for the shell session:

   Bash

   export JFROG_RUN_NATIVE=true

2. Run install or publish (examples):

   Bash

   jf npm install --build-name=my-app --build-number=1
   jf npm publish --build-name=my-app --build-number=1 --server-id=<your-server-id>

   Where:

   • <your-server-id>: The JFrog CLI server ID for publish operations when you have multiple servers configured

   For example:

   Bash

   export JFROG_RUN_NATIVE=true
   jf npm install --build-name=my-app --build-number=1
   jf npm publish --build-name=my-app --build-number=1 --server-id=my-server

When Native Mode is active, the CLI confirms it at the start of execution:

[Info] Running npm in native mode (JFROG_RUN_NATIVE=true)

What changes

• No temporary .npmrc is created by the CLI
• Your own .npmrc is used for all configuration
• Build-info collection still works (as with other tools in Native Mode)
• Publishing uses the native npm publish lifecycle (prepublish, publish, postpublish scripts run normally — no renaming needed)

Poetry Native Mode

When JFROG_RUN_NATIVE=true is set, jf poetry delegates to the native Poetry client without injecting Artifactory configuration or modifying project files. You can run Poetry commands through jf poetry (to benefit from build-info collection) or directly via poetry (without build-info). You must configure Poetry to use the Artifactory repository using the Artifactory Set Me Up instructions for your PyPI repository. The Set Me Up page generates the poetry source add command and credential configuration you add to your project.

Usage

To run Poetry with build-info in Native Mode:

1. Enable Native Mode:

   Bash

   export JFROG_RUN_NATIVE=true

2. Run installs and publishes through jf poetry when you need build-info, or use native poetry when you do not:

   • With build-info:

     Bash

     jf poetry install --build-name=my-app --build-number=1
     jf poetry publish --build-name=my-app --build-number=1

   • Without build-info:

     Bash

     poetry install
     poetry build
     poetry publish -r artifactory

What changes

• No tool.poetry.source entries are injected into pyproject.toml
• No poetry update is called implicitly
• No poetry.lock modifications
• No .jfrog/projects/poetry.yaml is read
• Build-info is still collected when using jf poetry with --build-name and --build-number
• All configuration comes from Poetry's own config and Artifactory Set Me Up

Docker Native Mode

When JFROG_RUN_NATIVE=true is set, jf docker build runs the native Docker build directly instead of the legacy JFrog build flow. Build-info is still collected when --build-name and --build-number are provided. Prerequisites: the Docker daemon must be running (docker info), a JFrog server must be configured with jf config add, and you must be logged in to the Docker registry with docker login <registry> before running these commands. For details, see jf docker.

Usage

To build and push a Docker image in Native Mode:

1. Enable Native Mode, confirm the Docker daemon is running (docker info), and log in to the registry (docker login <registry>).

2. Run build, push, and publish build-info:

   Bash

   export JFROG_RUN_NATIVE=true
   jf docker build -t <registry>/<image>:<tag> . --build-name=my-app --build-number=1
   jf docker push <registry>/<image>:<tag> --build-name=my-app --build-number=1
   jf rt bp my-app 1 --server-id=<your-server-id>

   Where:

   • <registry>: Your Artifactory Docker registry host (for example, acme.jfrog.io)
   • <image>: Image name (for example, docker-local/my-app)
   • <tag>: Image tag (for example, 1.0.0)
   • <your-server-id>: The JFrog CLI server ID for jf rt bp

   For example:

   Bash

   export JFROG_RUN_NATIVE=true
   jf docker build -t acme.jfrog.io/docker-local/my-app:1.0.0 . --build-name=my-app --build-number=1
   jf docker push acme.jfrog.io/docker-local/my-app:1.0.0 --build-name=my-app --build-number=1
   jf rt bp my-app 1 --server-id=my-server

What changes

• Docker build runs via the native Docker client (no legacy JFrog build wrapper)
• Build-info is still collected when --build-name and --build-number are provided
• Push, pull, and scan behave the same in both modes

NuGet Native Mode

When you set JFROG_RUN_NATIVE=true, jf nuget runs the NuGet CLI you already installed and can collect build-info without jf nuget-config. Native Mode is available in JFrog CLI 2.123.0 or later. Point the command at your Artifactory NuGet repository, or keep using a NuGet configuration file you already manage.

To switch NuGet to Native Mode when .jfrog/projects/nuget.yaml exists:

1. Remove the wrapped-mode project file:

   Bash

   rm .jfrog/projects/nuget.yaml

   If you configured NuGet globally, remove the nuget.yaml file from the JFrog CLI home directory as well.

2. Enable Native Mode for the shell session:

   Bash

   export JFROG_RUN_NATIVE=true

Usage

To restore, pack, and push in Native Mode:

• Run:

  Bash

  export JFROG_RUN_NATIVE=true
  jf nuget restore --repo-resolve=<resolve-repo> --build-name=my-app --build-number=1 --server-id=<your-server-id>
  jf nuget pack --build-name=my-app --build-number=1
  jf nuget push <package>.nupkg --repo=<deploy-repo> --build-name=my-app --build-number=1 --server-id=<your-server-id>
  jf rt bp my-app 1

  Where:

  • <resolve-repo>: Artifactory NuGet repository used to restore packages, for example nuget-virtual.
  • <deploy-repo>: Artifactory NuGet repository used for push, for example nuget-local.
  • <your-server-id>: The JFrog CLI server ID from jf config add. Omit it to use the default server.

  For example:

  Bash

  export JFROG_RUN_NATIVE=true
  jf nuget restore MyApp.sln --repo-resolve=nuget-virtual --build-name=my-app --build-number=1 --server-id=my-server
  jf nuget push MyLib.1.0.0.nupkg --repo=nuget-local --build-name=my-app --build-number=1 --server-id=my-server
  jf rt bp my-app 1

If the project already lists the Artifactory source in its own NuGet configuration, omit --repo-resolve and --repo. JFrog CLI then leaves that configuration unchanged and still collects build-info when you pass --build-name and --build-number.

What Changes

• You can skip jf nuget-config.
• JFrog CLI doesn't rewrite your project NuGet configuration. --repo-resolve and --repo add the Artifactory source for that command only.
• --repo-resolve and --server-id apply in Native Mode. In Wrapped Mode, configure the repository with jf nuget-config.
• Build-info is collected when you provide --build-name and --build-number:
  • The restore, install, and update commands record dependencies.
  • The push and pack commands record .nupkg and .snupkg artifacts.
  • Other NuGet commands run unchanged and don't collect build-info.
• Add --nuget-v2 when the Artifactory repository uses the NuGet V2 protocol.

After a restore that collects build-info, the CLI prints:

[Info] NuGet build info collected. Use 'jf rt bp my-app 1' to publish it.

.NET Native Mode

When you set JFROG_RUN_NATIVE=true, jf dotnet runs the .NET CLI you already installed and can collect build-info without jf dotnet-config. Native Mode is available in JFrog CLI 2.123.0 or later. You can use it for SDK-style projects, including .slnx solutions.

To switch .NET to Native Mode when .jfrog/projects/dotnet.yaml exists:

1. Remove the wrapped-mode project file:

   Bash

   rm .jfrog/projects/dotnet.yaml

   If you configured .NET globally, remove the dotnet.yaml file from the JFrog CLI home directory as well.

2. Enable Native Mode for the shell session:

   Bash

   export JFROG_RUN_NATIVE=true

Usage

To restore, build, pack, and push in Native Mode:

• Run:

  Bash

  export JFROG_RUN_NATIVE=true
  jf dotnet restore --repo-resolve=<resolve-repo> --build-name=my-app --build-number=1 --server-id=<your-server-id>
  jf dotnet build --build-name=my-app --build-number=1
  jf dotnet pack --build-name=my-app --build-number=1
  jf dotnet nuget push <package>.nupkg --repo=<deploy-repo> --build-name=my-app --build-number=1 --server-id=<your-server-id>
  jf rt bp my-app 1

  Where:

  • <resolve-repo>: Artifactory NuGet repository used to restore packages
  • <deploy-repo>: Artifactory NuGet repository used by dotnet nuget push
  • <your-server-id>: The JFrog CLI server ID from jf config add. Omit it to use the default server.

  For example:

  Bash

  export JFROG_RUN_NATIVE=true
  jf dotnet restore MyApp.sln --repo-resolve=nuget-virtual --build-name=my-app --build-number=1 --server-id=my-server
  jf dotnet nuget push MyLib.1.0.0.nupkg --repo=nuget-local --build-name=my-app --build-number=1 --server-id=my-server
  jf rt bp my-app 1

jf dotnet build, jf dotnet pack, and jf dotnet publish restore packages unless you pass --no-restore. Pass --repo-resolve on those commands when the restore should use Artifactory. publish doesn't record build-info. dotnet add package also restores, but that subcommand can't take a NuGet configuration file. JFrog CLI doesn't apply --repo-resolve there. Run jf dotnet restore --repo-resolve=<resolve-repo> first.

What Changes

• You can skip jf dotnet-config.
• JFrog CLI doesn't rewrite your project NuGet configuration.
• Build-info is collected when you provide --build-name and --build-number:
  • The restore, build, and add commands record dependencies.
  • The pack and nuget push commands record package artifacts.
  • The test, run, and publish commands run unchanged and don't collect build-info.
• Publish with jf dotnet nuget push. jf dotnet push isn't a command.

Supported Client Versions

Recent JFrog CLI versions are forward-compatible with modern package manager clients. The "Max Client" column represents the highest version certified for build-info collection and Native execution without schema errors.

When to Use Which Mode

Use Wrapped Mode when you want:

• Integrated Artifactory resolution with zero manual configuration
• Automatic build-info capture
• Managed repository configuration via JFrog CLI
• Consistent, unified behaviour across machines and CI

Use Native Mode when you need:

• Strict lockfile fidelity (no modifications to lockfiles such as poetry.lock or package-lock.json)
• Zero modification to project metadata files such as pom.xml, pyproject.toml, or settings.xml
• Full compatibility with the upstream package manager's behaviour
• Builds that must be fully deterministic across environments
• Custom or advanced workflows configured directly in the package manager

Environment Variable Reference

When this variable is set to true, it applies to all commands in the current shell session. Unset it or start a new session to return to Wrapped Mode.

Frequently Asked Questions

This section provides answers to frequently asked questions.

Related Topics

• Build Tools Overview
• Connect a Build Tool to Artifactory with JFrog CLI
• Use Docker with JFrog CLI