CLI for JFrog Artifactory

Overview

This page describes how to use JFrog CLI with JFrog Artifactory.

Syntax

When used with JFrog Artifactory, JFrog CLI uses the following syntax:

$ jfrog rt command-name global-options command-options arguments

where:

command-name	The command to execute. Note that you can use either the full command name or its abbreviation.
global-options	A set of global options that may be used for all commands: `--url:` (Mandatory) The Artifactory URL. `--user:` (Optional) The Artifactory user. `--password:` (Optional) The Artifactory password. `--apikey:` (Optional) The Artifactory API key. `--access-token:` (Optional) The Artifactory access token. `--ssh-key-path:` (Optional) The path to your SSH key file when authenticating with your RSA keys.
command-options	A set of options corresponding to the command
arguments	A set of arguments corresponding to the command

Environment Variables

The Artifactory upload command makes use of the following environment variable:

Variable Name	Description
JFROG_CLI_MIN_CHECKSUM_DEPLOY_SIZE_KB	[Default: 10] Minimum file size in KB for which JFrog CLI performs checksum deploy optimization.
JFROG_CLI_JCENTER_REMOTE_SERVER	Configured Artifactory server ID from which to download the jar needed by the maven and gradle integration commands. The Artifactory server should include a remote maven repository named jcenter, which proxies jcenter.
JFROG_CLI_JCENTER_REMOTE_REPO	[Default: jcenter] Can be optionally used with the JFROG_CLI_JCENTER_REMOTE_SERVER environment variable. Determines the name of the remote repository to use.

Read about additional environment variables at the Welcome to JFrog CLI page.

Authentication

When used with Artifactory, JFrog CLI offers several means of authentication: JFrog CLI does not support accessing Artifactory without authentication.

Currently, only Login Credentials are supported when working with external package managers and build tools (Maven, Gradle, Npm, Docker and NuGet)

Authenticating with Login Credentials

To authenticate yourself using your Artifactory login credentials, either configure your credentials once using the config command or use the --user and --password command options with each command.

Authenticating with an API key

To authenticate yourself using your Artifactory API Key, either configure your credentials once using the config command or use the --apikey command option with each command.

Authenticating with an Access Token

To authenticate yourself using an Artifactory Access Token, either configure your Access Token once using the config command or use the --access-token command option with each command.

Authenticating with RSA Keys

From version 4.4, Artifactory supports SSH authentication using RSA public and private keys. To authenticate yourself to Artifactory using RSA keys, execute the following instructions:

Enable SSH authentication as described in Configuring SSH.
Configure your Artifactory URL to have the following format: ssh://[host]:[port] There are two ways to do this:
- For each command, use the --url command option.
- Specify the Artifactory URL in the correct format using the config command.
Don't include your Artifactory context URL
Make sure that the [host] component of the URL only includes the host name or the IP, but not your Artifactory context URL.
Configure the path to your SSH key file. There are two ways to do this:
- For each command, use the --ssh-key-path command option.
- Specify the path using the config command.

Using Self-signed SSL Certificates

From version 1.1, JFrog CLI supports accessing Artifactory over SSL using self-signed certificates as follows:

Under your user home directory, you should find a directory named .jfrog (this directory is created by the JFrog CLI first time it is used).
Under .jfrog, create a directory called security
Place your SSL certificate in your ~/.jfrog/security directory

Note that you can place multiple SSL certificates in your ~/.jfrog/security directory.

Page Contents

General 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.

Command name	config
Abbreviation	c
Command options
--url	[Optional] The default Artifactory URL to be used for the other commands.
--user	[Optional] The default user to be used for the other commands.
--password	[Optional] The default password to be used for the other commands. Password Encryption Policy If the Artifactory instance you are trying to access has its Password Encryption Policy set to `Required` then you need to pass in your API key as your password.
--apikey	[Optional] The default API key to be used for the other commands.
--access-token	[Optional] The default access token to be used for the other commands.
--interactive	[Default: true] If true, the `config` command is interactive. This means that passing in the Artifactory URL (using `--url`) is optional. If it is not passed in as a command option, the CLI will interactively ask you for it when you issue the command. If false, you must pass in the Artifactory URL as a command option.
--enc-password	[Default: true] If true, the configured password will be encrypted using Artifactory's encryption API before being stored. If false, the configured password will not be encrypted.
Command arguments	If no arguments are passed in, the command will configure the Artifactory URL, user and password through the command options or through the interactive prompt
server ID	A unique ID for the new Artifactory server configuration.
show	Shows the stored configuration. In case this argument is followed by a configured server ID, then only this server's configurations is shown
delete	This argument should be followed by a configured server ID. The configuration for this server ID will be deleted.
clear	Clears all stored configuration.

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.

Command name	use
Abbreviation	N/A
Command options	The command has no options.
Command arguments
Server ID	The configured Artifactory server ID to use

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.

Command name	ping
Abbreviation	p

Command options
--url	[Optional] Artifactory URL.
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
Command arguments	The command accepts no arguments.

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.

