CLI for JFrog Artifactory

Commands

The following sections describe the commands available in the JFrog CLI for use with Artifactory. 

Configuration

This command is used to configure JFrog CLI with Artifactory servers, which can later be used in the other commands. The configured Artifactory servers details can be overridden per command by passing in alternative values for the Artifactory URL and login credentials. The values configured are saved in ~/.jfrog/jfrog-cli.conf. 

You can set a default Artifactory server by using the jfrog rt use command.

Examples

Example 1

Configure the Artifactory URL and credentials using the interactive prompt. The unique ID for the new Artifactory server configuration will be rt-server-1.

$ jfrog rt c rt-server-1

Example 2

Configure the Artifactory URL, user and password by passing them in as command options.

$ jfrog rt c rt-server-1 --url=http://domain/artifactory --user=admin --password=password

Example 3

Configure the Artifactory URL and API key by passing them in as command options.

$ jfrog rt c rt-server-1 --url=http://domain/artifactory --apikey=APIKEY

Example 4

Delete the rt-server-1 server configuration.

$ jfrog rt c delete rt-server-1

Example 5

Show details of the rt-server-1 Artifactory server.

$ jfrog rt c show rt-server-1

Example 6

Show all configured Artifactory servers.

$ jfrog rt c show

Example 7

Clear all configured servers.

$ jfrog rt c clear

Using a Predefined Artifactory Server

You can configure multiple Artifactory instances using the config command. The 'use' command is used for specifying which of the configured Artifactory instances should be used for the following CLI commands.  

Examples

Example 1

$ jfrog rt use artifactory-server-1

Verifying Artifactory is Accessible

This command can be used to verify that Artifactory is accessible by sending an applicative ping to Artifactory.

Examples

Example 1

Ping the configured default Artifactory server.

$ jfrog rt ping

Example 2

Ping the configured Artifactory server with ID rt-server-1.

$ jfrog rt ping --server-id=rt-server-1

Example 3

Ping the Artifactory server. accessible though the specified URL.

$ jfrog rt ping --url=http://my-rt-server.com/artifactory

Uploading Files 

This command is used to upload files to Artifactory.

Examples

Example 1

Upload a file called froggy.tgz to the root of the my-local-repo repository.

 $ jfrog rt u froggy.tgz my-local-repo

Example 2

Collect all the zip artifacts located under the build directory (including sub-directories), and upload them to the my-local-repo repository, under the zipFiles folder, while maintaining the original names of the artifacts.

$ jfrog rt u "build/*.zip" libs-release-local/zipFiles/

$ jfrog rt u build\\*.zip libs-release-local/zipFiles/

Downloading Files

This command is used to download files from Artifactory

Examples

Example 1

Download an artifact called cool-frog.zip located at the root of the my-local-repo repository to the current directory.

$ jfrog rt dl my-local-repo/cool-froggy.zip

Example 2

Download all artifacts located under the all-my-frogs directory in the my-local-repo repository to the all-my-frogs folder under the current directory.

$ jfrog rt dl my-local-repo/all-my-frogs/ all-my-frogs/

Example 3

Download all artifacts located in the my-local-repo repository with a jar extension to the all-my-frogs folder under the current directory.

$ jfrog rt dl "my-local-repo/*.jar" all-my-frogs/

Copying Files

This command is used to copy files in Artifactory

Examples

Example 1

Copy all artifacts located under /rabbit in the source-frog-repo repository into the same path in the target-frog-repo repository.

jfrog rt cp source-frog-repo/rabbit/ target-frog-repo/rabbit/

Example 2

Copy all zip files located under /rabbit in the source-frog-repo repository into the same path in the target-frog-repo repository.

 jfrog rt cp "source-frog-repo/rabbit/*.zip" target-frog-repo/rabbit/

Example 3

Copy all artifacts located under /rabbit in the source-frog-repo repository and with property "Version=1.0" into the same path in the target-frog-repo repository  .

 jfrog rt cp "source-frog-repo/rabbit/*" target-frog-repo/rabbit/ --props=Version=1.0

Moving Files

This command is used to move files in Artifactory

Examples

Example 1

Move all artifacts located under /rabbit in the source-frog-repo repository into the same path in the target-frog-repo repository.

jfrog rt mv source-frog-repo/rabbit/ target-frog-repo/rabbit/

Example 2

Move all zip files located under /rabbit in the source-frog-repo repository into the same path in the target-frog-repo repository.

 jfrog rt mv "source-frog-repo/rabbit/*.zip" target-frog-repo/rabbit/

Example 3

Move all artifacts located under /rabbit in the source-frog-repo repository and with property "Version=1.0" into the same path in the target-frog-repo repository  .

 jfrog rt mv "source-frog-repo/rabbit/*" target-frog-repo/rabbit/ --props=Version=1.0

Deleting Files

This command is used to delete files in Artifactory

Examples

Example 1

Delete all artifacts located under /rabbit in the frog-repo repository.

 jfrog rt del frog-repo/rabbit/

Example 2

Delete all zip files located under /rabbit in the frog-repo repository.

  jfrog rt del "frog-repo/rabbit/*.zip"

Searching Files

This command is used to search and display files in Artifactory.

Examples

Example 1

Display a list of all artifacts located under /rabbit in the frog-repo repository.

 jfrog rt s frog-repo/rabbit/

Example 2

Display a list of all zip files located under /rabbit in the frog-repo repository.

  jfrog rt s "frog-repo/rabbit/*.zip"

Setting Properties on Files

This command is used for setting properties on existing files in Artifactory.

Example

Set the properties on all the zip files in the generic-local repository. The command will set the property "a" with "1" value and the property "b" with two values: "2" and "3".

jfrog rt sp "generic-local/*.zip" "a=1;b=2,3"

Build Integration - Collecting Environment Variables

This command is used to collect environment variables and attach them to a build.

For more details, please refer to Build Integration.

Example

Collect environment variables for build name: frogger-build and build number: 17

 jfrog rt bce frogger-build 17

Build Integration - Adding Git Information

This command is used for adding Git VCS details, stored in a local .git directory, to a build.

For more details, please refer to Build Integration.

Example

 jfrog rt bag frogger-build 17 checkout-dir

Build Integration - Adding Local Files As Build Dependencies

The download command, as well as other commands which download dependencies from Artifactory accept the --build-name and --build-number command options. Adding these options records the downloaded files as build dependencies. In some cases however, you'd like to add file, which have been downloaded by another tool, to a build. Use this command to to this.

For more details, please refer to Build Integration,

Example

jfrog rt bad my-build-name 7 "path/to/build/dependencies/dir/"

Build Integration - Publishing a Build

This command is used to publish build info to Artifactory.

For more details, please refer to Build Integration,

Example

 jfrog rt bp my-build-name 18

Build Integration - Promoting a Build

This command is used to promote build in Artifactory.

For more details, please refer to Build Integration,

Example

 jfrog rt bpr my-build-name 18 target-repository

Build Integration - Distributing a Build

This command is used to deploy builds from Artifactory to Bintray, and creates an entry in the corresponding Artifactory distribution repository specified.

For more details, please refer to Build Integration,

Example

 jfrog rt bd my-build-name 18 target-distribution-repository

Build Integration - Scanning a Published Build

JFrog CLI is integrated with JFrog Xray through JFrog Artifactory allowing you to have build artifacts scanned for vulnerabilities and other issues. This integration requires JFrog Artifactory v4.16 and above and JFrog Xray v1.6 and above. For more information, see CI-CD build integration.

This command allows scanning a build, which had already been published to Artifactory using the build-publish command.

Example

 jfrog rt bs my-build-name 18

Build Integration - Clean Build

This command is used to clean (remove) build info collected locally.

For more details, please refer to Build Integration.

Example

 jfrog rt bc my-build-name 18

Cleaning Up Unreferenced Files from a Git LFS Repository