Command name	upload
Abbreviation	u
Command options	When using the * or ; characters in the upload command options or arguments, make sure to wrap the whole options or arguments string in quotes (") to make sure the * or ; characters are not interpreted as literals.
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
--spec	[Optional] Path to a file spec. For more details, please refer to Using File Specs.
--spec-vars	[Optional] List of variables in the form of "key1=value1;key2=value2;..." to be replaced in the File Spec. In the File Spec, the variables should be used as follows: ${key1}.
--build-name	[Optional] Build name. For more details, please refer to Build Integration.
--build-number	[Optional] Build number. For more details, please refer to Build Integration.
--props	[Optional] A list of Artifactory properties specified as "key=value" pairs separated by a semi-colon ( ; ) to be attached to the uploaded files. If any key can take several values, then each value is separated by a comma ( , ). For example, "key1=value1;key2=value21,value22;key3=value3".
--deb	[Optional] Used for Debian packages only. Specifies the distribution/component/architecture of the package. If the the value for distribution, component or architecture include a slash. the slash should be escaped with a back-slash.
--flat	[Default: true] If true, artifacts are uploaded to the exact target path specified and their hierarchy in the source file system is ignored. If false, artifacts are uploaded to the target path while maintaining their file system hierarchy.
--recursive	[Default: true] If true, artifacts are also collected from sub-folders of the source directory for upload . If false, only artifacts specifically in the source directory are uploaded.
--regexp	[Default: false] If true, the command will interpret the first argument, which describes the local file-system path of artifacts to upload, as a regular expression. If false, the command will interpret the first argument, which describes the local file-system path of artifacts to upload, as a wild-card expression.
--threads	[Default: 3] The number of parallel threads that should be used to upload where each thread uploads a single artifact at a time.
--dry-run	[Default: false] If true, the command only indicates which artifacts would have been uploaded If false, the command is fully executed and uploads artifacts as specified
--symlinks	[Default: false] If true, the command will preserve the soft links structure in Artifactory. The symlink file representation will contain the symbolic link and checksum properties.
--explode	[Default: false] If true, the command will extract an archive containing multiple artifacts after it is deployed to Artifactory, while maintaining the archive's file structure.
--include-dirs	[Default: false] If true, the source path applies to bottom-chain directories and not only to files. Botton-chain directories are either empty or do not include other directories that match the source path.
--exclude-patterns	A list of Semicolon-separated exclude patterns. Allows using wildcards or a regular expression according to the value of the 'regexp' option.
--sort-by	[Optional] A list of semicolon-separated fields to sort by. The fields must be part of the 'items' AQL domain. For more information read the AQL documentation
--sort-order	[Default: asc] The order by which fields in the 'sort-by' option should be sorted. Accepts 'asc' or 'desc'.
--limit	[Optional] The maximum number of items to fetch. Usually used with the 'sort-by' option.
--offset	[Optional] The offset from which to fetch items (i.e. how many items should be skipped). Usually used with the 'sort-by' option.
--fail-no-op	[Default: false] Set to true if you'd like the command to return exit code 2 in case of no files are affected.
--retries	[Default: 3] Number of upload retries.
Command arguments	The command takes two arguments. In case the --spec option is used, the commands accepts no arguments.
Source path	The first argument specifies the local file system path to artifacts which should be uploaded to Artifactory. You can specify multiple artifacts by using wildcards or a regular expression as designated by the `--regexp` command option. If you have specified that you are using regular expressions, then the first one used in the argument must be enclosed in parenthesis. Working on Windows? When working on Windows, the source path is interpreted by the CLI on your Windows system, so you need to specify the source path in Windows notation using \\ instead of the / character. The target path specified is interpreted by Artifactory which assumes a Unix-like notation, so the target path should be specified using the / character.
Target path	The second argument specifies the target path in Artifactory in the following format: `[repository_name]/[repository_path]` If the target path ends with a slash, the path is assumed to be a folder. For example, if you specify the target as "repo-name/a/b/", then "b" is assumed to be a folder in Artifactory into which files should be uploaded. If there is no terminal slash, the target path is assumed to be a file to which the uploaded file should be renamed. For example, if you specify the target as "repo-name/a/b", the uploaded file is renamed to "b" in Artifactory. For flexibility in specifying the upload path, you can include placeholders in the form of {1}, {2} which are replaced by corresponding tokens in the source path that are enclosed in parenthesis. For more details, please refer to Using Placeholders.

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.

On linux-based systems

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

On Windows-based systems

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

Downloading Files

This command is used to download files from Artifactory

Command name	download
Abbreviation	dl
Command options	When using the * or ; characters in the download command options or arguments, make sure to wrap the whole options or arguments string in quotes (") to make sure the * or ; characters are not interpreted as literals.
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
--build-name	[Optional] Build name. For more details, please refer to Build Integration.
--build-number	[Optional] Build number. For more details, please refer to Build Integration.
--spec	[Optional] Path to a file spec. For more details, please refer to Using File Specs.
--spec-vars	[Optional] List of variables in the form of "key1=value1;key2=value2;..." to be replaced in the File Spec. In the File Spec, the variables should be used as follows: ${key1}.
--props	[Optional] A list of Artifactory properties specified as "key=value" pairs separated by a semi-colon (for example, "key1=value1;key2=value2;key3=value3"). Only artifacts with all of the specified properties be downloaded.
--build	[Optional] If specified, only artifacts of the specified build are matched. The property format is build-name/build-number. If you do not specify the build number, the artifacts are filtered by the latest build number.
--flat	[Default: false] If true, artifacts are downloaded to the exact target path specified and their hierarchy in the source repository is ignored. If false, artifacts are downloaded to the target path in the file system while maintaining their hierarchy in the source repository.
--recursive	[Default: true] If true, artifacts are also downloaded from sub-paths under the specified path in the source repository. If false, only artifacts in the specified source path directory are downloaded.
--threads	[Default: 3] The number of parallel threads that should be used to download where each thread downloads a single artifact at a time.
--split-count	[Default: 3] The number of segments into which each file should be split for download (provided the artifact is over `--min-split` in size). To download each file in a single thread, set to 0.
--retries	[Default: 3] Number of download retries.
--min-split	[Default: 5120] The minimum size permitted for splitting. Files larger than the specified number will be split into equally sized `--split-count` segments. Any files smaller than the specified number will be downloaded in a single thread. If set to -1, files are not split.
--dry-run	[Default: false] If true, the command only indicates which artifacts would have been downloaded. If false, the command is fully executed and downloads artifacts as specified.
--explode	[Default: false] Set to true to extract an archive after it is downloaded from Artifactory
--validate-symlinks	[Default: false] If true, the command will validate that symlinks are pointing to existing and unchanged files, by comparing their sha1. Applicable to files and not directories.
--include-dirs	[Default: false] If true, the source path applies to bottom-chain directories and not only to files. Botton-chain directories are either empty or do not include other directories that match the source path.
--exclude-patterns	A list of Semicolon-separated exclude patterns. Allows using wildcards as part of the pattern. Unlike the Source path, must not include the repository name at the beginning of the path.
--sort-by	[Optional] A list of semicolon-separated fields to sort by. The fields must be part of the 'items' AQL domain. For more information read the AQL documentation
--sort-order	[Default: asc] The order by which fields in the 'sort-by' option should be sorted. Accepts 'asc' or 'desc'.
--limit	[Optional] The maximum number of items to fetch. Usually used with the 'sort-by' option.
--offset	[Optional] The offset from which to fetch items (i.e. how many items should be skipped). Usually used with the 'sort-by' option.
--fail-no-op	[Default: false] Set to true if you'd like the command to return exit code 2 in case of no files are affected.
--archive-entries	[Optional] If specified, only archive artifacts containing entries matching this pattern are matched. You can use wildcards to specify multiple artifacts.
Command arguments
Source path	Specifies the source path in Artifactory, from which the artifacts should be downloaded, in the following format: `[repository name]/[repository path].` You can use wildcards to specify multiple artifacts.
Target path	The second argument is optional and specifies the local file system target path. If the target path ends with a slash, the path is assumed to be a directory. For example, if you specify the target as "repo-name/a/b/", then "b" is assumed to be a directory into which files should be downloaded. If there is no terminal slash, the target path is assumed to be a file to which the downloaded file should be renamed. For example, if you specify the target as "a/b", the downloaded file is renamed to "b". For flexibility in specifying the target path, you can include placeholders in the form of {1}, {2} which are replaced by corresponding tokens in the source path that are enclosed in parenthesis. For more details, please refer to Using Placeholders.

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

Command name	copy
Abbreviation	cp
Command options	When using the * or ; characters in the copy command options or arguments, make sure to wrap the whole options or arguments string in quotes (") to make sure the * or ; characters are not interpreted as literals.
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
--spec	[Optional] Path to a file spec. For more details, please refer to Using File Specs.
--props	[Optional] A list of Artifactory properties specified as "key=value" pairs separated by a semi-colon. (For example, "key1=value1;key2=value2;key3=value3"). Only artifacts with these properties will be copied.
--build	[Optional] If specified, only artifacts of the specified build are matched. The property format is build-name/build-number. If you do not specify the build number, the artifacts are filtered by the latest build number.
--flat	[Default: false] If true, artifacts are copied to the exact target path specified and their hierarchy in the source path is ignored. If false, artifacts are copied to the target path while maintaining their source path hierarchy.
--recursive	[Default: true] If true, artifacts are also copied from sub-paths under the specified source path. If false, only artifacts in the specified source path directory are copied.
--dry-run	[Default: false] If true, the command only indicates which artifacts would have been copied. If false, the command is fully executed and copies artifacts as specified.
--exclude-patterns	A list of Semicolon-separated exclude patterns. Allows using wildcards as part of the pattern. Unlike the Source path, must not include the repository name at the beginning of the path.
--sort-by	[Optional] A list of semicolon-separated fields to sort by. The fields must be part of the 'items' AQL domain. For more information read the AQL documentation
--sort-order	[Default: asc] The order by which fields in the 'sort-by' option should be sorted. Accepts 'asc' or 'desc'.
--limit	[Optional] The maximum number of items to fetch. Usually used with the 'sort-by' option.
--offset	[Optional] The offset from which to fetch items (i.e. how many items should be skipped). Usually used with the 'sort-by' option.
--fail-no-op	[Default: false] Set to true if you'd like the command to return exit code 2 in case of no files are affected.
--archive-entries	[Optional] If specified, only archive artifacts containing entries matching this pattern are matched. You can use wildcards to specify multiple artifacts.
Command arguments	The command takes two arguments
Source path	Specifies the source path in Artifactory, from which the artifacts should be copied, in the following format: `[repository name]/[repository path].` You can use wildcards to specify multiple artifacts.
Target path	Specifies the target path in Artifactory, to which the artifacts should be copied, in the following format: `[repository name]/[repository path]` If the pattern ends with a slash, the target path is assumed to be a folder. For example, if you specify the target as "repo-name/a/b/", then "b" is assumed to be a folder in Artifactory into which files should be copied. If there is no terminal slash, the target path is assumed to be a file to which the copied file should be renamed. For example, if you specify the target as "repo-name/a/b", the copied file is renamed to "b" in Artifactory. For flexibility in specifying the target path, you can include placeholders in the form of {1}, {2} which are replaced by corresponding tokens in the source path that are enclosed in parenthesis. For more details, please refer to Using Placeholders.

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

Command name	move
Abbreviation	mv
Command options	When using the * or ; characters in the copy command options or arguments, make sure to wrap the whole options or arguments string in quotes (") to make sure the * or ; characters are not interpreted as literals.
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
--spec	[Optional] Path to a file spec. For more details, please refer to Using File Specs.
--props	[Optional] A list of Artifactory properties specified as "key=value" pairs separated by a semi-colon (for example, "key1=value1;key2=value2;key3=value3"). Only artifacts with these properties will be moved.
--build	[Optional] If specified, only artifacts of the specified build are matched. The property format is build-name/build-number. If you do not specify the build number, the artifacts are filtered by the latest build number.
--flat	[Default: false] If true, artifacts are moved to the exact target path specified and their hierarchy in the source path is ignored. If false, artifacts are moved to the target path while maintaining their source path hierarchy.
--recursive	[Default: true] If true, artifacts are also moved from sub-paths under the specified source path. If false, only artifacts in the specified source path directory are moved.
--dry-run	[Default: false] If true, the command only indicates which artifacts would have been moved. If false, the command is fully executed and downloads artifacts as specified.
--exclude-patterns	A list of Semicolon-separated exclude patterns. Allows using wildcards as part of the pattern. Unlike the Source path, must not include the repository name at the beginning of the path.
--sort-by	[Optional] A list of semicolon-separated fields to sort by. The fields must be part of the 'items' AQL domain. For more information read the AQL documentation
--sort-order	[Default: asc] The order by which fields in the 'sort-by' option should be sorted. Accepts 'asc' or 'desc'.
--limit	[Optional] The maximum number of items to fetch. Usually used with the 'sort-by' option.
--offset	[Optional] The offset from which to fetch items (i.e. how many items should be skipped). Usually used with the 'sort-by' option.
--fail-no-op	[Default: false] Set to true if you'd like the command to return exit code 2 in case of no files are affected.
--archive-entries	[Optional] If specified, only archive artifacts containing entries matching this pattern are matched. You can use wildcards to specify multiple artifacts.
Command arguments	The command takes two arguments
Source path	Specifies the source path in Artifactory, from which the artifacts should be moved, in the following format: `[repository name]/[repository path].` You can use wildcards to specify multiple artifacts.
Target path	Specifies the target path in Artifactory, to which the artifacts should be moved, in the following format: `[repository name]/[repository path]` If the pattern ends with a slash, the target path is assumed to be a folder. For example, if you specify the target as "repo-name/a/b/", then "b" is assumed to be a folder in Artifactory into which files should be moved. If there is no terminal slash, the target path is assumed to be a file to which the moved file should be renamed. For example, if you specify the target as "repo-name/a/b", the moved file is renamed to "b" in Artifactory. For flexibility in specifying the upload path, you can include placeholders in the form of {1}, {2} which are replaced by corresponding tokens in the source path that are enclosed in parenthesis. For more details, please refer to Using Placeholders.

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

Command name	delete
Abbreviation	del
Command options	When using the * or ; characters in the delete command options or arguments, make sure to wrap the whole options or arguments string in quotes (") to make sure the * or ; characters are not interpreted as literals.
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
--spec	[Optional] Path to a file spec. For more details, please refer to Using File Specs.
--props	[Optional] A list of Artifactory properties specified as "key=value" pairs separated by a semi-colon (for example, "key1=value1;key2=value2;key3=value3"). Only artifacts with these properties will be deleted.
--build	[Optional] If specified, only artifacts of the specified build are matched. The property format is build-name/build-number. If you do not specify the build number, the artifacts are filtered by the latest build number.
--recursive	[Default: true] If true, artifacts are also deleted from sub-paths under the specified path.
--quiet	[Default: false] If true, the delete confirmation message is skipped.
--dry-run	[Default: false] If true, the command only indicates which artifacts would have been deleted. If false, the command is fully executed and deletes artifacts as specified.
--exclude-patterns	A list of Semicolon-separated exclude patterns. Allows using wildcards as part of the pattern. Unlike the Source path, must not include the repository name at the beginning of the path.
--sort-by	[Optional] A list of semicolon-separated fields to sort by. The fields must be part of the 'items' AQL domain. For more information read the AQL documentation
--sort-order	[Default: asc] The order by which fields in the 'sort-by' option should be sorted. Accepts 'asc' or 'desc'.
--limit	[Optional] The maximum number of items to fetch. Usually used with the 'sort-by' option.
--offset	[Optional] The offset from which to fetch items (i.e. how many items should be skipped). Usually used with the 'sort-by' option.
--fail-no-op	[Default: false] Set to true if you'd like the command to return exit code 2 in case of no files are affected.
--archive-entries	[Optional] If specified, only archive artifacts containing entries matching this pattern are matched. You can use wildcards to specify multiple artifacts.
Command arguments	The command takes one argument
Delete path	Specifies the path in Artifactory of the files that should be deleted in the following format: `[repository name]/[repository path].` You can use wildcards to specify multiple artifacts.

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.

Command name	search
Abbreviation	s
Command options	When using the * or ; characters in the command options or arguments, make sure to wrap the whole options or arguments string in quotes (") to make sure the * or ; characters are not interpreted as literals.
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
--spec	[Optional] Path to a file spec. For more details, please refer to Using File Specs.
--spec-vars	[Optional] List of variables in the form of "key1=value1;key2=value2;..." to be replaced in the File Spec. In the File Spec, the variables should be used as follows: ${key1}.
--props	[Optional] A list of Artifactory properties specified as "key=value" pairs separated by a semi-colon (for example, "key1=value1;key2=value2;key3=value3"). Only artifacts with these properties will be returned.
--build	[Optional] If specified, only artifacts of the specified build are matched. The property format is build-name/build-number. If you do not specify the build number, the artifacts are filtered by the latest build number.
--recursive	[Default: true] Set to false if you do not wish to search artifacts inside sub-folders in Artifactory.
--exclude-patterns	A list of Semicolon-separated exclude patterns. Allows using wildcards as part of the pattern. Unlike the Source path, must not include the repository name at the beginning of the path.
--sort-by	[Optional] A list of semicolon-separated fields to sort by. The fields must be part of the 'items' AQL domain. For more information read the AQL documentation
--sort-order	[Default: asc] The order by which fields in the 'sort-by' option should be sorted. Accepts 'asc' or 'desc'.
--limit	[Optional] The maximum number of items to fetch. Usually used with the 'sort-by' option.
--offset	[Optional] The offset from which to fetch items (i.e. how many items should be skipped). Usually used with the 'sort-by' option.
--fail-no-op	[Default: false] Set to true if you'd like the command to return exit code 2 in case of no files are affected.
--archive-entries	[Optional] If specified, only archive artifacts containing entries matching this pattern are matched. You can use wildcards to specify multiple artifacts.
Command arguments
Search path	Specifies the search path in Artifactory, in the following format: `[repository name]/[repository path].` You can use wildcards to specify multiple artifacts.

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.

Command name	set-props
Abbreviation	sp
Command options	When using the * or ; characters in the command options or arguments, make sure to wrap the whole options or arguments string in quotes (") to make sure the * or ; characters are not interpreted as literals.
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
--props	[Optional] List of properties in the form of "key1=value1;key2=value2,...". Only files with these properties are affected.
--recursive	[Default: true] When false, artifacts inside sub-folders in Artifactory will not be affected.
--build	[Optional] If specified, only artifacts of the specified build are matched. The property format is build-name/build-number. If you do not specify the build number, the artifacts are filtered by the latest build number.
--include-dirs	[Default: false] When true, the properties will also be set on folders (and not just files) in Artifactory.
--exclude-patterns	A list of Semicolon-separated exclude patterns. Allows using wildcards as part of the pattern. Unlike the Source path, must not include the repository name at the beginning of the path.
--sort-by	[Optional] A list of semicolon-separated fields to sort by. The fields must be part of the 'items' AQL domain. For more information read the AQL documentation
--sort-order	[Default: asc] The order by which fields in the 'sort-by' option should be sorted. Accepts 'asc' or 'desc'.
--limit	[Optional] The maximum number of items to fetch. Usually used with the 'sort-by' option.
--offset	[Optional] The offset from which to fetch items (i.e. how many items should be skipped). Usually used with the 'sort-by' option.
--archive-entries	[Optional] If specified, only archive artifacts containing entries matching this pattern are matched. You can use wildcards to specify multiple artifacts.
Command arguments	The command takes two arguments.
Files pattern	Files that match the pattern will be set with the specified properties.
Files properties	The list of properties, in the form of key1=value1;key2=value2,..., to be set on the matching artifacts.

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"

Deleting Properties from Files

This command is used for deleting properties from existing files in Artifactory.

Command name	delete-props
Abbreviation	delp
Command options	When using the * or ; characters in the command options or arguments, make sure to wrap the whole options or arguments string in quotes (") to make sure the * or ; characters are not interpreted as literals.
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
--props	[Optional] List of properties in the form of "key1=value1;key2=value2,...". Only files with these properties are affected.
--recursive	[Default: true] When false, artifacts inside sub-folders in Artifactory will not be affected.
--build	[Optional] If specified, only artifacts of the specified build are matched. The property format is build-name/build-number. If you do not specify the build number, the artifacts are filtered by the latest build number.
--include-dirs	[Default: false] When true, the properties will also be set on folders (and not just files) in Artifactory.
--exclude-patterns	A list of Semicolon-separated exclude patterns. Allows using wildcards as part of the pattern. Unlike the Source path, must not include the repository name at the beginning of the path.
--sort-by	[Optional] A list of semicolon-separated fields to sort by. The fields must be part of the 'items' AQL domain. For more information read the AQL documentation
--sort-order	[Default: asc] The order by which fields in the 'sort-by' option should be sorted. Accepts 'asc' or 'desc'.
--limit	[Optional] The maximum number of items to fetch. Usually used with the 'sort-by' option.
--offset	[Optional] The offset from which to fetch items (i.e. how many items should be skipped). Usually used with the 'sort-by' option.
--archive-entries	[Optional] If specified, only archive artifacts containing entries matching this pattern are matched. You can use wildcards to specify multiple artifacts.
Command arguments	The command takes two arguments.
Files pattern	The properties will be deleted from files that match the pattern.
Files properties	The list of properties, in the form of key1,key2,..., to be deleted from the matching artifacts.

Example

Delete the "status" and "phase" properties from all the zip files in the generic-local repository.

jfrog rt delp "generic-local/*.zip" "status,phase"

Collecting Environment Variables

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

Command name	build-collect-env
Abbreviation	bce
Command options	This command has no options.
Command arguments	The command accepts two arguments.
Build name	Build name.
Build number	Build number.

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, including project tracked issues, from the local .git directory.

For more details, please refer to Build Integration.

Command name	build-add-git
Abbreviation	bag
Command options
--config	[Optional] Path to a configuration file, used for collecting tracked project issues and adding them to the build-info. Read more about how to configure the file in Information from git.
Command arguments	The command accepts three arguments.
Build name	Build name.
Build number	Build number.
.git path	Optional - Path to a directory containing the .git directory. If not specific, the .git directory is assumed to be in the current directory or in one of the parent directories.

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.

Command name	build-add-dependencies
Abbreviation	bad
Command options	When using the * or ; characters in the command options or arguments, make sure to wrap the whole options or arguments string in quotes (") to make sure the * or ; characters are not interpreted as literals.
--spec	[Optional] Path to a File Spec.
--spec-vars	[Optional] List of variables in the form of "key1=value1;key2=value2;..." to be replaced in the File Spec. In the File Spec, the variables should be used as follows: ${key1}.
--recursive	[Default: true] When false, artifacts inside sub-folders in Artifactory will not be affected.
--regexp	[Optional: false] [Default: false] Set to true to use a regular expression instead of wildcards expression to collect files to be added to the build info.
--dry-run	[Default: false] Set to true to only get a summery of the dependencies that will be added to the build info.
--exclude-patterns	A list of Semicolon-separated exclude patterns. Allows using wildcards or a regular expression according to the value of the 'regexp' option.
Command arguments	The command takes threee arguments.
Build name	The build name to add the dependencies to
Build number	The build number to add the dependencies to
Pattern	Specifies the local file system path to dependencies which should be added to the build info. You can specify multiple dependencies by using wildcards or a regular expression as designated by the --regexp command option. If you have specified that you are using regular expressions, then the first one used in the argument must be enclosed in parenthesis.

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.

Command name	build-publish
Abbreviation	bp
Command options
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
--build-url	[Optional] Can be used for setting the CI server build URL in the build-info.
--env-include	[Default: *] List of patterns in the form of "value1;value2;..." Only environment variables that match those patterns will be included in the build info.
--env-exclude	[Default: password;secret;key] List of case insensitive patterns in the form of "value1;value2;..." environment variables match those patterns will be excluded.
-dry-run	[Default: false] Set to true to disable communication with Artifactory.
Command arguments	The command accepts two arguments.
Build name	Build name to be published.
Build number	Build number to be published.

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.

Command name	build-promote
Abbreviation	bpr
Command options
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
--status	[Optional] Build promotion status.
--comment	[Optional] Build promotion comment.
--source-repo	[Optional] Build promotion source repository.
--include-dependencies	[Default: false] If set to true, the build dependencies are also promoted.
--copy	[Default: false] If set true, the build artifacts and dependencies are copied to the target repository, otherwise they are moved.
--dry-run	[Default: false] If true, promotion is only simulated. The build is not promoted.
Command arguments	The command accepts three arguments.
Build name	Build name to be promoted.
Build number	Build number to be promoted.
Target repository	Build promotion target repository.

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.

Command name	build-distribute
Abbreviation	bd
Command options
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
--source-repos	[Optional] List of local repositories in the form of "repo1,repo2,..." from which build artifacts should be deployed.
--passphrase	[Optional] If specified, Artifactory will GPG sign the build deployed to Bintray and apply the specified passphrase.
--publish	[Default: true] If true, builds are published when deployed to Bintray.
--override	[Default: false] If true, Artifactory overwrites builds already existing in the target path in Bintray.
--async	[Default: false] If true, the build will be distributed asynchronously.
--dry-run	[Default: false] If true, distribution is only simulated. No files are actually moved.
Command arguments	The command accepts two arguments.
Build name	Build name to be distributed.
Build number	Build number to be distributed.
Target repository	Build distribution target repository.

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.

Command name	build-scan
Abbreviation	bs
Command options
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
--fail	[Default: true] When set to true, the command returns exit code 3 if a 'Fail Build' rule is matched by Xray. Set to false if you do not wish the command to return exit code 3 in such case, and an exit code 0 will be returned.
Command arguments	The command accepts two arguments.
Build name	Build name to be scanned.
Build number	Build number to be scanned.

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.

Command name	build-clean
Abbreviation	bc
Command options	The command has no options.
Command arguments	The command accepts two arguments.
Build name	Build name.
Build number	Build number.

Example

 jfrog rt bc my-build-name 18

Build Integration - Discarding Old Builds from Artifactory

This command is used to discard builds previously published to Artifactory using the build-publish command.

For more details, please refer to Build Integration.

Command name	build-discard
Abbreviation	bdi
Command options
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
--max-days	[Optional] The maximum number of days to keep builds in Artifactory.
--max-builds	[Optional] The maximum number of builds to store in Artifactory.
--exclude-builds	[Optional] List of build numbers in the form of "value1,value2,...", that should not be removed from Artifactory.
--delete-artifacts	[Default: false] If set to true, automatically removes build artifacts stored in Artifactory.
--async	[Default: false] If set to true, build discard will run asynchronously and will not wait for response.
Command arguments	The command accepts one argument.
Build name	Build name.

Example

Example 1

Discard the oldest build numbers of build my-build-name from Artifactory, leaving only the 10 most recent builds.

 jfrog rt bdi my-build-name --max-builds=10

Example 2

Discard the oldest build numbers of build my-build-name from Artifactory, leaving only builds published during the last 7 days.

 jfrog rt bdi my-build-name --max-days=7

Example 3

Discard the oldest build numbers of build my-build-name from Artifactory, leaving only builds published during the last 7 days. b20 and b21 will not be discarded.

 jfrog rt bdi my-build-name --max-days=7 --exclude-builds="b20,b21"

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.

Command name	git-lfs-clean
Abbreviation	glc
Command options
--refs	[Default: refs/remotes/*] List of Git references in the form of "ref1,ref2,..." which should be preserved.
--repo	[Optional] Local Git LFS repository in Artifactory which should be cleaned. If omitted, the repository is detected from the Git repository.
--quiet	[Default: false] Set to true to skip the delete confirmation message.
--apikey	[Optional] The default API key to be used for all other commands.
--dry-run	[Default: false] If true, cleanup is only simulated. No files are actually deleted.
Command arguments	If no arguments are passed in, the command assumes the .git repository is located at current directory.
path to .git	Path to the directory which includes the .git directory.

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.

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

Overview

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.

Many of JFrog CLI's commands accept two optional command options: --build-name and --build-number. When these options are added, JFrog CLI collects and records the build info locally for these commands.
When running multiple commands using the same build and build number, JFrog CLI aggregates the collected build info into one build.
The recorded build-info can be later published to Artifactory using the build-publish command.

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.

Collecting 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

Collecting 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

Collecting 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

Collecting Information from Git

The build-add-git (bag) command collects the Git revision and URL from the local .git directory and adds it to the build-info. It can also collect the list of tracked project issues (for example, issues stored in JIRA or other bug tracking systems) and add them to the build-info. The issues are collected by command by reading the git commit messages. It matches each commit message with a pre-configured regular expression, and retrieves the issue ID and issue summary. The information required for collecting the issues is retrieved from a yaml configuration file provided to the command.

This is the configuration file structure.

version: 1
issues:
  serverID: my-artifactory-server
  trackerName: JIRA
  regexp: (.+-[0-9]+)\s-\s(.+)
  keyGroupIndex: 1
  summaryGroupIndex: 2
  trackerUrl: http://my-jira.com/issues
  aggregate: true
  aggregationStatus: RELEASED

Configuration file properties

Property name	Description
Version	The schema version is intended for internal use. Do not change!
serverID	Artifactory server ID configured by the jfrog rt config command. The command uses this server for fetching details about previous published builds.
trackerName	The name (type) of the issue tracking system. For example, JIRA. This property can take any value.
regexp	A regular expression used for matching the git commit messages. The expression should include two capturing groups - for the issue key (ID) and the issue summary. In the example above, the regular expression matches the commit messages as displayed in the following example: HAP-1007 - This is a sample issue
keyGroupIndex	The capturing group index in the regular expression used for retrieving the issue key. In the example above, setting the index to "1" retrieves HAP-1007 from this commit message: HAP-1007 - This is a sample issue
summaryGroupIndex	The capturing group index in the regular expression for retrieving the issue summary. In the example above, setting the index to "2" retrieves the sample issue from this commit message: HAP-1007 - This is a sample issue
trackerUrl	The issue tracking URL. This value is used for constructing a direct link to the issues in the Artifactory build UI.
aggregate	Set to true, if you wish all builds to include issues from previous builds.
aggregationStatus	If aggregate is set to true, this property indicates how far in time should the issues be aggregated. In the above example, issues will be aggregated from previous builds, until a build with a RELEASE status is found. Build statuses are set when a build is promoted using the jfrog rt build-promote command.

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

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:

Create the build configuration file.
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

Downloading the Extractor JARs

For integrating with Maven and Gradle, JFrog CLI uses the build-info-extractor jars files. These jar files are downloaded by JFrog CLI from jcenter the first time they are needed.

If you're using JFrog CLI on a machine which has no access to the internet, you can configure JFrog CLI to download these jar files from an Artifactory instance. Here's how to configure Artifactory and JFrog CLI to download the jars files.

Create a remote Maven repository in Artifactory and name it jcenter. When creating the repository, configure it to proxy https://jcenter.bintray.com
Make sure that this Artifactory server is known to JFrog CLI, using the jfrog rt c show command. If not, configure it using the jfrog rt c command.
Set the JFROG_CLI_JCENTER_REMOTE_SERVER environment variable with the server ID of the Artifactory server you configured.
If you prefer to use a remote repository with a name different than jcenter, you can configure this name as the value of the JFROG_CLI_JCENTER_REMOTE_REPO environment variable.

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

Deploying Maven Artifacts

Artifacts deployment to Artifactory is triggered by the install phase (and not the deploy phase).

To disable artifacts deployment, add -Dartifactory.publish.artifacts=false to the list of goals and options.

For example: "clean install -Dartifactory.publish.artifacts=false"

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

Notice that the above commands accept two options: a build name and a build number. When adding a build name and a build number to the build commands, JFrog CLI stores locally the information about the build. You can then publish this build-info to Artifactory. read more about publishing builds builds to Artifactory in the Collecting Build Information section.

Running Builds with MSBuild

JFrog CLI includes integration with MSBuild and Artifactory, allowing you to resolve dependencies and deploy build artifacts from and to Artifactory, while collecting build-info and storing it in Artifactory. This is done by having JFrog CLI in your search path and adding JFrog CLI commands to the MSBuild csproj file.

For detailed instructions, please refer to our MSBuild Project Example on GitHub.

Building Docker Images

JFrog CLI provides full support for publishing docker images to Artifactory using the docker client running on the same machine. This allows you to to collect build-info for your docker build and then publish it to Artifactory.

To build and push your docker images to Artifactory, follow these steps:

Make sure Artifactory can be used as docker registry. Please refer to Getting Started with Docker and Artifactory in the JFrog Artifactory User Guide.
To ensure that the docker client and your Artifactory docker registry are correctly configured to work together, run the following code snippet.
```
docker pull hello-world
docker tag hello-world:latest <artifactoryDockerRegistry>/hello-world:latest
docker login <artifactoryDockerRegistry>
docker push <artifactoryDockerRegistry>/hello-world:latest
```
If everything is configured correctly, pushing any image including the hello-world image should be successfully uploaded to Artifactory.

docker commands with the CLI

When running the docker-pull and docker-push commands, the CLI will first attempt to login to the docker registry.
In case of a login failure, the command will not be executed.

Pulling Docker Images

Running docker-pull command allows pulling docker images from Artifactory, while collecting the build-info and storing it locally, so that it can be later published to Artifactory, using the build-publish command.

The following table lists the command arguments and flags:

Command-name	docker-pull
Abbreviation	dpl
Command options
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
--build-name	[Optional] Build name. For more details, please refer to Build Integration.
--build-number	[Optional] Build number. For more details, please refer to Build Integration.
Command argument
Image tag	The docker image tag to pull.
Source repository	Source repository in Artifactory.

Examples

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

You can then publish the build-info collected by the docker-pull command to Artifactory using the build-publish command.

Pushing Docker Images

After building your image using the docker client, the docker-push command pushes the image layers to Artifactory, while collecting the build-info and storing it locally, so that it can be later published to Artifactory, using the build-publish command.

The following table lists the command arguments and flags:

Command-name	docker-push
Abbreviation	dp
Command options
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
--build-name	[Optional] Build name. For more details, please refer to Build Integration.
--build-number	[Optional] Build number. For more details, please refer to Build Integration.
--threads	[Default: 3] Number of working threads.
Command argument
Image tag	The docker image tag to push.
Target repository	Target repository in Artifactory.

Examples

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

You can then publish the build-info collected by the docker-push command to Artifactory using the build-publish command.

Building Npm Packages

JFrog CLI provides full support for building npm packages using the npm client. This allows you to resolve npm dependencies, and publish your npm packages from and to Artifactory, while collecting build-info and storing it in Artifactory.

Follow these guidelines when building npm packages:

Working with Artifactory repositories: You can download npm packages from any npm repository type - local, remote or virtual, but you can only publish to a local or virtual Artifactory repository, containing local repositories. To publish to a virtual repository, you first need to set a default local repository. For more details, please refer to .

Renaming existing prepublish and postpublish scripts in the package.json file: When the npm-publish command runs, JFrog CLI runs the pack command in the background, and not the standard publish command. If your npm package includes the prepublish or postpublish scripts, rename them to prepack and postpack, respectively.

To build an npm package with Artifactory, take the following actions:

Create an npm repository in Artifactory.
Run the Install command to fetch the npm packages.
Publish the npm package to the designated Artifactory repository. JFrog CLI provides additional build commands, please refer to the section.

Requirements

Npm client version 5.4.0 and above.

Artifactory version 5.5.2 and above.

Installing Npm Packages

The npm-install command fetches the npm dependencies from the npm repositories.

The following table lists the command arguments and flags:

Command-name	npm-install
Abbreviation	npmi
Command options
--npm-args	[Optional] A list of npm arguments and options in the form of "--arg1=value1 --arg2=value2".
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
--build-name	[Optional] Build name. For more details, please refer to Build Integration.
--build-number	[Optional] Build number. For more details, please refer to Build Integration.
Command argument
Repository name	The source npm repository. Can be local, remote, or a virtual npm repository.

Examples

Example 1

The following example installs the dependencies and records them locally as part of build my-build-name/1. The build-info can later be published to Artifactory using the build-publish command.

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

Example 2

The following example installs the dependencies:

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

Publishing the Npm Packages into Artifactory

The npm-publish command packs and deploys the npm package to the designated npm repository.

If your npm package includes the prepublish or postpublish scripts, please refer to the guidelines above.

The following table lists the command arguments and flags:

Command-name	npm-publish
Abbreviation	npmp
Command options
--npm-args	[Optional] A list of npm arguments and options in the form of "--arg1=value1 --arg2=value2"
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
--build-name	[Optional] Build name. For more details, please refer to Build Integration.
--build-number	[Optional] Build number. For more details, please refer to Build Integration.
Command argument
Repository name	The target npm repository. Can be local, or a virtual npm repository containing local repositories.

Example

To pack and publish the npm package and also record it locally as part of build my-build-name/1, run the following command. The build-info can later be published to Artifactory using the build-publish command:

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

Building Go Packages

General

JFrog CLI provides full support for building Go packages using the Go client. This allows you to resolve Go dependencies from and publish your Go packages to Artifactory, while collecting build-info and storing it in Artifactory.

Build Process

When building your go project using the jfrog rt go build command, JFrog CLI does the following:
1. Downloads the dependencies from Artifactory.
2. Dependencies which are missing in Artifactory are downloaded from the source control and then published to Artifactory.
3. Builds the project.

Requirements

JFrog CLI client version 1.20.0 and above.

Artifactory version 6.2.0 and above.

Go client version 1.11.0 and above.

Using JFrog CLI vs. the Native Go Client

The native go client can be used to build packages with Artifactory. To set the go client to use Artifactory, the GOPROXY environment variable needs to be set and include the Artifactory instance details as follows:

<protocol>://<username>:<password>@<artifactory domain>/api/go/<go repository>

It is recommended to use a virtual go repository, which includes a local repository, set as the default deployment repository. The virtual repository can include one or more remote repositories, to proxy remote sources such as GoCenter or github.

Some go packages however have not yet been converted to use go-modules and therefore cannot be proxied by Artifactory.
JFrog CLI provides a solution to this issue. It does this by attempting to download packages from Artifactory first and fall back to source control repositories if the packages cannot be fetched from Artifactory. JFrog CLI will publish these missing packages to Artifactory, so that they are available for the next builds.

Example project

To help you get started, you can use this sample project on GitHub.

Running go commands

The go command triggers the go client.

The following table lists the command arguments and flags:

Command-name	go
Abbreviation	go
Command options
--no-registry	[Default false] Set to true if you don't want to use Artifactory as your proxy.
--recursive-tidy	[Default: false] Set to true if you want to create full mod files for all the dependencies and publish them to Artifactory. Read more about this option here.
--recursive-tidy-overwrite	[Default: false] Can be used only with the --recursive-tidy option set to true. If set to true, the dependencies mod files are tidies, before publishing them to Artifactory. Read more about this option here.
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
--build-name	[Optional] Build name. For more details, please refer to Build Integration.
--build-number	[Optional] Build number. For more details, please refer to Build Integration.
Command argument
Go command	The Go command to run
Repository	The target Go repository. Can be local or a virtual Go repository. Important: Since this command also deploys Go packages that are missing in Artifactory, If the repository used is Virtual Repository, it must include a Default Deployment Repository. Read more it here.

Examples

Example 1

The following example runs Go build command. The dependencies resolved from Artifactory via the go-virtual repository.

jfrog rt go build go-virtual

Example 2

The following example runs Go build command, while recording the build-info locally under build name my-build and build number 1. The build-info can later be published to Artifactory using the build-publish command:

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

Publishing Go Packages to Artifactory

The go-publish command packs and deploys the Go package to the designated Go repository in Artifactory.

The following table lists the command arguments and flags:

Command-name	go-publish
Abbreviation	gp
Command options
--self	[Default: true] Set false to skip publishing the project package zip file to Artifactory. The default set to true to publish the project itself to Artifactory.
--deps	[Optional] List of project dependencies in the form of "dep1-name:version,dep2-name:version..." to be published to Artifactory. Use "ALL" to publish all dependencies. By default no dependencies are being published.
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
--build-name	[Optional] Build name. For more details, please refer to Build Integration.
--build-number	[Optional] Build number. For more details, please refer to Build Integration.
Command argument
Target repository	The target Go repository. Can be local or a virtual Go repository, with a Default Deployment Repository.
Version	The version of the Go project that is being published

Examples

Example 1

To pack and publish the Go package and also record the build-info as part of build my-build-name/1, run the following command. The build-info can later be published to Artifactory using the build-publish command:

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

Example 2

To pack and publish the Go package, the entire project dependencies and also record the build-info locally as part of build my-build-name/1, run the following command. The build-info can later be published to Artifactory using the build-publish command:

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

Example 3

To pack and publish the Go package, selected dependencies and also record the build-info locally as part of build my-build-name/1, run the following command. The build-info can later be published to Artifactory using the build-publish command:

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

Populating Artifactory with Go Packages

This command recursively discovers all project dependencies, both direct and indirect, and publishes them to Artifactory.

Command-name	go-recursive-publish
Abbreviation	grp
Command options
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
Command argument
Target repository	Target repository in Artifactory. Publish the dependencies to this repository.

Example 1

jfrog rt grp go-local

Building Nuget Packages

JFrog CLI provides full support for restoring Nuget packages using the Nuget client. This allows you to resolve Nuget dependencies from and publish your Nuget packages to Artifactory, while collecting build-info and storing it in Artifactory.

Nuget dependencies resolution is supported by the jfrog rt nuget command.

To publish your nuget packages to Artifactory, use the jfrog rt upload command.

Running Nuget commands

The nuget command runs the nuget client.

The following table lists the command arguments and flags:

Command-name	nuget
Abbreviation
Command options
--nuget-args	[Optional] A list of NuGet arguments and options in the form of "arg1 arg2 arg3..."
--solution-root	[Default: .] Path to the root directory of the solution. If the directory includes more than one sln files, then the first argument passed in the --nuget-args option should be the name (not the path) of the sln file.
--server-id	[Optional] Artifactory server ID configured using the config command. If not specified, the default configured Artifactory server is used.
--build-name	[Optional] Build name. For more details, please refer to Build Integration.
--build-number	[Optional] Build number. For more details, please refer to Build Integration.
Command argument
Nuget command	The Nuget command to run. For example, restore.
Source repository name	The source NuGet repository. Can be a local, remote or virtual NuGet repository.`

Example 1

Run nuget restore for the solution at the current directory, while resolving the nuget dependencies from the nuget-virtual Artifactory repository.

jfrog rt nuget restore nuget-virtual

Example 2

Run nuget restore for the solution at the current directory, while resolving the nuget dependencies from the nuget-virtual Artifactory repository.

In addition, record the build-info as part of build my-build-name/1, run the following command. The build-info can later be published to Artifactory using the build-publish command:

jfrog rt nuget restore nuget-virtual --build-name=my-build-name --build-number=1

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]"],
            "archiveEntries": "[Optional]",
            "build": "[Optional]",
            "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]"],
            "build": "[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]"],
            "archiveEntries": "[Optional]",
            "build": "[Optional]",
            "sortBy" : ["[Optional]"],
            "sortOrder": "[Optional, Default: 'asc']",
            "limit": [Optional],
            "offset": [Optional]
        }
    ]
}

Examples

The following examples can help you get started using File Specs.

Running on Windows?

To use the following examples on Windows, replace all forward slashes with two back-slashes.

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 located under the all-my-frogs directory in the my-local-repo repository to the froggy/all-my-frogs directory. Download only files which are artifacts of build number 5 of build my-build.

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

Example 3:

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": "froggy/"
    }
  ]
}

Example 4: Upload

All zip files located under the resources directory to the zip folder, under the all-my-frogs repository.
AND
All TGZ files located under the resources directory to the tgz folder, under the all-my-frogs repository.
Tag all zip files with type = zip and status = ready.
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 5: 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 6: 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 7: 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 8: 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.

Page tree

CLI for JFrog Artifactory

Overview

Syntax

command-name

global-options

command-options

arguments

Environment Variables

Variable Name

JFROG_CLI_MIN_CHECKSUM_DEPLOY_SIZE_KB

JFROG_CLI_JCENTER_REMOTE_SERVER

JFROG_CLI_JCENTER_REMOTE_REPO

Authentication

Authenticating with Login Credentials

Authenticating with an API key

Authenticating with an Access Token

Authenticating with RSA Keys

Using Self-signed SSL Certificates

General Commands

Configuration

Command name

Abbreviation

Command options

Command arguments

Examples

Using a Predefined Artifactory Server

Command name

Abbreviation

Command options

Command arguments

Examples

Verifying Artifactory is Accessible

Command name

Abbreviation

Command options

Command arguments

Examples

Uploading Files

Command name

Abbreviation

Command options

Command arguments

Examples

Downloading Files

Command name

Abbreviation

Command options

Command arguments

Examples

Copying Files

Command name

Abbreviation

Command options

Command arguments

Examples

Moving Files

Command name

Abbreviation

Command options

Command arguments

Examples

Deleting Files

Command name

Abbreviation

Command options

Command arguments

Examples

Searching Files

Command name

Abbreviation

Command options

Command arguments

Examples

Setting Properties on Files

Command name

Abbreviation

Command options

Command arguments

Example