This command is used to clean up files from a Git LFS repository. This deletes all files from a Git LFS repository, which are no longer referenced in a corresponding Git repository.

Examples

Example 1

Cleans up Gil LFS files from Artifactory, using the configuration in the .git directory located at the current directory.

$ jfrog rt glc

Example 2

Cleans up Gil LFS files from Artifactory, using the configuration in the .git directory located inside the path/to/git/config directory.

$ jfrog rt glc path/to/git/config

Using Placeholders

The JFrog CLI offers enormous flexibility in how you download, upload, copy, or move files through use of wildcard or regular expressions with placeholders in the upload command.

Any wildcard enclosed in parenthesis in the source path can be matched with a corresponding placeholder in the target path to determine the name of the artifact once uploaded.

Examples

Example 1

For each .tgz file in the source directory, create a corresponding directory with the same name in the target repository and upload it to there. For example, a file called froggy.tgz should be uploaded to my-local-rep/froggy/froggy.tgz.

$ jfrog rt u "(*).tgz" my-local-repo/{1}/ --recursive=false

Example 2

Upload all files whose name begins with "frog" to folder frogfiles in the target repository, but append its name with the text "-up". For example, a file called froggy.tgz should be renamed froggy.tgz-up.

$ jfrog rt u "(frog*)" my-local-repo/frogfiles/{1}-up --recursive=false

Example 3

Upload all files in the current directory to the my-local-repo repository and place them in directories which match their file extensions.

$ jfrog rt u "(*).(*)" my-local-repo/{2}/{1}.{2} --recursive=false

Example 4

Copy all zip files under /rabbit in the source-frog-repo repository into the same path in the target-frog-repo repository and append the copied files' names with ".cp".

jfrog rt cp "source-frog-repo/rabbit/(*.zip)" target-frog-repo/rabbit/{1}.cp

Build Integration

JFrog CLI integrates with any development ecosystem allowing you to collect build information and then publish it to Artifactory. By publishing build information to Artifactory, JFrog CLI empowers Artifactory to provide visibility into artifacts deployed, dependencies used and exhaustive information on the build environment to allow fully traceable builds. 

Running Maven and Gradle Builds

JFrog CLI includes integration with Maven and Gradle, allowing you to configure these build tools to resolve dependencies and deploy build artifacts from and to Artifactory, while collecting build-info and storing it in Artifactory. 

To configure and run your build, take the following actions:

1. Create the build configuration file.

2. Run the build with the configuration file as an argument.

Creating the Build Configuration File

To create a build configuration file for a maven build, run the following command. The command's argument is a path to a new file which will be created by the command:

$ jfrog rt mvnc /path/to/a/non/existing/config/file

To create a build configuration file for a gradle build, run the following command. The command's argument is a path to a new file which will be created by the command:

$ jfrog rt gradlec /path/to/a/non/existing/config/file

Running the Build

To run a maven build, run the following command, with the path to the build configuration you created:

$ jfrog rt mvn "clean install -f path/to/pom-file" /path/to/config/file --build-name=mvn-build-name --build-number=1

To run a gradle build, run the following command, with the path to the build configuration you created:

$ jfrog rt gradle "clean artifactoryPublish -b path/to/build.gradle" /path/to/config/file --build-name=gradle-build-name --build-number=1

jfrog rt docker-push my-docker-registry.io/my-docker-image:latest docker-local --build-name=my-build-name --build-number=7

jfrog rt npm-install my-remote-npm-repo --build-name=my-build-name --build-number=1 --npm-args="--only=prod"

jfrog rt npm-install my-remote-npm-repo

jfrog rt npm-publish my-local-npm-repo --build-name=my-build-name --build-number=1

jfrog rt go build go-virtual

jfrog rt go build go-virtual --no-registry=true

jfrog rt gp go-virtual --build-name=my-build-name --build-number=1

jfrog rt gp go-virtual --deps=ALL --build-name=my-build-name --build-number=1

jfrog rt gp go-virtual --deps=rsc.io/quote:v1.5.2,rsc.io/sampler:v1.3.0 --build-name=my-build-name --build-number=1

Collecting Build Information

Build information is collected by adding the --build-name and --build-number options to different CLI commands. The CLI commands can be run several times and cumulatively collect build information for the specified build name and number until it is published to Artifactory. For example, running the download command several times with the same build name and number will accumulate each downloaded file in the corresponding build information. 

Dependencies

Dependencies are collected by adding  the --build-name and --build-number options to the download command .

For example, the following command downloads the cool-froggy.zip file found in repository my-local-repo , but it also specifies this file as a dependency in build my-build-name with build number 18:

jfrog rt dl my-local-repo/cool-froggy.zip --build-name=my-build-name --build-number=18

Build Artifacts

Build artifacts are collected by adding  the --build-name and --build-number options to the upload command. 

For example, the following command specifies that file froggy.tgz uploaded to repository my-local-repo is a build artifact of build my-build-name with build number 18:

jfrog rt u froggy.tgz my-local-repo --build-name=my-build-name --build-number=18

Environment Variables

Environment variables are collected using the build-collect-env (bce) command.

For example, the following command collects all currently known environment variables, and attaches them to the build information for build my-build-name with build number 18:

jfrog rt bce my-build-name 18

To view additional commands, please refer to the Build Integration-Collecting Environment Variables section.

Cleanup

Build information is accumulated by the CLI according to the commands you apply until you publish the build information to Artifactory. If, for any reason, you wish to "reset" the build information and cleanup (i.e. delete) any information accumulated so far, you can use the build-clean (bc) command. For example, the following command cleans up any build information collected for build my-build-name with build number 18:

jfrog rt bc my-build-name 18

Publishing Build Information

To publish the accumulated build information for a build to Artifactory, use the build-publish (bp) command. For example, the following command publishes all the build information collected for build my-build-name with build number 18:

jfrog rt bp my-build-name 18

Using File Specs

To achieve complex file manipulations you may require several CLI commands. For example, you may need to upload several different sets of files to different repositories. To simplify the implementation of these complex manipulations, you can apply JFrog CLI download, upload, move, copy and delete commands with JFrog Artifactory using --spec option to replace the inline command arguments and options. Each command uses an array of file specifications in JSON format with a corresponding schema as described in the sections below. Note that if any of these commands are issued using both inline options as well as the file specs, then the inline options override their counterparts specified in the file specs.

File Spec Schemas

Download, Copy and Move Commands Spec Schema

The file spec schema for the download, copy and move commands is as follows:

{
	"files": [
   		{
	    	"pattern" or "aql": "[Mandatory]",
    	  	"target": "[Optional]",
      		"props": "[Optional]",
     	 	"recursive": "[Optional, Default: 'true']",
      		"flat" : "[Optional, Default: 'false']",
			"excludePatterns": ["[Optional, Applicable only when 'pattern' is specified]"],
			"sortBy" : ["[Optional]"],
			"sortOrder": "[Optional, Default: 'asc']",
			"limit": [Optional],
			"offset": [Optional]
    	}
  	]
}

Upload Command Spec Schema

The file spec schema for the upload command is as follows:

{
	"files": [
   		{
      		"pattern": "[Mandatory]",
   			"target": "[Mandatory]",
      		"props": "[Optional]",
      		"recursive": "[Optional, Default: 'true']",
      		"flat" : "[Optional, Default: 'true']",
      		"regexp": "[Optional, Default: 'false']",
			"excludePatterns": ["[Optional]"],
			"sortBy" : ["[Optional]"],
			"sortOrder": "[Optional, Default: 'asc']",
			"limit": [Optional],
			"offset": [Optional]
    	}
  	]
}

Search, Set-Props and Delete Commands Spec Schema

The file spec schema for the search and delete commands are as follows:

{
	"files": [
   		{
      		"pattern" or "aql": "[Mandatory]",
      		"props": "[Optional]",
      		"recursive": "[Optional, Default: 'true']",
			"excludePatterns": ["[Optional, Applicable only when 'pattern' is specified]"],
			"sortBy" : ["[Optional]"],
			"sortOrder": "[Optional, Default: 'asc']",
			"limit": [Optional],
			"offset": [Optional]
    	}
  	]
}

Examples

The following are examples of file specs that could be used to download files.

Example 1: Download all files located under the all-my-frogs directory in the my-local-repo repository to the froggy/all-my-frogs directory.

{
	"files": [
   		{
      		"pattern": "my-local-repo/all-my-frogs/",
			"target": "froggy/"
    	}
  	]
}

Example 2: Download all files retrieved by the AQL query to the froggy directory.

{
  "files": [
    {
      "aql": {
        "items.find": {
          "repo": "my-local-repo",
          "$or": [
            {
              "$and": [
                {
                  "path": {
                    "$match": "."
                  },
                  "name": {
                    "$match": "a1.in"
                  }
                }
              ]
            },
            {
              "$and": [
                {
                  "path": {
                    "$match": "*"
                  },
                  "name": {
                    "$match": "a1.in"
                  }
                }
              ]
            }
          ]
        }
      },
      "target": "cli-reg-test/spec-copy-test/aql-a1/"
    }
  ]
} 

Example 3: Upload

1. All zip files located under the resources directory to the zip folder, under the all-my-frogs repository.
   AND 
2. All TGZ files located under the resources directory to the tgz folder, under the all-my-frogs repository.
3. Tag all zip files with type = zip and status = ready.
4. Tag all tgz files with type = tgz and status = ready.

{
  "files": [
    {
      "pattern": "resources/*.zip",
      "target": "my-repo/zip/",
      "props": "type=zip;status=ready"
    },
    {
      "pattern": "resources/*.tgz",
      "target": "my-repo/tgz/",
	  "props": "type=tgz;status=ready"
    }
  ]
}

Example 4: Download all files located under the all-my-frogs directory in the my-local-repo repository except for files with .txt extension and all files inside the all-my-frogs directory with the props. prefix.

Notice that the exclude patterns do not include the repository.

{
	"files": [
	 {
		"pattern": "my-local-repo/all-my-frogs/",
		"excludePatterns": ["*.txt","all-my-frog/props.*"]
     }
	]
}
 

Example 5: Download The latest file uploaded to the all-my-frogs directory in the my-local-repo repository.

{
	"files": [
	 {
		"pattern": "my-local-repo/all-my-frogs/",
		"target": "my-repo/files/",
        "sortBy": "created",
        "sortOrder": "desc",
        "limit": 1,
     }
	]
}

Example 6: Search for the three largest files located under the all-my-frogs directory in the my-local-repo repository. If there are files with the same size, sort them "internally" by creation date.

{
	"files": [
	 {
		"pattern": "my-local-repo/all-my-frogs/",
        "sortBy": ["size","created"],
        "sortOrder": "desc",
        "limit": 3
     }
	]
}

Example 7: Download The second latest file uploaded to the all-my-frogs directory in the my-local-repo repository.

{
	"files": [
	 {
		"pattern": "my-local-repo/all-my-frogs/",
		"target": "my-repo/files/",
        "sortBy": "created",
        "sortOrder": "desc",
        "limit": 1,
		"offset": 1
     }
	]
}

Storing Symlinks in Artifactory

JFrog CLI lets you upload and download artifacts from your local file-system to Artifactory, this also includes uploading symlinks (soft links).

Symlinks are stored in Artifactory as files with a zero size, with the following properties:
symlink.dest - The actual path on the original filesystem to which the symlink points
symlink.destsha1 - the SHA1 checksum of the value in the symlink.dest property

To upload symlinks, the upload command should be executed with the --symlinks option set to true.
To download symlinks stored in Artifactory, the download command should be executed with the --symlinks option set to true.

In addition, when downloading symlinks stored in Artifactory, the CLI can verify that the file to which the symlink points actually exists and that it has the correct SHA1 checksum. To add this validation, you should use the --validate-symlinks option with the download command.