diff --git a/.github/workflows/pythonTests.yml b/.github/workflows/pythonTests.yml index d9aed44fa..fd937028b 100644 --- a/.github/workflows/pythonTests.yml +++ b/.github/workflows/pythonTests.yml @@ -19,7 +19,7 @@ jobs: strategy: fail-fast: false matrix: - suite: [ pip, pipenv ] + suite: [ pip, pipenv, poetry ] os: [ ubuntu, windows, macos ] runs-on: ${{ matrix.os }}-latest steps: @@ -35,6 +35,9 @@ jobs: - name: Setup Pipenv if: ${{ matrix.suite == 'pipenv' }} run: python -m pip install pipenv + - name: Setup Poetry + if: ${{ matrix.suite == 'poetry' }} + run: python -m pip install poetry - name: Checkout code uses: actions/checkout@v3 with: diff --git a/.github/workflows/scriptTests.yml b/.github/workflows/scriptTests.yml index 16856b439..27ce99e5e 100644 --- a/.github/workflows/scriptTests.yml +++ b/.github/workflows/scriptTests.yml @@ -78,7 +78,7 @@ jobs: - name: "Get latest release" id: latest-release run: | - export LATEST_RELEASE=`curl https://api.github.com/repos/jfrog/jfrog-cli/releases/latest -s --retry 10 | jq .name -r | cut -c 2-` + export LATEST_RELEASE=`curl https://api.github.com/repos/jfrog/jfrog-cli/releases/latest -s | jq .name -r | cut -c 2-` echo "LATEST_RELEASE=$LATEST_RELEASE" >> "$GITHUB_OUTPUT" shell: bash diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 30d6a1ede..d9bd3949d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -104,6 +104,7 @@ The available test types are: | `-test.go` | Go tests | | `-test.pip` | Pip tests | | `-test.pipenv` | Pipenv tests | +| `-test.poetry` | Poetry tests | | `-test.nuget` | Nuget tests | | `-test.plugins` | Plugins tests | | `-test.distribution` | Distribution tests | diff --git a/Jenkinsfile b/Jenkinsfile index 4dd0944af..c5f2e9671 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -46,18 +46,6 @@ node("docker") { } } - state('synchronize branches') { - if ("$EXECUTION_MODE".toString().equals("Build CLI")) { - masterBranch = 'v2' - devBranch = 'dev' - if (BRANCH?.trim() == 'v1') { - masterBranch = 'v1' - devBranch = 'dev-v1' - } - synchronizeBranches(masterBranch, devBranch) - } - } - stage('install npm') { installNpm(nodeVersion) } @@ -160,28 +148,6 @@ def runRelease(architectures) { } } -def synchronizeBranches(masterBranch, devBranch) { - dir("$cliWorkspace/$repo") { - releaseTag = "v$RELEASE_VERSION" - withCredentials([string(credentialsId: 'ecosystem-github-automation', variable: 'GITHUB_ACCESS_TOKEN')]) { - stage("Merge to $masterBranch") { - sh """#!/bin/bash - git merge origin/$devBranch --no-edit - git push "https://$GITHUB_ACCESS_TOKEN@github.com/jfrog/jfrog-cli.git" - """ - } - stage("Merge to $devBranch") { - sh """#!/bin/bash - git checkout $devBranch - git merge origin/$masterBranch --no-edit - git push "https://$GITHUB_ACCESS_TOKEN@github.com/jfrog/jfrog-cli.git" - git checkout $masterBranch - """ - } - } - } -} - def createTag() { stage('Create a tag and a GitHub release') { dir("$jfrogCliRepoDir") { diff --git a/build/npm/v2-jf/package-lock.json b/build/npm/v2-jf/package-lock.json index 3c103cfd5..6304b51f7 100644 --- a/build/npm/v2-jf/package-lock.json +++ b/build/npm/v2-jf/package-lock.json @@ -1,5 +1,5 @@ { "name": "jfrog-cli-v2-jf", - "version": "2.52.0", + "version": "2.51.1", "lockfileVersion": 1 } diff --git a/build/npm/v2-jf/package.json b/build/npm/v2-jf/package.json index d8f368690..69927d968 100644 --- a/build/npm/v2-jf/package.json +++ b/build/npm/v2-jf/package.json @@ -1,6 +1,6 @@ { "name": "jfrog-cli-v2-jf", - "version": "2.52.0", + "version": "2.51.1", "description": "🐸 Command-line interface for JFrog Artifactory, Xray, Distribution, Pipelines and Mission Control 🐸", "homepage": "https://github.com/jfrog/jfrog-cli", "preferGlobal": true, diff --git a/build/npm/v2/package-lock.json b/build/npm/v2/package-lock.json index 86e9c08b7..141be0880 100644 --- a/build/npm/v2/package-lock.json +++ b/build/npm/v2/package-lock.json @@ -1,5 +1,5 @@ { "name": "jfrog-cli-v2", - "version": "2.52.0", + "version": "2.51.1", "lockfileVersion": 2 } diff --git a/build/npm/v2/package.json b/build/npm/v2/package.json index 46474b837..d82b23956 100644 --- a/build/npm/v2/package.json +++ b/build/npm/v2/package.json @@ -1,6 +1,6 @@ { "name": "jfrog-cli-v2", - "version": "2.52.0", + "version": "2.51.1", "description": "🐸 Command-line interface for JFrog Artifactory, Xray, Distribution, Pipelines and Mission Control 🐸", "homepage": "https://github.com/jfrog/jfrog-cli", "preferGlobal": true, diff --git a/distribution_test.go b/distribution_test.go index 5c5d12869..62cbea526 100644 --- a/distribution_test.go +++ b/distribution_test.go @@ -445,7 +445,7 @@ func TestUpdateBundleProps(t *testing.T) { cleanDistributionTest(t) } -func TestBundlePathMappingFromPatternAndTarget(t *testing.T) { +func TestBundlePathMapping(t *testing.T) { initDistributionTest(t) // Upload files @@ -465,28 +465,6 @@ func TestBundlePathMappingFromPatternAndTarget(t *testing.T) { cleanDistributionTest(t) } -func TestBundlePathMappingFromPatternAndTargetUsingSpec(t *testing.T) { - initDistributionTest(t) - - // Upload files - specFile, err := tests.CreateSpec(tests.DistributionUploadSpecB) - assert.NoError(t, err) - runRt(t, "u", "--spec="+specFile) - - // Create and distribute release bundle with path mapping from /data/ to /target/ - spec, err := tests.CreateSpec(tests.DistributionCreateWithPatternAndTarget) - assert.NoError(t, err) - runDs(t, "rbc", tests.BundleName, bundleVersion, "--sign", "--spec="+spec) - runDs(t, "rbd", tests.BundleName, bundleVersion, "--site=*", "--sync") - - // Validate files are distributed to the target mapping - spec, err = tests.CreateSpec(tests.DistributionMappingDownload) - assert.NoError(t, err) - inttestutils.VerifyExistInArtifactory(tests.GetBundleMappingExpected(), spec, serverDetails, t) - - cleanDistributionTest(t) -} - func TestBundlePathMappingUsingSpec(t *testing.T) { initDistributionTest(t) diff --git a/documentation/CLI-for-JFrog-Artifactory.md b/documentation/CLI-for-JFrog-Artifactory.md index 4be56f28c..41b473330 100644 --- a/documentation/CLI-for-JFrog-Artifactory.md +++ b/documentation/CLI-for-JFrog-Artifactory.md @@ -1 +1,3054 @@ -The documentation for JFrog CLI has been relocated to [this](https://docs.jfrog-applications.jfrog.io/jfrog-applications/jfrog-cli) website. \ No newline at end of file +# JFrog CLI : CLI for JFrog Artifactory + +## Overview + +This page describes how to use JFrog CLI with JFrog Artifactory. + +Read more about JFrog CLI [here](https://jfrog.com/help/r/jfrog-cli/environment-variables). + +## 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_RELEASES_REPO** | Configured Artifactory repository name from which to download the jar needed by the mvn/gradle command.
This environment variable's value format should be `/`.
The repository should proxy https://releases.jfrog.io.
This environment variable is used by the 'jf mvn' and 'jf gradle' commands, and also by the 'jf audit' command, when used for maven or gradle projects. | +| **JFROG_CLI_DEPENDENCIES_DIR** | \[Default: $JFROG_CLI_HOME_DIR/dependencies\]

Defines the directory to which JFrog CLI's internal dependencies are downloaded. | +| **JFROG_CLI_REPORT_USAGE** | \[Default: true\]

Set to false to block JFrog CLI from sending usage statistics to Artifactory. | +| **JFROG_CLI_SERVER_ID** | Server ID configured using the config command, unless sent as a command argument or option. | +| **JFROG_CLI_BUILD_NAME** | Build name to be used by commands which expect a build name, unless sent as a command argument or option. | +| **JFROG_CLI_BUILD_NUMBER** | Build number to be used by commands which expect a build number, unless sent as a command argument or option. | +| **JFROG_CLI_BUILD_PROJECT** | JFrog project key to be used by commands which expect build name and build number. Determines the project of the published build. | +| **JFROG_CLI_BUILD_URL** | Sets the CI server build URL in the build-info. The "jf rt build-publish" command uses the value of this environment variable, unless the --build-url command option is sent. | +| **JFROG_CLI_ENV_EXCLUDE** | \[Default: \*password\*;\*secret\*;\*key\*;\*token\*\]

List of case insensitive patterns in the form of "value1;value2;...". Environment variables match those patterns will be excluded. This environment variable is used by the "jf rt build-publish" command, in case the --env-exclude command option is not sent. | +| **JFROG_CLI_TRANSITIVE\_DOWNLOAD\_EXPERIMENTAL** | \[Default: false\]

Used by the "jf rt download" command. Set to true to download artifacts also from remote repositories. This feature is experimental and available on Artifactory version 7.17.0 or higher.` | + +--- +**Note** +> Read about additional environment variables at the [Welcome to JFrog CLI](https://jfrog.com/help/r/jfrog-cli/environment-variables) page. +--- + + +## Authentication + +When used with Artifactory, JFrog CLI offers several means of authentication: JFrog CLI does not support accessing Artifactory without authentication. + +### Authenticating with Username and Password / API Key + +To authenticate yourself using your JFrog login credentials, either configure your credentials once using the **jf c add** command or provide the following option to each command. + +| Command option | Description | +|----------------|-----------------------------------------------------------------------| +| --url | JFrog Artifactory API endpoint URL. It usually ends with /artifactory | +| --user | JFrog username | +| --password | JFrog password or API key | + +For enhanced security, when JFrog CLI is configured to use a username and password / API key, it automatically generates an access token to authenticate with Artifactory. The generated access token is valid for one hour only. JFrog CLI automatically refreshed the token before it expires. The **jfrog c add** command allows disabling this functionality. This feature is currently not supported by commands which use external tools or package managers or work with JFrog Distribution. + +### Authenticating with an Access Token + +To authenticate yourself using an Artifactory Access Token, either configure your Access Token once using the **jf c add** command or provide the following option to each command. + +| Command option | Description | +|----------------|-----------------------------------------------------------------------| +| --url | JFrog Artifactory API endpoint URL. It usually ends with /artifactory | +| --access-token | JFrog access token | + +### Authenticating with RSA Keys + +--- +**Note** +> Currently, authentication with RSA keys is not supported when working with external package managers and build tools (Maven, Gradle, Npm, Docker, Go and NuGet) or with the cUrl integration. +--- + +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](https://jfrog.com/help/r/jfrog-platform-administration-Documentation/Managing-Ssh-Keys). +* 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 **jfrog c add** command. + + --- + **Warning**

+ **Don't include your Artifactory context URL** + + > Make sure that the \[host\] component of the URL only includes the hostname 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 **jfrog c add** command. + +### Authenticating using Client Certificates (mTLS) + +From Artifactory release 7.38.4, you can authenticate users using a client certificate ([mTLS](https://en.wikipedia.org/wiki/Mutual_authentication#mTLS)). To do so will require a reverse proxy and some setup on the front reverse proxy (Nginx). Read about how to set this up [here](https://jfrog.com/help/r/jfrog-artifactory-documentation/Http-Settings). + +To authenticate with the proxy using a client certificate, either configure your certificate once using the **jf c add** command or use the --`client-cert-path` and`--client-cert-ket-path` command options with each command. + +--- +**Note** +> Authentication using client certificates (mTLS) is not supported by commands which integrate with package managers. +--- + + +Not Using a Public CA (Certificate Authority)? + +This section is relevant for you if you're not using a public CA (Certificate Authority) to issue the SSL certificate used to connect to your Artifactory domain. You may not be using a public CA either because you're using self-signed certificates or you're running your own PKI services in-house (often by using a Microsoft CA). + +In this case, you'll need to make those certificates available for JFrog CLI, by placing them inside the **security/certs** directory, which is under JFrog CLI's home directory. By default, the home directory is **~/.jfrog**, but it can be also set using the **JFROG_CLI_HOME_DIR** environment variable. + +**Note** +1. The supported certificate format is PEM. +2. Some commands support the **--insecure-tls** option, which skips the TLS certificates verification. +3. Before version 1.37.0, JFrog CLI expected the certificates to be located directly under the **security** directory. JFrog CLI will automatically move the certificates to the new directory when installing version 1.37.0 or above. Downgrading back to an older version requires replacing the configuration directory manually. You'll find a backup if the old configuration under **.jfrog/backup** + + +## 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 `jf rt upload` command should be executed with the `--symlinks` option set to true. + +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 `jf rt download` command. + +* * * + +## Using Placeholders + +The JFrog CLI offers enormous flexibility in how you **download, upload**, **copy**, or **move** files through the use of wildcard or regular expressions with placeholders. + +Any wildcard enclosed in parentheses 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: Upload all files to the target repository** + +For each .tgz file in the source directory, create a corresponding directory with the same name in the target repository and upload it there. For example, a file named **froggy.tgz** should be uploaded to **my-local-rep/froggy**. **froggy** will be created in a folder in Artifactory). +``` +jf rt u "(*).tgz" my-local-repo/{1}/ --recursive=false +``` + +##### **Example 2: Upload all files sharing the same prefix to the target repository** + +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**. +``` +jf rt u "(frog*)" my-local-repo/frogfiles/{1}-up --recursive=false +``` + +##### **Example 3: Upload all files to corresponding directories according to extension type** + +Upload all files in the current directory to the **my-local-repo** repository and place them in directories that match their file extensions. +``` +jf rt u "(*).(*)" my-local-repo/{2}/{1}.{2} --recursive=false +``` + +##### **Example 4: Copy all zip files to target repository and append with an extension.** + +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". +``` +jf rt cp "source-frog-repo/rabbit/(*.zip)" target-frog-repo/rabbit/{1}.cp +``` + +## General Commands + +The following sections describe the commands available in the JFrog CLI for use with Artifactory. + +### Verifying Artifactory is Accessible + +This command can be used to verify that Artifactory is accessible by sending an applicative ping to Artifactory. + +| | | +|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------| +| Command name | rt ping | +| Abbreviation | rt p | +| | | +| Command options | | +| --url | \[Optional\]

Artifactory URL. | +| --server-id | \[Optional\]

Server ID configured using the **jf c add** command. If not specified, the default configured Artifactory server is used. | +| --insecure-tls | \[Default: false\]

Set to true to skip TLS certificates verification. | +| Command arguments | The command accepts no arguments. | + +#### **Examples** + +##### **Example 1** + +Ping the configured default Artifactory server. +``` +jf rt ping +``` + +##### **Example 2** + +Ping the configured Artifactory server with ID **rt-server-1**. +``` +jf rt ping --server-id=rt-server-1 +``` + +##### **Example 3** + +Ping the Artifactory server. accessible through the specified URL. +``` +jf rt ping --url=https://my-rt-server.com/artifactory +``` + +### Uploading Files + +This command is used to upload files to Artifactory. + +| | | +|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command name | rt upload | +| Abbreviation | rt u | +| Command options | **Warning**

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. | +| --archive | \[Optional\]

Set to "zip" to pack and deploy the files to Artifactory inside a ZIP archive. Currently, the only packaging format supported is zip. | +| --server-id | \[Optional\]

Server ID configured using the **jf c add** 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](https://jfrog.com/help/r/jfrog-cli/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](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --build-number | \[Optional\]

Build number. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --project | \[Optional\]

JFrog project key. | +| --module | \[Optional\]

Optional module name for the build-info. | +| --target-props | \[Optional\]

A list of Artifactory [properties](https://jfrog.com/help/r/jfrog-artifactory-documentation/Working-With-Jfrog-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: false\]

If true, files are uploaded to the exact target path specified and their hierarchy in the source file system is ignored.

If false, files are uploaded to the target path while maintaining their file system hierarchy.

If [Using Placeholders](https://jfrog.com/help/r/jfrog-cli/using-placeholders) are used, the value of this option is ignored.

**Note**

**JFrog CLI v1**

In JFrog CLI v1, the default value of the --flat option is true. | +| --recursive | \[Default: true\]

If true, files are also collected from sub-folders of the source directory for upload .

If false, only files 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, it will interpret the first argument as a wild-card expression.

The above also applies for the --exclusions option.

If you have specified that you are using regular expressions, then the beginning of the expression must be enclosed in parenthesis. For example: **a/b/c/(.*)/file.zip** | +| --ant | \[Default: false\]

If true, the command will interpret the first argument, which describes the local file-system path of artifacts to upload, as an ANT pattern.

If false, it will interpret the first argument as a wildcards expression.

The above also applies for the --exclusions option. | +| --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. Bottom-chain directories are either empty or do not include other directories that match the source path. | +| --bypass-archive-inspection | \[Default: false\]

Set to true to bypass the archive security inspection before it is unarchived. Used with the 'explode' option.| +| --exclusions | \[Optional\]

A list of Semicolon-separated exclude patterns. Allows using wildcards, regular expressions or ANT patterns, according to the value of the **--regexp** and **--ant** options. Please read the **--regexp** and **--ant** options description for more information. | +| --sync-deletes | \[Optional\]

Specific path in Artifactory, under which to sync artifacts after the upload. After the upload, this path will include only the artifacts uploaded during this upload operation. The other files under this path will be deleted. | +| --quiet | \[Default: false\]

If true, the delete confirmation message is skipped. | +| --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. | +| --retry-wait-time | \[Default: 0s\]

Number of seconds or milliseconds to wait between retries. The numeric value should either end with s for seconds or ms for milliseconds. | +| --detailed-summary | \[Default: false\]

Set to true to include a list of the affected files as part of the command output summary. | +| --insecure-tls | \[Default: false\]

Set to true to skip TLS certificates verification. | +| Command arguments | The command takes two arguments.

In case the --spec option is used, the commands accept no arguments. | +| Source path | The first argument specifies the local file system path to artifacts that should be uploaded to Artifactory. You can specify multiple artifacts by using wildcards or a regular expression as designated by the **--regexp** command option. Please read the **--regexp** option description for more information. | +| 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](https://jfrog.com/help/r/jfrog-cli/using-placeholders). | + +#### Examples + +##### **Example 1** + +Upload a file called **froggy.tgz** to the root of the **my-local-repo** repository. +``` +jf rt u froggy.tgz my-local-repo +``` + +##### **Example 2** + +Collect all the zip files located under the **build** directory (including subdirectories), and upload them to the **my-local-repo** repository, under the **zipFiles** folder, while maintaining the original names of the files. +``` +jf rt u "build/*.zip" my-local-repo/zipFiles/ +``` + +##### **Example 3** + +Collect all the zip files located under the **build** directory (including subdirectories), and upload them to the **my-local-repo** repository, under the **zipFiles** folder, while maintaining the original names of the files. Also delete all files in the **my-local-repo** repository, under the **zipFiles** folder, except for the files which were uploaded by this command. +``` +jf rt u "build/*.zip" my-local-repo/zipFiles/ --sync-deletes="my-local-repo/zipFiles/" +``` + +##### **Example 4** + +Collect all files located under the **build** directory (including subdirectories), and upload them to the **my-release-local **repository, under the **files** folder, while maintaining the original names of the artifacts. Exclude (do not upload) files, which include **install** as part of their path, and have the **pack** extension. This example uses a wildcard pattern. See **Example 5**, which uses regular expressions instead. +``` +jf rt u "build/" my-release-local/files/ --exclusions="\*install\*pack*" +``` + +##### **Example 5** + +Collect all files located under the **build** directory (including subdirectories), and upload them to the **my-release-local** repository, under the **files** folder, while maintaining the original names of the artifacts. Exclude (do not upload) files, which include **install** as part of their path, and have the **pack** extension. This example uses a regular expression. See **Example 4**, which uses a wildcard pattern instead. +``` +jf rt u "build/" my-release-local/files/ --regexp --exclusions="(.*)install.*pack$" +``` + +##### **Example 6** + +Collect all files located under the **build** directory and match the **/*.zip** ANT pattern, and upload them to the **my-release-local** repository, under the **files** folder, while maintaining the original names of the artifacts. +``` +jf rt u "build/**/*.zip" my-release-local/files/ --ant +``` + +##### **Example 7** + +Package all files located under the **build** directory (including subdirectories) into a zip archive named **archive.zip** , and upload the archive to the **my-local-repo** repository, +``` +jf rt u "build/" my-local-repo/my-archive.zip --archive zip +``` + +### Downloading Files + +This command is used to download files from Artifactory. + +> Download from Remote Repositories:

By default, the command only downloads files that are cached on the current Artifactory instance. It does not download files located on remote Artifactory instances, through remote or virtual repositories. To allow the command to download files from remote Artifactory instances, which are proxied by the use of remote repositories, set the **JFROG_CLI_TRANSITIVE_DOWNLOAD_EXPERIMENTAL** environment variable to **true**. This functionality requires version 7.17 or above of Artifactory. The remote download functionality is supported only on remote repositories which proxy repositories on remote Artifactory instances. Downloading through a remote repository that proxies non-Artifactory repositories is not supported. + +| | | +|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command name | rt download | +| Abbreviation | rt dl | +| Command options | **Warning**

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\]

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](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --build-number | \[Optional\]

Build number. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --project | \[Optional\]

JFrog project key. | +| --module | \[Optional\]

Optional module name for the build-info. | +| --spec | \[Optional\]

Path to a file spec. For more details, please refer to [Using File Specs](https://jfrog.com/help/r/jfrog-cli/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](https://jfrog.com/help/r/jfrog-artifactory-documentation/Working-With-Jfrog-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 names and values will be downloaded. | +| --exclude-props | \[Optional\]

A list of Artifactory [properties](https://jfrog.com/help/r/jfrog-artifactory-documentation/Working-With-Jfrog-Properties) specified as "key=value" pairs separated by a semi-colon (for example, "key1=value1;key2=value2;key3=value3"). Only artifacts **without all** of the specified properties names and values will 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. | +| --bundle | \[Optional\]

If specified, only artifacts of the specified bundle are matched. The value format is bundle-name/bundle-version. | +| --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.

If [Using Placeholders](https://jfrog.com/help/r/jfrog-cli/using-placeholders) are used, and you would like the local file system (download path) to be determined by placeholders only, or in other words, avoid concatenating the Artifactory folder hierarchy local, set to false. | +| --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. | +| --retry-wait-time | \[Default: 0s\]

Number of seconds or milliseconds to wait between retries. The numeric value should either end with s for seconds or ms for milliseconds. | +| --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.

Supported compression formats: br, bz2, gz, lz4, sz, xz, zstd.

Supported archive formats: zip, tar (including any compressed variants like tar.gz), rar. | +| --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. Bottom-chain directories are either empty or do not include other directories that match the source path. | +| --exclusions | A list of Semicolon-separated exclude patterns. Allows using wildcards. | +| --sync-deletes | \[Optional\]

Specific path in the local file system, under which to sync dependencies after the download. After the download, this path will include only the dependencies downloaded during this download operation. The other files under this path will be deleted. | +| --quiet | \[Default: false\]

If true, the delete confirmation message is skipped. | +| --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](https://jfrog.com/help/r/jfrog-artifactory-documentation/artifactory-query-language) | +| --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. | +| --detailed-summary | \[Default: false\]

Set to true to include a list of the affected files as part of the command output summary. | +| --insecure-tls | \[Default: false\]

Set to true to skip TLS certificates verification. | +| --gpg-key | \[Optional\]

Path to the public GPG key file located on the file system, used to validate downloaded release bundle files. | +| Command arguments | | +| Source path | Specifies the source path in Artifactory, from which the artifacts should be downloaded. 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](https://jfrog.com/help/r/jfrog-cli/using-placeholders). | + +#### Examples + +##### **Example 1** + +Download an artifact called **cool-froggy.zip** located at the root of the **my-local-repo** repository to the current directory. +``` +jf 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. +``` +jf 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. +``` +jf rt dl "my-local-repo/*.jar" all-my-frogs/ +``` + +##### **Example 4** + +Download the latest file uploaded to the all-my-frogs folder in the **my-local-repo** repository. +``` +jf rt dl "my-local-repo/all-my-frogs/" --sort-by=created --sort-order=desc --limit=1 +``` + +### Copying Files + +This command is used to copy files in Artifactory + +| | | +|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command name | rt copy | +| Abbreviation | rt cp | +| Command options | **Warning**

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\]

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](https://jfrog.com/help/r/jfrog-cli/using-file-specs). | +| --props | \[Optional\]

A list of Artifactory [properties](https://jfrog.com/help/r/jfrog-artifactory-documentation/Working-With-Jfrog-Properties) specified as "key=value" pairs separated by a semi-colon. (For example, "key1=value1;key2=value2;key3=value3"). Only artifacts with these properties names and values will be copied. | +| --exclude-props | \[Optional\]

A list of Artifactory [properties](https://jfrog.com/help/r/jfrog-artifactory-documentation/Working-With-Jfrog-Properties) specified as "key=value" pairs separated by a semi-colon (for example, "key1=value1;key2=value2;key3=value3"). Only artifacts **without all** of the specified properties names and values 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. | +| --bundle | \[Optional\]

If specified, only artifacts of the specified bundle are matched. The value format is bundle-name/bundle-version. | +| --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. | +| --exclusions | A list of Semicolon-separated exclude patterns. Allows using wildcards. | +| --threads | \[Default: 3\]

Number of threads used for copying the items. | +| --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](https://jfrog.com/help/r/jfrog-artifactory-documentation/artifactory-query-language) | +| --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. | +| --insecure-tls | \[Default: false\]

Set to true to skip TLS certificates verification. | +| --retries | \[Default: 3\]

Number for HTTP retry attempts. | +| --retry-wait-time | \[Default: 0s\]

Number of seconds or milliseconds to wait between retries. The numeric value should either end with s for seconds or ms for milliseconds. | +| 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](https://jfrog.com/help/r/jfrog-cli/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. +``` +jf 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. +``` +jf 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. +``` +jf 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 | rt move | +| Abbreviation | rt mv | +| Command options | **Warning**

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\]

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](https://jfrog.com/help/r/jfrog-cli/using-file-specs). | +| --props | \[Optional\]

A list of Artifactory [properties](https://jfrog.com/help/r/jfrog-artifactory-documentation/Working-With-Jfrog-Properties) specified as "key=value" pairs separated by a semi-colon (for example, "key1=value1;key2=value2;key3=value3"). Only artifacts with these properties names and values will be moved. | +| --exclude-props | \[Optional\]

A list of Artifactory [properties](https://jfrog.com/help/r/jfrog-artifactory-documentation/Working-With-Jfrog-Properties) specified as "key=value" pairs separated by a semi-colon (for example, "key1=value1;key2=value2;key3=value3"). Only artifacts **without all** of the specified properties names and values 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. | +| --bundle | \[Optional\]

If specified, only artifacts of the specified bundle are matched. The value format is bundle-name/bundle-version. | +| --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. | +| --exclusions | A list of Semicolon-separated exclude patterns. Allows using wildcards. | +| --threads | \[Default: 3\]

Number of threads used for moving the items. | +| --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](https://jfrog.com/help/r/jfrog-artifactory-documentation/artifactory-query-language) | +| --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. | +| --insecure-tls | \[Default: false\]

Set to true to skip TLS certificates verification. | +| --retries | \[Default: 3\]

Number of HTTP retry attempts. | +| --retry-wait-time | \[Default: 0s\]

Number of seconds or milliseconds to wait between retries. The numeric value should either end with s for seconds or ms for milliseconds. | +| 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](https://jfrog.com/help/r/jfrog-cli/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. +``` +jf 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. +``` +jf 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 . +``` +jf 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 | rt delete | +| Abbreviation | rt del | +| Command options | **Warning**

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\]

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](https://jfrog.com/help/r/jfrog-cli/using-file-specs). | +| --props | \[Optional\]

A list of Artifactory [properties](https://jfrog.com/help/r/jfrog-artifactory-documentation/Working-With-Jfrog-Properties) specified as "key=value" pairs separated by a semi-colon (for example, "key1=value1;key2=value2;key3=value3"). Only artifacts with these properties names and values will be deleted. | +| --exclude-props | \[Optional\]

A list of Artifactory [properties](https://jfrog.com/help/r/jfrog-artifactory-documentation/Working-With-Jfrog-Properties) specified as "key=value" pairs separated by a semi-colon (for example, "key1=value1;key2=value2;key3=value3"). Only artifacts **without all** of the specified properties names and values 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. | +| --bundle | \[Optional\]

If specified, only artifacts of the specified bundle are matched. The value format is bundle-name/bundle-version. | +| --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. | +| --exclusions | A list of Semicolon-separated exclude patterns. Allows using wildcards. | +| --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](https://jfrog.com/help/r/jfrog-artifactory-documentation/artifactory-Query-Language) | +| --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. | +| --threads | \[Default: 3\]

Number of threads used for deleting the items. | +| --insecure-tls | \[Default: false\]

Set to true to skip TLS certificates verification. | +| --retries | \[Default: 3\]

Number of HTTP retry attempts. | +| --retry-wait-time | \[Default: 0s\]

Number of seconds or milliseconds to wait between retries. The numeric value should either end with s for seconds or ms for milliseconds.--retry-wait-time | +| 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. +``` +jf rt del frog-repo/rabbit/ +``` + +##### **Example 2** + +Delete all zip files located under **/rabbit** in the **frog-repo** repository. +``` +jf rt del "frog-repo/rabbit/*.zip" +``` + +### Searching Files + +This command is used to search and display files in Artifactory. + +| | | +|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command name | rt search | +| Abbreviation | rt s | +| Command options | **Warning**

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\]

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](https://jfrog.com/help/r/jfrog-cli/using-file-specs). | +| --count | \[Optional\]

Set to true to display only the total of files or folders found. | +| --include-dirs | \[Optional\]

Set to true if you'd like to also apply the source path pattern for directories and not only for files | +| --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](https://jfrog.com/help/r/jfrog-artifactory-documentation/Working-With-Jfrog-Properties) specified as "key=value" pairs separated by a semi-colon (for example, "key1=value1;key2=value2;key3=value3"). Only artifacts with these properties names and values will be returned. | +| --exclude-props | \[Optional\]

A list of Artifactory [properties](https://jfrog.com/help/r/jfrog-artifactory-documentation/Working-With-Jfrog-Properties) specified as "key=value" pairs separated by a semi-colon (for example, "key1=value1;key2=value2;key3=value3"). Only artifacts **without all** of the specified properties names and values 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. | +| --bundle | \[Optional\]

If specified, only artifacts of the specified bundle are matched. The value format is bundle-name/bundle-version. | +| --recursive | \[Default: true\]

Set to false if you do not wish to search artifacts inside sub-folders in Artifactory. | +| --exclusions | A list of Semicolon-separated exclude patterns. Allows using wildcards. | +| --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](https://jfrog.com/help/r/jfrog-artifactory-documentation/artifactory-query-language) | +| --sort-order | \[Default: asc\]

The order by which fields in the 'sort-by' option should be sorted. Accepts 'asc' or 'desc'. | +| --transitive | \[Default: false\]

Set to true to look for artifacts also in remote repositories. Available on Artifactory version 7.17.0 or higher. | +| --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. | +| --insecure-tls | \[Default: false\]

Set to true to skip TLS certificates verification. | +| --retries | \[Default: 3\]

Number of HTTP retry attempts. | +| --retry-wait-time | \[Default: 0s\]

Number of seconds or milliseconds to wait between retries. The numeric value should either end with s for seconds or ms for milliseconds.retry-wait-time | +| --include | \[Optional\]

List of fields in the form of \"value1;value2;...\".
Only the path and the fields that are specified will be returned. The fields must be part of the 'items' AQL domain. for the full supported items list check [AQL documentation](https://jfrog.com/help/r/jfrog-artifactory-documentation/artifactory-query-language) | +| 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. +``` +jf rt s frog-repo/rabbit/ +``` + +##### **Example 2** + +Display a list of all zip files located under **/rabbit** in the **frog-repo** repository. +``` +jf rt s "frog-repo/rabbit/*.zip" +``` + +##### **Example 3** + +Display a list of the files under example-repo-local with the following fields: path, actual_md5, modified_b, updated and depth. +``` +jf rt s example-repo-local --include="actual_md5;modified_by;updated;depth" +``` + +### Setting Properties on Files + +This command is used for setting properties on existing files in Artifactory. + +| | | +|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command name | rt set-props | +| Abbreviation | rt sp | +| Command options | **Warning**

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\]

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](https://jfrog.com/help/r/jfrog-cli/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\]

List of properties in the form of "key1=value1;key2=value2,...". Only files with these properties names and values are affected. | +| --exclude-props | \[Optional\]

A list of Artifactory [properties](https://jfrog.com/help/r/jfrog-artifactory-documentation/Working-With-Jfrog-Properties) specified as "key=value" pairs separated by a semi-colon (for example, "key1=value1;key2=value2;key3=value3"). Only artifacts **without all** of the specified properties names and values will be 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. | +| --bundle | \[Optional\] If specified, only artifacts of the specified bundle are matched. The value format is bundle-name/bundle-version. | +| --include-dirs | \[Default: false\]

When true, the properties will also be set on folders (and not just files) in Artifactory. | +| --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. | +| --exclusions | A list of Semicolon-separated exclude patterns. Allows using wildcards. | +| --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](https://jfrog.com/help/r/jfrog-artifactory-documentation/artifactory-query-language) | +| --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. | +| --insecure-tls | \[Default: false\]

Set to true to skip TLS certificates verification. | +| --threads | \[Default: 3\]

Number of working threads. | +| --retries | \[Default: 3\]

Number of HTTP retry attempts. | +| --retry-wait-time | \[Default: 0s\]

Number of seconds or milliseconds to wait between retries. The numeric value should either end with s for seconds or ms for milliseconds. | +| 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 + +##### **Example 1** + +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". +``` +jf rt sp "generic-local/*.zip" "a=1;b=2,3" +``` + +##### **Example 2** + +The command will set the property "a" with "1" value and the property "b" with two values: "2" and "3" on all files found by the File Spec my-spec. +``` +jf rt sp "a=1;b=2,3" --spec my-spec +``` + +### Deleting Properties from Files + +This command is used for deleting properties from existing files in Artifactory. + +| | | +|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command name | rt delete-props | +| Abbreviation | rt delp | +| Command options | **Warning**

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. | +| --exclude-props | \[Optional\]

A list of Artifactory [properties](https://jfrog.com/help/r/jfrog-artifactory-documentation/Working-With-Jfrog-Properties) specified as "key=value" pairs separated by a semi-colon (for example, "key1=value1;key2=value2;key3=value3"). Only artifacts **without all** of the specified properties names and values will be 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. | +| --bundle | \[Optional\]

If specified, only artifacts of the specified bundle are matched. The value format is bundle-name/bundle-version. | +| --include-dirs | \[Default: false\]

When true, the properties will also be set on folders (and not just files) in Artifactory. | +| --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. | +| --exclusions | A list of Semicolon-separated exclude patterns. Allows using wildcards. | +| --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](https://jfrog.com/help/r/jfrog-artifactory-documentation/artifactory-query-language) | +| --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. | +| --insecure-tls | \[Default: false\]

Set to true to skip TLS certificates verification. | +| --retries | \[Default: 3\]

Number of HTTP retry attempts. | +| --retry-wait-time | \[Default: 0s\]

Number of seconds or milliseconds to wait between retries. The numeric value should either end with s for seconds or ms for milliseconds.retry-wait-time | +| 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. +``` +jf rt delp "generic-local/*.zip" "status,phase" +``` + +### Creating Access Tokens + +This command allows creating [Access Tokens](https://jfrog.com/help/r/jfrog-platform-administration-Documentation/Access-Tokens) for users in Artifactory + +| | | +|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command name | rt access-token-create | +| Abbreviation | rt atc | +| Command options | | +| --groups | \[Default: *\]

A list of comma-separated groups for the access token to be associated with. Specify * to indicate that this is a 'user-scoped token', i.e., the token provides the same access privileges that the current subject has, and is therefore evaluated dynamically. A non-admin user can only provide a scope that is a subset of the groups to which he belongs | +| --grant-admin | \[Default: false\]

Set to true to provides admin privileges to the access token. This is only available for administrators. | +| --expiry | \[Default: 3600\]

The time in seconds for which the token will be valid. To specify a token that never expires, set to zero. Non-admin can only set a value that is equal to or less than the default 3600. | +| --refreshable | \[Default: false\]

Set to true if you'd like the the token to be refreshable. A refresh token will also be returned in order to be used to generate a new token once it expires. | +| --audience | \[Optional\]

A space-separate list of the other Artifactory instances or services that should accept this token identified by their Artifactory Service IDs, as obtained by the 'jf rt curl api/system/serviceid' command. | +| Command arguments | | +| username | Optional - The user name for which this token is created. If not specified, the configured user is used. | + +#### **Examples** + +Create an access token for the user with the **commander-will-riker** username. +``` +jf rt atc commander-will-riker +``` + +### 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 | rt git-lfs-clean | +| Abbreviation | rt 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. | +| --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 Git LFS files from Artifactory, using the configuration in the .git directory located at the current directory. +``` + jf rt glc +``` + +##### **Example 2** + +Cleans up Git LFS files from Artifactory, using the configuration in the .git directory located inside the path/to/git/config directory. +``` +jf rt glc path/to/git/config +``` + +### Running cUrl + +Execute a cUrl command, using the configured Artifactory details. The command expects the cUrl client to be included in the PATH. + +> **Note** - This command supports only Artifactory REST APIs, which are accessible under https://<JFrog base URL>/artifactory/api/ + + +| | | | +|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----| +| Command name | rt curl | | +| Abbreviation | rt cl | | +| Command options | | | +| --server-id | \[Optional\]

Server ID configured using the **jf c add** command. If not specified, the default configured server is used. | | +| Command arguments | | | +| cUrl arguments and flags | The same list of arguments and flags passed to cUrl, except for the following changes:

1. The full Artifactory URL should not be passed. Instead, the REST endpoint URI should be sent.
2. The login credentials should not be passed. Instead, the --server-id should be used. | | + +Currently only servers configured with username and password / API key are supported. + +#### **Examples** + +##### **Example 1** + +Execute the cUrl client, to send a GET request to the /api/build endpoint to the default Artifactory server +``` +jf rt curl -XGET /api/build +``` + +##### **Example 2** + +Execute the cUrl client, to send a GET request to the /api/build endpoint to the configured my-rt-server server ID. +``` +jf rt curl -XGET /api/build --server-id my-rt-server +``` + +## Build Integration +### Overview + +JFrog CLI integrates with any development ecosystem allowing you to collect build-info and then publish it to Artifactory. By publishing build-info to Artifactory, JFrog CLI empowers Artifactory to provide visibility into artifacts deployed, dependencies used and extensive information on the build environment to allow fully traceable builds. Read more about build-info and build integration with Artifactory [here](https://jfrog.com/help/r/jfrog-integrations-documentation/Build-Integration). + +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](https://jfrog.com/help/r/jfrog-cli/publishing-build-info) command. + +### Collecting Build-Info + +Build-info 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-info for the specified build name and number until it is published to Artifactory. For example, running the `jf rt download` command several times with the same build name and number will accumulate each downloaded file in the corresponding build-info. + +#### Collecting Dependencies + +Dependencies are collected by adding the `--build-name` and `--build-number` options to the `jf rt 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: +``` +jf 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 `jf rt 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: +``` +jf rt u froggy.tgz my-local-repo --build-name=my-build-name --build-number=18 +``` +#### Collecting Environment Variables + +This command is used to collect environment variables and attach them to a build. + +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-info for build `my-build-name` with build number 18: +``` +jf rt bce my-build-name 18 +``` +The following table lists the command arguments and flags: + +| | | +|-------------------|----------------------------------------| +| Command name | rt build-collect-env | +| Abbreviation | rt bce | +| Command options | | +| --project | \[Optional\]

JFrog project key. | +| 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 +``` +jf rt bce frogger-build 17 +``` + +#### 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 reading the git commit messages from the local git log. Each commit message is matched against a pre-configured regular expression, which 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. + +The following table lists the command arguments and flags: + +| | | +|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command name | rt build-add-git | +| Abbreviation | rt bag | +| Command options | | +| --config | \[Optional\]

Path to a yaml configuration file, used for collecting tracked project issues and adding them to the build-info. | +| --server-id | \[Optional\]

Server ID configured using the ['jf config' command](https://jfrog.com/help/r/jfrog-cli/jfrog-Platform-CONFIGURATION). This is the server to which the build-info will be later published, using the `jf rt build-publish` command. This option, if provided, overrides the serverID value in this command's yaml configuration. If both values are not provided, the default server, configured by the ['jf config' command](https://jfrog.com/help/r/jfrog-cli/jfrog-Platform-CONFIGURATION), is used. | +| --project | \[Optional\]

JFrog project key. | +| 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 +``` +jf rt bag frogger-build 17 checkout-dir +``` + +This is the configuration file structure. +```yaml +version: 1 +issues: + # The serverID yaml property is optional. The --server-id command option, if provided, overrides the serverID value. + # If both the serverID property and the --server-id command options are not provided, + # the default server, configured by the "jfrog config add" command is used. + serverID: my-artifactory-server + + trackerName: JIRA + regexp: (.+-\[0-9\]+)\\s-\\s(.+) + keyGroupIndex: 1 + summaryGroupIndex: 2 + trackerUrl: https://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 ['jf config' command](https://jfrog.com/help/r/jfrog-cli/jfrog-Platform-CONFIGURATION). The command uses this server for fetching details about previous published builds. The **--server-id** command option, if provided, overrides the **serverID** value.
If both the **serverID** property and the **--server-id** command options are not provided, the default server, configured by the ['jf config' command](https://jfrog.com/help/r/jfrog-cli/jfrog-Platform-CONFIGURATION) is used. | +| 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 **jf rt build-promote** command. | + +#### Adding 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, it is necessary to add a file, which has been downloaded by another tool, to a build. Use the **build-add-dependencies** command to this. + +By default, the command collects the files from the local file system. If you'd like the files to be collected from Artifactory however, add the **--from-rt** option to the command. + +| | | +|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command name | rt build-add-dependencies | +| Abbreviation | rt bad | +| Command options | **Warning**

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. | +| --from-rt | \[Default: false\]

Set to true to search the files in Artifactory, rather than on the local file system. The --regexp option is not supported when --from-rt is set to true. | +| --server-id | \[Optional\]

Server ID configured using the config command. | +| --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.This option is not supported when --from-rt is set to true. | +| --dry-run | \[Default: false\]

Set to true to only get a summery of the dependencies that will be added to the build info. | +| --module | \[Optional\]

Optional module name in the build-info for adding the dependency. | +| --exclusions | 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 three 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 + +**Example 1** + +Add all files located under the **path/to/build/dependencies/dir** directory as dependencies of a build. The build name is **my-build-name** and the build number is **7**. The build-info is only updated locally. To publish the build-info to Artifactory use the **jf rt build-publish** command. +``` +jf rt bad my-build-name 7 "path/to/build/dependencies/dir/" +``` + + +**Example 2** + +Add all files located in the **m-local-repo** Artifactory repository, under the **dependencies** folder, as dependencies of a build. The build name is **my-build-name** and the build number is **7**. The build-info is only updated locally. To publish the build-info to Artifactory use the **jf rt build-publish** command. +``` +jf rt bad my-build-name 7 "my-local-repo/dependencies/" --from-rt +``` + + +**Example 3** + +Add all files located under the **path/to/build/dependencies/dir** directory as dependencies of a build. The build name is **my-build-name**, the build number is **7** and module is m1. The build-info is only updated locally. To publish the build-info to Artifactory use the **jf rt build-publish** command. +``` +jf rt bad my-build-name 7 "path/to/build/dependencies/dir/" --module m1 +``` + +### Publishing Build-Info + +This command is used to publish build info to Artifactory. To publish the accumulated build-info for a build to Artifactory, use the **build-publish** command. For example, the following command publishes all the build-info collected for build **my-build-name** with build number 18: +``` +jf bp my-build-name 18 +``` + +This command is used to publish build info to Artifactory. + +| | | +|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command name | rt build-publish | +| Abbreviation | rt bp | +| Command options | | +| --server-id | \[Optional\]

Server ID configured using the config command. If not specified, the default configured Artifactory server is used. | +| --project | \[Optional\]

JFrog project key. | +| --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. | +| --insecure-tls | \[Default: false\]

Set to true to skip TLS certificates verification. | +| Command arguments | The command accepts two arguments. | +| Build name | Build name to be published. | +| Build number | Build number to be published. | + +##### Example +``` +jf rt bp my-build-name 18 +``` + +### Aggregating Published Builds +The build-info, which is collected and published to Artifactory by the **jf rt build-publish** command, can include multiple modules. Each module in the build-info represents a package, which is the result of a single build step, or in other words, a JFrog CLI command execution. For example, the following command adds a module named **m1** to a build named **my-build** with **1** as the build number: +``` +jf rt upload "a/*.zip" generic-local --build-name my-build --build-number 1 --module m1 +``` + +The following command, adds a second module, named **m2** to the same build: +``` +jf rt upload "b/*.zip" generic-local --build-name my-build --build-number 1 --module m2 +``` + +You now publish the generated build-info to Artifactory using the following command: +``` +jf rt build-publish my-build 1 +``` + +Now that you have your build-info published to Artifactory, you can perform actions on the entire build. For example, you can download, copy, move or delete all or some of the artifacts of a build. Here's how you do this. +``` +jf rt download "*" --build my-build/1 +``` + +In some cases though, your build is composed of multiple build steps, which are running on multiple different machines or spread across different time periods. How do you aggregate those build steps, or in other words, aggregate those command executions, into one build-info? + +The way to do this, is to create a separate build-info for every section of the build, and publish it independently to Artifactory. Once all the build-info instances are published, you can create a new build-info, which references all the previously published build-info instances. The new build-info can be viewed as a "master" build-info, which references other build-info instances. + +So the next question is - how can this reference between the two build-instances be created? + +The way to do this is by using the **build-append** command. Running this command on an unpublished build-info, adds a reference to a different build-info, which has already been published to Artifactory. This reference is represented by a new module in the new build-info. The ID of this module will have the following format: **<referenced build name>/<referenced build number>. + +Now, when downloading the artifacts of the "master" build, you'll actually be downloading the artifacts of all of its referenced builds. The examples below demonstrates this, + +| | | +|------------------------|-----------------------------------------------------------| +| Command name | rt build-append | +| Abbreviation | rt ba | +| Command options | This command has no options. | +| Command arguments | The command accepts four arguments. | +| Build name | The current (not yet published) build name. | +| Build number | The current (not yet published) build number, | +| build name to append | The published build name to append to the current build | +| build number to append | The published build number to append to the current build | + +##### Requirements + +Artifactory version 7.25.4 and above. + +##### Example +```yaml +# Create and publish build a/1 +jf rt upload "a/*.zip" generic-local --build-name a --build-number 1 +jf rt build-publish a 1 + +# Create and publish build b/1 +jf rt upload "b/*.zip" generic-local --build-name b --build-number 1 +jf rt build-publish b 1 + +# Append builds a/1 and b/1 to build aggregating-build/10 +jf rt build-append aggregating-build 10 a 1 +jf rt build-append aggregating-build 10 b 1 + +# Publish build aggregating-build/10 +jf rt build-publish aggregating-build 10 + +# Download the artifacts of aggregating-build/10, which is the same as downloading the of a/1 and b/1 +jf rt download --build aggregating-build/10 +``` + +### Promoting a Build + +This command is used to [promote build](https://jfrog.com/knowledge-base/how-does-build-promotion-work/) in Artifactory. + +| | | +|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| +| Command name | rt build-promote | +| Abbreviation | rt bpr | +| Command options | | +| --server-id | \[Optional\]

Server ID configured using the config command. If not specified, the default configured Artifactory server is used. | +| --project | \[Optional\]

JFrog project key. | +| --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. | +| --props | \[Optional\]

List of properties in the form of "key1=value1;key2=value2,...". to attach to the build artifacts. | +| --dry-run | \[Default: false\]

If true, promotion is only simulated. The build is not promoted. | +| --insecure-tls | \[Default: false\]

Set to true to skip TLS certificates verification. | +| 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 +``` +jf rt bpr my-build-name 18 target-repository +``` + +### Cleaning up the Build + +Build-info is accumulated by the CLI according to the commands you apply until you publish the build-info to Artifactory. If, for any reason, you wish to "reset" the build-info and cleanup (i.e. delete) any information accumulated so far, you can use the `build-clean` (`bc`) command. + +The following table lists the command arguments and flags: + +| | | +|-------------------|------------------------------------| +| Command name | rt build-clean | +| Abbreviation | rt bc | +| Command options | The command has no options. | +| Command arguments | The command accepts two arguments. | +| Build name | Build name. | +| Build number | Build number. | + + + +For example, the following command cleans up any build-info collected for build `my-build-name` with build number 18: +``` +jf rt bc my-build-name 18 +``` + +### Discarding Old Builds from Artifactory + +This command is used to discard builds previously published to Artifactory using the [build-publish](https://jfrog.com/help/r/jfrog-cli/publishing-build-info) command. + +The following table lists the command arguments and flags: + +| | | +|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------| +| Command name | rt build-discard | +| Abbreviation | rt bdi | +| Command options | | +| --server-id | \[Optional\]

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. +``` +jf 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. +``` +jf 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. +``` +jf rt bdi my-build-name --max-days 7 --exclude-builds "b20,b21" +``` + +Package Managers Integration +---------------------------- + +### Running Maven Builds + +JFrog CLI includes integration with Maven, allowing you to resolve dependencies and deploy build artifacts from and to Artifactory, while collecting build-info and storing it in Artifactory. + +#### Setting maven repositories + +Before using the **mvn** command, the project needs to be pre-configured with the Artifactory server and repositories, to be used for building and publishing the project. The **mvn-config** command should be used once to add the configuration to the project. The command should run while inside the root directory of the project. The configuration is stored by the command in the **.jfrog** directory at the root directory of the project. + +| | | +|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | mvn-config | +| Abbreviation | mvnc | +| Command options | | +| --global | \[Optional\]

Set to true, if you'd like the configuration to be global (for all projects on the machine). Specific projects can override the global configuration. | +| --server-id-resolve | \[Optional\]

Server ID for resolution. The server should configured using the 'jf rt c' command. | +| --server-id-deploy | \[Optional\]

Server ID for deployment. The server should be configured using the 'jf rt c' command. | +| --repo-resolve-releases | \[Optional\]

Resolution repository for release dependencies. | +| --repo-resolve-snapshots | \[Optional\]

Resolution repository for snapshot dependencies. | +| --repo-deploy-releases | \[Optional\]

Deployment repository for release artifacts. | +| --repo-deploy-snapshots | \[Optional\]

Deployment repository for snapshot artifacts. | +| --include-patterns | \[Optional\]

Filter deployed artifacts by setting a wildcard pattern that specifies which artifacts to include. You may provide multiple patterns separated by a comma followed by a white-space. For example

artifact-*.jar, artifact-*.pom | +| --exclude-patterns | \[Optional\]

Filter deployed artifacts by setting a wildcard pattern that specifies which artifacts to exclude. You may provide multiple patterns separated by a comma followed by a white-space. For example

artifact-*-test.jar, artifact-*-test.pom | +| --scan | \[Default: false\]

Set if you'd like all files to be scanned by Xray on the local file system prior to the upload, and skip the upload if any of the files are found vulnerable. | +| --format | \[Default: table\]

Should be used with the --scan option. Defines the scan output format. Accepts table or json as values. | +| Command arguments | The command accepts no arguments | + +#### Running maven + +The **mvn** command triggers the maven client, while resolving dependencies and deploying artifacts from and to Artifactory. + +> **Note**: Before running the **mvn** command on a project for the first time, the project should be configured with the **mvn-config** command. + +> **Note**: If the machine running JFrog CLI has no access to the internet, make sure to read the [Downloading the Maven and Gradle Extractor JARs](https://jfrog.com/help/r/jfrog-cli/downloading-the-maven-and-gradle-extractor-jars) section. + +The following table lists the command arguments and flags: + +| | | +|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | mvn | +| Abbreviation | mvn | +| Command options | | +| --threads | \[Default: 3\]

Number of threads for uploading build artifacts. | +| --build-name | \[Optional\]

Build name. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --build-number | \[Optional\]

Build number. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --project | \[Optional\]

JFrog project key. | +| --insecure-tls | \[Default: false\]

Set to true to skip TLS certificates verification. | +| Command arguments | The command accepts the same arguments and options as the mvn client. | + +**Deploying Maven Artifacts** + +The deployment to Artifacts is triggered both by the deployment and install phases. +To disable artifacts deployment, add** **-Dartifactory.publish.artifacts=false** to the list of goals and options. +For example: "**clean install****-Dartifactory.publish.artifacts=false"** + +##### Examples + +**Example 1** + +Run clean and install with maven. +``` +jf mvn clean install -f path/to/pom-file +``` + +### Running Gradle Builds + +JFrog CLI includes integration with Gradle, allowing you to resolve dependencies and deploy build artifacts from and to Artifactory, while collecting build-info and storing it in Artifactory. + +#### Setting gradle repositories + +Before using the **gradle** command, the project needs to be pre-configured with the Artifactory server and repositories, to be used for building and publishing the project. The **gradle-config** command should be used once to add the configuration to the project. The command should run while inside the root directory of the project. The configuration is stored by the command in the**.jfrog** directory at the root directory of the project. + +| | | +|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | gradle-config | +| Abbreviation | gradlec | +| Command options | | +| --global | \[Optional\]

Set to true, if you'd like the configuration to be global (for all projects on the machine). Specific projects can override the global configuration. | +| --server-id-resolve | \[Optional\]

Server ID for resolution. The server should configured using the 'jf c add' command. | +| --server-id-deploy | \[Optional\]

Server ID for deployment. The server should be configured using the 'jf c add' command. | +| --repo-resolve | \[Optional\]

Repository for dependencies resolution. | +| --repo-deploy | \[Optional\]

Repository for artifacts deployment. | +| --uses-plugin | \[Default: false\]

Set to true if the Gradle Artifactory Plugin is already applied in the build script. | +| --use-wrapper | \[Default: false\]

Set to true if you'd like to use the Gradle wrapper. | +| --deploy-maven-desc | \[Default: true\]

Set to false if you do not wish to deploy Maven descriptors. | +| --deploy-ivy-desc | \[Default: true\]

Set to false if you do not wish to deploy Ivy descriptors. | +| --ivy-desc-pattern | \[Default: '\[organization\]/\[module\]/ivy-\[revision\].xml'

Set the deployed Ivy descriptor pattern. | +| --ivy-artifacts-pattern | \[Default: '\[organization\]/\[module\]/\[revision\]/\[artifact\]-\[revision\](-\[classifier\]).\[ext\]'

Set the deployed Ivy artifacts pattern. | +| --scan | \[Default: false\]

Set if you'd like all files to be scanned by Xray on the local file system prior to the upload, and skip the upload if any of the files are found vulnerable. | +| --format | \[Default: table\]

Should be used with the --scan option. Defines the scan output format. Accepts table or json as values. | +| Command arguments | The command accepts no arguments | + +#### Running gradle + +The **gradle** command triggers the gradle client, while resolving dependencies and deploying artifacts from and to Artifactory. + +> **Note**: Before running the **gradle** command on a project for the first time, the project should be configured with the **gradle-config** command. + +> **Note**: If the machine running JFrog CLI has no access to the internet, make sure to read the[Downloading the Maven and Gradle Extractor JARs](https://jfrog.com/help/r/jfrog-cli/downloading-the-maven-and-gradle-extractor-jars)section. + +The following table lists the command arguments and flags: + +| | | +|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | gradle | +| Abbreviation | gradle | +| Command options | | +| --threads | \[Default: 3\]

Number of threads for uploading build artifacts. | + | --build-name | \[Optional\]

Build name. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --build-number | \[Optional\]

Build number. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --project | \[Optional\]

JFrog project key. | +| Command arguments | The command accepts the same arguments and options as the gradle client. | + +##### Examples + +**Example 1** + +Build the project using the **artifactoryPublish** task, while resolving and deploying artifacts from and to Artifactory. +``` +jf gradle clean artifactoryPublish -b path/to/build.gradle +``` + +### 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](https://github.com/eyalbe4/project-examples/tree/master/msbuild-example) on GitHub. + +### Managing Docker Images + +JFrog CLI provides full support for pulling and publishing docker images from and to Artifactory using the docker client running on the same machine. This allows you to collect build-info for your docker build and then publish it to Artifactory. You can also promote the pushed docker images from one repository to another in Artifactory. + +To build and push your docker images to Artifactory, follow these steps: + +1. Make sure Artifactory can be used as docker registry. Please refer to [Getting Started with Docker and Artifactory](https://jfrog.com/help/r/jfrog-artifactory-documentation/Getting-Started-With-Artifactory-As-A-docker-Registry) in the JFrog Artifactory User Guide. +2. Make sure that the installed docker client has version **17.07.0-ce (2017-08-29)** or above. To verify this, run **docker -v**** +3. 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. + +> **Note**: When running the docker-pull and docker-push commands, the CLI will first attempt to log in to the docker registry. In case of a login failure, the command will not be executed. + +#### Examples + +Check out our [docker project examples on GitHub](https://github.com/jfrog/project-examples/tree/master/docker-oci-examples). + +#### Pulling Docker Images Using the Docker Client + +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](https://jfrog.com/help/r/jfrog-cli/publishing-build-info) command. + +The following table lists the command arguments and flags: + + + +| | | +|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | docker pull | +| Abbreviation | dpl | +| Command options | | +| --server-id | \[Optional\]

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](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --build-number | \[Optional\]

Build number. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --project | \[Optional\]

JFrog project key. | +| --module | \[Optional\]

Optional module name for the build-info. | +| --skip-login | \[Default: false\]

Set to true if you'd like the command to skip performing docker login. | +| Command arguments | The same arguments and options supported by the docker client/ | + +##### Examples + +jf docker pull my-docker-registry.io/my-docker-image:latest --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](https://jfrog.com/help/r/jfrog-cli/publishing-build-info) command. + + + +#### Pushing Docker Images Using the Docker Client + +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\]

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](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --build-number | \[Optional\]

Build number. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --project | \[Optional\]

JFrog project key. | +| --module | \[Optional\]

Optional module name for the build-info. | +| --skip-login | \[Default: false\]

Set to true if you'd like the command to skip performing docker login. | +| --threads | \[Default: 3\]

Number of working threads. | +| --detailed-summary | \[Default: false\]

Set true to include a list of the affected files as part of the command output summary. | +| Command arguments | The same arguments and options supported by the docker client/ | + +##### Examples + +jf docker push my-docker-registry.io/my-docker-image:latest --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](https://jfrog.com/help/r/jfrog-cli/publishing-build-info) command. + + + +#### Pulling Docker Images Using Podman + +[Podman](https://podman.io/) is a daemonless container engine for developing, managing, and running OCI Containers. Running the **podman-pull** command allows pulling docker images from Artifactory using podman, while collecting the build-info and storing it locally, so that it can be later published to Artifactory, using the [build-publish](https://jfrog.com/help/r/jfrog-cli/publishing-build-info) command. + +The following table lists the command arguments and flags: + +| | | +|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | rt podman-pull | +| Abbreviation | rt ppl | +| Command options | | +| --server-id | \[Optional\]

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](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --build-number | \[Optional\]

Build number. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --project | \[Optional\]

JFrog project key. | +| --module | \[Optional\]

Optional module name for the build-info. | +| --skip-login | \[Default: false\]

Set to true if you'd like the command to skip performing docker login. | +| Command argument | | +| Image tag | The docker image tag to pull. | +| Source repository | Source repository in Artifactory. | + +##### Examples +``` +jf rt podman-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 **podman-pull** command to Artifactory using the [build-publish](https://jfrog.com/help/r/jfrog-cli/publishing-build-info) command. + + + +#### Pushing Docker Images Using Podman + +[Podman](https://podman.io/) is a daemon-less container engine for developing, managing, and running OCI Containers. After building your image, the **podman-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 | rt podman-push | +| Abbreviation | rt pp | +| Command options | | +| --server-id | \[Optional\]

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](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --build-number | \[Optional\]

Build number. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --project | \[Optional\]

JFrog project key. | +| --module | \[Optional\]

Optional module name for the build-info. | +| --skip-login | \[Default: false\]

Set to true if you'd like the command to skip performing docker login. | +| --threads | \[Default: 3\]

Number of working threads. | +| --detailed-summary | \[Default: false\]

Set to true to include a list of the affected files as part of the command output summary. | +| Command argument | | +| Image tag | The docker image tag to push. | +| Target repository | Target repository in Artifactory. | + +##### Examples +``` +jf rt podman-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 **podman-push** command to Artifactory using the [build-publish](https://jfrog.com/help/r/jfrog-cli/publishing-build-info) command. + + + +#### Pushing Docker Images Using Kaniko + +JFrog CLI allows pushing containers to Artifactory using [Kaniko](https://github.com/GoogleContainerTools/kaniko#kaniko---build-images-in-kubernetes), while collecting build-info and storing it in Artifactory. +For detailed instructions, please refer to our [Kaniko project example on GitHub](https://github.com/jfrog/project-examples/tree/master/docker-oci-examples/kaniko-example). + +#### Pushing Docker Images Using buildx + +JFrog CLI allows pushing containers to Artifactory using [buildx](https://github.com/GoogleContainerTools/kaniko#kaniko---build-images-in-kubernetes), while collecting build-info and storing it in Artifactory. +For detailed instructions, please refer to our [buildx project example on GitHub](https://github.com/jfrog/project-examples/tree/master/docker-oci-examples/fat-manifest-example). + +#### Pushing Docker Images Using the OpenShift CLI + +JFrog CLI allows pushing containers to Artifactory using the [OpenShift CLI](https://docs.openshift.com/container-platform/4.2/cli_reference/openshift_cli/getting-started-cli.html), while collecting build-info and storing it in Artifactory. +For detailed instructions, please refer to our [OpenShift build project example on GitHub](https://github.com/jfrog/project-examples/tree/master/docker-oci-examples/openshift-examples/openshift-build-example). + + + +#### Adding Published Docker Images to the Build-Info + +The **build-docker-create** command allows adding a docker image, which is already published to Artifactory, into the build-info. This build-info can be later published to Artifactory, using the **build-publish** command. + + + +| | | +|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | rt build-docker-create | +| Abbreviation | rt bdc | +| Command options | | +| --image-file | Path to a file which includes one line in the following format: IMAGE-TAG@sha256:MANIFEST-SHA256. For example:

cat image-file-details
superfrog-docker.jfrog.io/hello-frog@sha256:30f04e684493fb5ccc030969df6de0 | +| --server-id | \[Optional\]

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](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --build-number | \[Optional\]

Build number. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --project | \[Optional\]

JFrog project key. | +| --module | \[Optional\]

Optional module name for the build-info. | +| --skip-login | \[Default: false\]

Set to true if you'd like the command to skip performing docker login. | +| --threads | \[Default: 3\]

Number of working threads. | +| Command argument | | +| Target repository | The name of the repository to which the image was pushed. | + +##### Examples +``` +jf rt bdc docker-local --image-file image-file-details --build-name myBuild --build-number 1 +``` +You can then publish the build-info collected by the **podman-push** command to Artifactory using the [build-publish](https://jfrog.com/help/r/jfrog-cli/publishing-build-info) command. + + + +#### Promoting Docker Images + +Promotion is the action of moving or copying a group of artifacts from one repository to another, to support the artifacts' lifecycle. When it comes to docker images, there are two ways to promote a docker image which was pushed to Artifactory: + +1. Create build-info for the docker image, and then promote the build using the **jf rt build-promote** command. +2. Use the **jf rt docker-promote** command as described below. + +The following table lists the command arguments and flags: + +| | | +|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | rt docker-promote | +| Abbreviation | rt dpr | +| Command options | | +| --server-id | \[Optional\]

Server ID configured using the config command. If not specified, the default configured Artifactory server is used. | +| --copy | \[Default: false\]

If set true, the Docker image is copied to the target repository, otherwise it is moved. | +| --source-tag | \[Optional\]

The tag name to promote. | +| --target-docker-image | \[Optional\]

Docker target image name. | +| --target-tag | \[Optional\]

The target tag to assign the image after promotion. | +| Command argument | | +| source docker image | The docker image name to promote. | +| source repository | Source repository in Artifactory. | +| target repository | Target repository in Artifactory. | + +##### Examples + +Promote the **hello-world** docker image from the **docker-dev-local** repository to the **docker-staging-local** repository. +``` +jf rt docker-promote hello-world docker-dev-local docker-staging-local +``` + + +### Building Npm Packages Using the Npm Client + +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: + +* 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 [Deploying to a Virtual Repository](https://jfrog.com/help/r/jfrog-artifactory-documentation/virtual-repositories). +* When the **npm-publish** command runs, JFrog CLI runs the **pack** command in the background. The pack action is followed by an upload, which is not based on the npm client's publish command. Therefore, If your npm package includes the **prepublish** or **postpublish** scripts, rename them to **prepack** and **postpack** respectively. + + +##### Requirements + +Npm client version 5.4.0 and above. + +Artifactory version 5.5.2 and above. + +#### Setting npm repositories + +Before using the **npm-install**, **npm-ci** and **npm-publish** commands, the project needs to be pre-configured with the Artifactory server and repositories, to be used for building and publishing the project. The **npm-config** command should be used once to add the configuration to the project. The command should run while inside the root directory of the project. The configuration is stored by the command in the **.jfrog** directory at the root directory of the project. + +| | | +|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | npm-config | +| Abbreviation | npmc | +| Command options | | +| --global | \[Optional\]

Set to true, if you'd like the configuration to be global (for all projects on the machine). Specific projects can override the global configuration. | +| --server-id-resolve | \[Optional\]

Artifactory server ID for resolution. The server should configured using the 'jfrog c add' command. | +| --server-id-deploy | \[Optional\]

Artifactory server ID for deployment. The server should be configured using the 'jfrog c add' command. | +| --repo-resolve | \[Optional\]

Repository for dependencies resolution. | +| --repo-deploy | \[Optional\]

Repository for artifacts deployment. | +| Command arguments | The command accepts no arguments | + +#### Installing Npm Packages + +The **npm-install** and **npm-ci** commands execute npm's **install** and **ci** commands respectively, to fetches the npm dependencies from the npm repositories. + +Before running the **npm-install** or **npm-ci** command on a project for the first time, the project should be configured using the **npm-config** command. + +The following table lists the command arguments and flags: + +| | | +|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | npm | +| Abbreviation | | +| Command options | | +| --build-name | \[Optional\]

Build name. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --build-number | \[Optional\]

Build number. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --project | \[Optional\]

JFrog project key. | +| --module | \[Optional\]

Optional module name for the build-info. | +| --threads | \[Default: 3\]

Number of working threads for build-info collection. | +| Command arguments | The command accepts the same arguments and options as the npm client. | + +##### 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](https://jfrog.com/help/r/jfrog-cli/publishing-build-info) command. The dependencies are resolved from the Artifactory server and repository configured by **npm-config** command. +``` +jf npm install --build-name=my-build-name --build-number=1 +``` + +##### Example 2 + +The following example installs the dependencies. The dependencies are resolved from the Artifactory server and repository configured by **npm-config** command. +``` +jf npm install +``` + +##### Example 3 + +The following example installs the dependencies using the npm-ci command. The dependencies are resolved from the Artifactory server and repository configured by **npm-config** command. +``` +jf npm ci +``` + + +#### Publishing the Npm Packages into Artifactory + +The **npm-publish** command packs and deploys the npm package to the designated npm repository. + +Before running the **npm-publish** command on a project for the first time, the project should be configured using the **npm-config** command. This configuration includes the Artifactory server and repository to which the package should deploy. + +> **Warning**: 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 | | +| Command options | | +| --build-name | \[Optional\]

Build name. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --build-number | \[Optional\]

Build number. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --project | \[Optional\]

JFrog project key. | +| --module | \[Optional\]

Optional module name for the build-info. | +| --detailed-summary | \[Default: false\]

Set true to include a list of the affected files as part of the command output summary. | +| --scan | \[Default: false\]

Set if you'd like all files to be scanned by Xray on the local file system prior to the upload, and skip the upload if any of the files are found vulnerable. | +| --format | \[Default: table\]

Should be used with the --scan option. Defines the scan output format. Accepts table or JSON as values. | +| Command argument | The command accepts the same arguments and options that the **npm pack** command expects. | + +##### 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](https://jfrog.com/help/r/jfrog-cli/publishing-build-info) command. The package is published to the Artifactory server and repository configured by **npm-config** command. +``` +jf npm publish --build-name=my-build-name --build-number=1 +``` + +### Building Npm Packages Using the Yarn Client + +JFrog CLI provides full support for building npm packages using the yarn client. This allows you to resolve npm dependencies, while collecting build-info and storing it in Artifactory. You can download npm packages from any npm repository type - local, remote or virtual. Publishing the packages to a local npm repository is supported through the **jf rt upload** command. + +Yarn version 2.4.0 and above is supported. + +#### Setting npm repositories + +Before using the **jf yarn** command, the project needs to be pre-configured with the Artifactory server and repositories, to be used for building the project. The **yarn-config** command should be used once to add the configuration to the project. The command should run while inside the root directory of the project. The configuration is stored by the command in the **.jfrog** directory at the root directory of the project. + +| | | +|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | yarn-config | +| Abbreviation | yarnc | +| Command options | | +| --global | \[Optional\]

Set to true, if you'd like the configuration to be global (for all projects on the machine). Specific projects can override the global configuration. | +| --server-id-resolve | \[Optional\]

Artifactory server ID for resolution. The server should configured using the 'jf c add' command. | +| --repo-resolve | \[Optional\]

Repository for dependencies resolution. | +| Command arguments | The command accepts no arguments | + +#### Installing Npm Packages + +The **jf yarn** command executes the yarn client, to fetch the npm dependencies from the npm repositories. + +> **Note**: Before running the command on a project for the first time, the project should be configured using the **yarn-config** command. + +The following table lists the command arguments and flags: + +| | | +|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | yarn | +| Command options | | +| --build-name | \[Optional\]

Build name. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --build-number | \[Optional\]

Build number. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --project | \[Optional\]

JFrog project key. | +| --module | \[Optional\]

Optional module name for the build-info. | +| --threads | \[Default: 3\]

Number of working threads for build-info collection. | +| Command arguments | The command accepts the same arguments and options as the yarn client. | + +##### 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](https://jfrog.com/help/r/jfrog-cli/publishing-build-info) command. The dependencies are resolved from the Artifactory server and repository configured by **yarn-config command. +``` +jf yarn install --build-name=my-build-name --build-number=1 +``` + + +Example 2 + +The following example installs the dependencies. The dependencies are resolved from the Artifactory server and repository configured by **yarn-config command. +``` +jf yarn install +``` + + +### Building Go Packages + +#### General + +JFrog CLI provides full support for building Go packages using the Go client. This allows resolving Go dependencies from and publish your Go packages to Artifactory, while collecting build-info and storing it in Artifactory. + +#### Requirements + +JFrog CLI client version 1.20.0 and above. + +Artifactory version 6.1.0 and above. + +Go client version 1.11.0 and above. + +#### Example project + +To help you get started, you can use [this sample project on GitHub](https://github.com/jfrog/project-examples/tree/master/golang-example). + +#### Setting Go repositories + +Before you can use JFrog CLI to build your Go projects with Artifactory, you first need to set the resolutions and deployment repositories for the project. + +Here's how you set the repositories. + +1. 'cd' into to the root of the Go project. +2. Run the **jf rt go-config** command. + +| | | +|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | go-config | +| Abbreviation | | +| Command options | | +| --global | \[Default false\]

Set to true, if you'd like the configuration to be global (for all projects on the machine). Specific projects can override the global configuration. | +| --server-id-resolve | \[Optional\]

Artifactory server ID for resolution. The server should configured using the 'jf c add' command. | +| --server-id-deploy | \[Optional\]

Artifactory server ID for deployment. The server should be configured using the 'jf c add' command. | +| --repo-resolve | \[Optional\]

Repository for dependencies resolution. | +| --repo-deploy | \[Optional\]

Repository for artifacts deployment. | + +##### Examples + +##### Example 1 + +Set repositories for this go project. +``` +jf go-config +``` + +##### Example 2 + +Set repositories for all go projects on this machine. +``` +jf go-config --global +``` + + +#### Running Go commands + +The **go** command triggers the go client. + +> **Note**: Before running the **go** command on a project for the first time, the project should be configured using the **go-config** command. + +The following table lists the command arguments and flags: + + + +| | | +|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | go | +| Abbreviation | go | +| Command options | | +| --build-name | \[Optional\]

Build name. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --build-number | \[Optional\]

Build number. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --project | \[Optional\]

JFrog project key. | +| --no-fallback | \[Default: false\]

Set to avoid downloading packages from the VCS, if they are missing in Artifactory. | +| --module | \[Optional\]

Optional module name for the build-info. | +| Command arguments | | +| Go command | The command accepts the same arguments and options as the go client. | + +##### Examples + +##### Example 1 + +The following example runs Go build command. The dependencies resolved from Artifactory via the go-virtual repository. + +> **Note**: Before using this example, please make sure to set repositories for the Go project using the go-config command. + +``` +jf rt go build +``` + +##### 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](https://jfrog.com/help/r/jfrog-cli/publishing-build-info)command. + +> **Note**: Before using this example, please make sure to set repositories for the Go project using the go-config command. +``` +jf rt go build --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. + +> **Note**: Before running the **go-publish** command on a project for the first time, the project should be configured using the **go-config** command. + +The following table lists the command arguments and flags: + + + +| | | +|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | go-publish | +| Abbreviation | gp | +| Command options | | +| --build-name | \[Optional\]

Build name. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --build-number | \[Optional\]

Build number. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --project | \[Optional\]

JFrog project key. | +| --module | \[Optional\]

Optional module name for the build-info. | +| --detailed-summary | \[Default: false\]

Set true to include a list of the affected files as part of the command output summary. | +| Command argument | | +| Version | The version of the Go project that is being published | + +##### Examples + +##### Example 1 + +To pack and publish the Go package, run the following command. Before running this command on a project for the first time, the project should be configured using the **go-config** command. +``` +jf gp v1.2.3 +``` + +##### Example 2 + +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](https://jfrog.com/help/r/jfrog-cli/publishing-build-info) command. Before running this command on a project for the first time, the project should be configured using the **go-config** command. +``` +jf gp v1.2.3 --build-name my-build-name --build-number 1 +``` + +### Building Python Packages + +JFrog CLI provides full support for building Python packages using the **pip** and **pipenv** and poetry package installers. This allows resolving python dependencies from Artifactory, while recording the downloaded packages. The downloaded packages are stored as dependencies in the build-info stored in Artifactory. + +Once the packages are installed, the Python project can be then built and packaged using the pip, pipenv or poetry clients. Once built, the produced artifacts can be uploaded to Artifactory using JFrog CLI's upload command and registered as artifacts in the build-info. + +#### Example projects + +To help you get started, you can use [the sample projects on GitHub](https://github.com/jfrog/project-examples/tree/master/python-example). + +#### Setting Python repository + +Before you can use JFrog CLI to build your Python projects with Artifactory, you first need to set the repository for the project. + +Here's how you set the repositories. + +1. 'cd' into the root of the Python project. +2. Run the**jf pip-config**, **jf pipenv-config** or **jf poetry-configc** commands, depending on whether you're using the pip or pipenv clients. + +| | | +|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | pip-config / pipenv-config / poetry-config | +| Abbreviation | pipc / pipec / poc | +| Command options | | +| --global | \[Default false\]

Set to true, if you'd like the configuration to be global (for all projects on the machine). Specific projects can override the global configuration. | +| --server-id-resolve | \[Optional\]

Artifactory server ID for resolution. The server should configured using the 'jf c add' command. | +| --repo-resolve | \[Optional\]

Repository for dependencies resolution. | + +##### Examples + +##### Example 1 + +Set repositories for this Python project when using the pip client. +``` +jf pipc +``` + +##### Example 2 + +Set repositories for all Python projects using the pip client on this machine. +``` +jf pipc --global +``` + +##### Example 3 + +Set repositories for this Python project when using the pipenv client. +``` +jf pipec +``` + +##### Example 4 + +Set repositories for all Python projects using the poetry client on this machine. +``` +jf poc --global +``` + +##### Example 5 + +Set repositories for this Python project when using the poetry client. +``` +jf poc +``` + +##### Example 6 + +Set repositories for all Python projects using the pipenv client on this machine. +``` +jf pipec --global +``` + +#### Installing Python packages + +The **pip install**, **pipenv install** and **poetry install** commands use the **pip**, **pipenv** and **poetry** clients respectively, to install the project dependencies from Artifactory. The commands can also record these packages as build dependencies as part of the build-info published to Artifactory. + +> **Note**: Before running the **pip install**, **pipenv install** and **poetry install** commands on a project for the first time, the project should be configured using the **pip-config** ,**pipenv-config** or **poetry-config** commands respectively. + +**Recording all dependencies** +JFrog CLI records the installed packages as build-info dependencies. The recorded dependencies are packages installed during the **jf rt pip-install** command execution. When running the command inside a Python environment, which already has some of the packages installed, the installed packages will not be included as part of the build-info, because they were not originally installed by JFrog CLI. A warning message will be added to the log in this case. +**How to include all packages in the build-info?** + +The details of all the installed packages are always cached by the **jf pip install** and **jf pipenv install** command in the **.jfrog/projects/deps.cache.json** file, located under the root of the project. JFrog CLI uses this cache for including previously installed packages in the build-info. +If the Python environment had some packages installed prior to the first execution of the install command, those previously installed packages will be missing from the cache and therefore will not be included in the build-info. + +Running the install command with both the **no-cache-dir** and **force-reinstall** pip options, should re-download and install these packages, and they will therefore be included in the build-info and added to the cache. It is also recommended to run the command from inside a [virtual environment](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/). + + +| | | +|------------------|------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | pip / pipenv / poetry | +| Abbreviation | | +| Command options | | +| --build-name | \[Optional\]

Build name. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --build-number | \[Optional\]

Build number. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --project | \[Optional\]

JFrog project key. | +| --module | \[Optional\]

Optional module name for the build-info. | +| Command argument | | +| Pip arguments | Arguments and options for the pip-install command. | + + + +##### Examples + +Example 1 + +The following command triggers pip install, while recording the build dependencies as part of build name **my-build** and build number **1** . +``` +jf pip install . --build-name my-build --build-number 1 +``` + +Example 2 + +The following command triggers pipenv install, while recording the build dependencies as part of build name **my-build** and build number **1** . +``` +jf pipenv install . --build-name my-build --build-number 1 +``` + +Example 3 + +The following are command triggers poetry install, while recording the build dependencies as part of build name **my-build** and build number **1** . +``` +jf poetry install . --build-name my-build --build-number 1 +``` +### Building NuGet Packages + +JFrog CLI provides full support for restoring NuGet packages using the NuGet client or the .NET Core CLI. 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 `jf nuget` command, which uses the NuGet client or the `jf dotnet` command, which uses the .NET Core CLI. + +To publish your NuGet packages to Artifactory, use the [jf rt upload](https://jfrog.com/help/r/jfrog-cli/uploading-files) command. + +#### Setting NuGet repositories + +Before using the**nuget** or **dotnet** commands, the project needs to be pre-configured with the Artifactory server and repository, to be used for building the project. + +Before using the nuget or dotnet commands, the **nuget-config** or **dotnet-config** commands should be used respectively. These commands configure the project with the details of the Artifactory server and repository, to be used for the build. The **nuget-config** or **dotnet-config** commands should be executed while inside the root directory of the project. The configuration is stored by the command in the **.jfrog** directory at the root directory of the project. You then have the option of storing the .jfrog directory with the project sources, or creating this configuration after the sources are checked out. + +The following table lists the commands' options: + +| | | +|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | nuget-config / dotnet-config | +| Abbreviation | nugetc / dotnetc | +| Command options | | +| --global | \[Optional\]

Set to true, if you'd like the configuration to be global (for all projects on the machine). Specific projects can override the global configuration. | +| --server-id-resolve | \[Optional\]

Artifactory server ID for resolution. The server should configured using the 'jf c add' command. | +| --repo-resolve | \[Optional\]

Repository for dependencies resolution. | +| --nuget-v2 | \[Default: false\]
Set to true if you'd like to use the NuGet V2 protocol when restoring packages from Artifactory (instead of NuGet V3). | +| Command arguments | The command accepts no arguments | + +#### Running Nuget and Dotnet commands + +The **nuget** command runs the **NuGet client** and the **dotnet** command runs the **.NET Core CLI. + +> Before running the nuget command on a project for the first time, the project should be configured using the nuget-config command. + +> Before running the dotnet command on a project for the first time, the project should be configured using the dotnet-config command. + +The following table lists the commands arguments and options: + +| | | +|------------------|------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | nuget / dotnet | +| Abbreviation | | +| Command options | | +| --build-name | \[Optional\]

Build name. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --build-number | \[Optional\]

Build number. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --project | \[Optional\]

JFrog project key. | +| --module | \[Optional\]

Optional module name for the build-info. | +| Command argument | The command accepts the same arguments and options as the NuGet client / .NET Core CLI. | + +##### Examples + +##### Example 1 + +Run nuget restore for the solution at the current directory, while resolving the NuGet dependencies from the pre-configured Artifactory repository. Use the NuGet client for this command +``` +jf nuget restore +``` + +##### Example 2 + +Run dotnet restore for the solution at the current directory, while resolving the NuGet dependencies from the pre-configured Artifactory repository. Use the .NET Core CLI for this command +``` +jf dotnet restore +``` + +##### Example 3 + +Run dotnet restore for the solution at the current directory, while resolving the NuGet dependencies from the pre-configured Artifactory repository. + +In addition, record the build-info as part of build **my-build-name/1**. The build-info can later be published to Artifactory using the [build-publish](https://jfrog.com/help/r/jfrog-cli/publishing-build-info) command: +``` +jf dotnet restore --build-name=my-build-name --build-number=1 +``` + +### Packaging and Publishing Terraform Modules + +JFrog CLI supports packaging Terraform modules and publishing them to a Terraform repository in Artifactory using the **jf terraform publish** command. + +We recommend using [this example project on GitHub](https://github.com/jfrog/project-examples/tree/master/terraform-example) for an easy start up. + +Before using the **jf terraform publish** command for the first time, you first need to configure the Terraform repository for your Terraform project. To do this, follow these steps: + +1. 'cd' into the root directory for your Terraform project. +2. Run the interactive **jf terraform-config** command and set deployment repository name. + +The **jf terraform-config** command will store the repository name inside the **.jfrog** directory located in the current directory. You can also add the **--global** command option, if you prefer the repository configuration applies to all projects on the machine. In that case, the configuration will be saved in JFrog CLI's home directory. + +The following table lists the command options: + +| | | +|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | terraform-config | +| Abbreviation | tfc | +| Command options | | +| --global | \[Optional\]

Set to true, if you'd like the configuration to be global (for all projects on the machine). Specific projects can override the global configuration. | +| --server-id-deploy | \[Optional\]

Artifactory server ID for deployment. The server should configured using the 'jf c add' command. | +| --repo-deploy | \[Optional\]

Repository for artifacts deployment. | +| Command arguments | The command accepts no arguments | + +##### Examples + +##### Example 1 + +Configuring the Terraform repository for a project, while inside the root directory of the project +``` +jf tfc +``` + +##### Example 2 + +Configuring the Terraform repository for all projects on the machine +``` +jf tfc --global +``` + + +The **terraform publish** command creates a terraform package for the module in the current directory, and publishes it to the configured Terraform repository in Artifactory. + +The following table lists the commands arguments and options: + +| | | +|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | terraform publish | +| Abbreviation | tf p | +| Command options | | +| --namespace | \[Mandatory\]

Terraform module namespace | +| --provider | \[Mandatory\]

Terraform module provider | +| --tag | \[Mandatory\]

Terraform module tag | +| --exclusions | \[Optional\]

A list of Semicolon-separated exclude patterns wildcards. Paths inside the module matching one of the patterns are excluded from the deployed package. | +| --build-name | \[Optional\]

Build name. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --build-number | \[Optional\]

Build number. For more details, please refer to [Build Integration](https://jfrog.com/help/r/jfrog-cli/build-integration). | +| --project | | +| Command argument | The command accepts no arguments | + +##### Examples + +##### Example 1 + +The command creates a package for the Terraform module in the current directory, and publishes it to the Terraform repository (configured by the **jf tfc command**) with the provides namespace, provider and tag. +``` +jf tf p --namespace example --provider aws --tag v0.0.1 +``` + +##### Example 2 + +The command creates a package for the Terraform module in the current directory, and publishes it to the Terraform repository (configured by the **jf tfc command**) with the provides namespace, provider and tag. The published package will not include the module paths which include either **test** or **ignore** . +``` +jf tf p --namespace example --provider aws --tag v0.0.1 --exclusions "\*test\*;\*ignore\*" +``` + +##### Example 3 + +The command creates a package for the Terraform module in the current directory, and publishes it to the Terraform repository (configured by the **jf tfc** command) with the provides namespace, provider and tag. The published module will be recorded as an artifact of a build named **my-build** with build number **1**. The **jf rt bp** command publishes the build to Artifactory. +``` +jf tf p --namespace example --provider aws --tag v0.0.1 --build-name my-build --build-number 1 +jf rt bp my-build 1 +``` + +## Managing Configuration Entities + +JFrog CLI offers a set of commands for managing Artifactory configuration entities. + +### Creating Users + +This command allows creating a bulk of users. The details of the users are provided in a CSV format file. Here's the file format. +``` +"username","password","email" +"username1","password1","john@c.com" +"username2","password1","alice@c.com" +``` + +> **Note**: The first line in the CSV is cells' headers. It is mandatory and is used by the command to map the cell value to the users' details. + +The CSV can include additional columns, with different headers, which will be ignored by the command. + +| | | +|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | rt users-create | +| Abbreviation | rt uc | +| Command options | | +| --server-id | \[Optional\]

Artifactory server ID configured using the config command. | +| --csv | \[Mandatory\]

Path to a CSV file with the users' details. The first row of the file should include the name,password,email headers. | +| --replace | \[Optional\]

Set to true if you'd like existing users or groups to be replaced. | +| --users-groups | \[Optional\]

A list of comma-separated groups for the new users to be associated to. | +| Command arguments | The command accepts no arguments | + +##### Example + +Create new users according to details defined in the path/to/users.csv file. +``` +jf rt users-create --csv path/to/users.csv +``` + + +### Deleting Users + +This command allows deleting a bulk of users. The command a list of usernames to delete. The list can be either provided as a comma-seperated argument, or as a CSV file, which includes one column with the usernames. Here's the CSV format. +``` +"username" +"username1" +"username2" +"username2" +``` + +The first line in the CSV is cells' headers. It is mandatory and is used by the command to map the cell value to the users' details. + +The CSV can include additional columns, with different headers, which will be ignored by the command. + +| | | +|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | rt users-delete | +| Abbreviation | rt udel | +| Command options | | +| --server-id | \[Optional\]

Artifactory server ID configured using the config command. | +| --csv | \[Optional\]

Path to a csv file with the usernames to delete. The first row of the file is the reserved for the cells' headers. It must include the "username" header. | +| Command arguments | | +| users list | Comma-separated list of usernames to delete. If the --csv command option is used, then this argument becomes optional. | + +##### Example 1 + +Delete the users according to the usernames defined in the path/to/users.csv file. +``` +jf rt users-delete --csv path/to/users.csv +``` + +##### Example 2 + +Delete the users according to the u1, u2 and u3 usernames. +``` +jf rt users-delete "u1,u2,u3" +``` + +### Creating Groups + +This command creates a new users group. + +| | | +|-------------------|--------------------------------------------------------------------------------| +| Command-name | rt group-create | +| Abbreviation | rt gc | +| Command options | | +| --server-id | \[Optional\]

Artifactory server ID configured using the config command. | +| Command arguments | | +| group name | The name of the group to create. | + +##### Example + +Create a new group name **reviewers** . +``` +jf rt group-create reviewers +``` + +### Adding Users to Groups + +This command adds a list fo existing users to a group. + +| | | +|-------------------|--------------------------------------------------------------------------------| +| Command-name | rt group-add-users | +| Abbreviation | rt gau | +| Command options | | +| --server-id | \[Optional\]

Artifactory server ID configured using the config command. | +| Command arguments | | +| group name | The name of the group to add users to. | +| users list | Comma-seperated list of usernames to add to the specified group. | + +##### Example + +Add to group reviewers the users with the following usernames: u1, u2 and u3. +``` +jf rt group-add-users "reviewers" "u1,u2,u3" +``` + +### Deleting Groups + +This command deletes a group. + +| | | +|-------------------|--------------------------------------------------------------------------------| +| Command-name | rt group-delete | +| Abbreviation | rt gdel | +| Command options | | +| --server-id | \[Optional\]

Artifactory server ID configured using the config command. | +| Command arguments | | +| group name | The name of the group to delete. | + +##### Example + +Delete the **reviewers** group. +``` +jf rt group-delete "reviewers" +``` + +### Managing Repositories + +JFrog CLI offers a set of commands for managing Artifactory repositories. You can create, update and delete repositories. To make it easier to manage repositories, the commands which create and update the repositories accept a pre-defined configuration template file. This template file can also include variables. which can be later replaced with values, when creating or updating the repositories. The configuration template file is created using the **jf rt repo-template** command. + +#### Creating or Configuration Template + +This is an interactive command, which creates a configuration template file. This file should be used as an argument for the **jf rt repo-create** or the **jf rt repo-update** commands. + +When using this command to create the template, you can also provide replaceable variable, instead of fixes values. Then, when the template is used to create or update repositories, values can be provided to replace the variables in the template. + +| | | +|-------------------|---------------------------------------------------------------------------------------------------------------| +| Command-name | rt repo-template | +| Abbreviation | rt rpt | +| Command options | The command has no options. | +| Command arguments | | +| template path | Specifies the local file system path for the template file created by the command. The file should not exist. | + +##### Example + +Create a configuration template, with a variable for the repository name. Then, create a repository using this template, and provide repository name to replace the variable. +``` +$ jf rt repo-template template.json + +Select the template type (press Tab for options): create +Insert the repository key > ${repo-name} +Select the repository class (press Tab for options): local +Select the repository's package type (press Tab for options): generic +You can type ":x" at any time to save and exit. +Select the next configuration key (press Tab for options): :x +[Info] Repository configuration template successfully created at template.json. +$ +$ jf rt repo-create template.json --vars "repo-name=my-repo" +[Info] Creating local repository... +[Info] Done creating repository. +``` + +#### Creating / Updating Repositories + +These two commands create a new repository and updates an existing a repository. Both commands accept as an argument a configuration template, which can be created by the **jf rt repo-template** command. The template also supports variables, which can be replaced with values, provided when it is used. + +| | | +|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | rt repo-create / rt repo-update | +| Abbreviation | rt rc / rt ru | +| Command options | | +| --server-id | \[Optional\]

Artifactory server ID configured using the config command. | +| --vars | \[Optional\]

List of variables in the form of "key1=value1;key2=value2;..." to be replaced in the template. In the template, the variables should be used as follows: ${key1}. | +| Command arguments | | +| template path | Specifies the local file system path for the template file to be used for the repository creation. The template can be created using the "jf rt rpt" command. | + +##### Example 1 + +Create a repository, using the **template.json** file previously generated by the **repo-template** command. +``` +jf rt repo-create template.json +``` + +##### Example 2 + +Update a repository, using the **template.json** file previously generated by the **repo-template** command. +``` +jf rt repo-update template.json +``` + +##### Example 3 + +Update a repository, using the **template.json** file previously generated by the **repo-template** command. Replace the repo-name variable inside the template with a name for the updated repository. +``` +jf rt repo-update template.json --vars "repo-name=my-repo" +``` + +#### Deleting Repositories + +This command permanently deletes a repository, including all of its content. + +| | | +|-------------------|------------------------------------------------------------------------------------------------------------| +| Command name | rt repo-delete | +| Abbreviation | rt rdel | +| Command options | | +| --server-id | \[Optional\]

Artifactory server ID configured using the config command. | +| --quiet | \[Default: $CI\]

Set to true to skip the delete confirmation message. | +| Command arguments | | +| repository key | Specifies the repositories that should be removed. You can use wildcards to specify multiple repositories. | + +##### Example + +Delete a repository from Artifactory. +``` +jf rt repo-delete generic-local +``` + +### Managing Replications + +JFrog CLI offers commands creating and deleting replication jobs in Artifactory. To make it easier to create replication jobs, the commands which creates the replication job accepts a pre-defined configuration template file. This template file can also include variables. which can be later replaced with values, when creating the replication job. The configuration template file is created using the **jf rt replication-template** command. + +### Creating a Configuration Template + +This command creates a configuration template file, which should be used as an argument for the **jf rt replication-create** command. + +When using this command to create the template, you can also provide replaceable variable, instead of fixes values. Then, when the template is used to create replication jobs, values can be provided to replace the variables in the template. + +| | | +|-------------------|---------------------------------------------------------------------------------------------------------------| +| Command-name | rt replication-template | +| Abbreviation | rt rplt | +| Command options | The command has no options. | +| Command arguments | | +| template path | Specifies the local file system path for the template file created by the command. The file should not exist. | + +##### Example + +Create a configuration template, with two variables for the source and target repositories. Then, create a replication job using this template, and provide source and target repository names to replace the variables. +``` +$ jf rt rplt template.json +Select replication job type (press Tab for options): push +Enter source repo key > ${source} +Enter target repo key > ${target} +Enter target server id (press Tab for options): my-server-id +Enter cron expression for frequency (for example, 0 0 12 * * ? will replicate daily) > 0 0 12 * * ? +You can type ":x" at any time to save and exit. +Select the next property > :x +[Info] Replication creation config template successfully created at template.json. +$ +$ jf rt rplc template.json --vars "source=generic-local;target=generic-local" +[Info] Done creating replication job. +``` + + +#### Creating Replication Jobs + +This command creates a new replication job for a repository. The command accepts as an argument a configuration template, which can be created by the **jf rt replication-template** command. The template also supports variables, which can be replaced with values, provided when it is used. + +| | | +|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | replication-create | +| Abbreviation | rt rplc | +| Command options | | +| --server-id | \[Optional\]

Artifactory server ID configured using the config command. | +| --vars | \[Optional\]

List of variables in the form of "key1=value1;key2=value2;..." to be replaced in the template. In the template, the variables should be used as follows: ${key1}. | +| Command arguments | | +| template path | Specifies the local file system path for the template file to be used for the replication job creation. The template can be created using the "jf rt rplt" command. | + +##### Example 1 + +Create a replication job, using the **template.json** file previously generated by the **replication-template** command. +``` +jf rt rplc template.json +``` + +##### Example 2 + +Update a replication job, using the **template.json** file previously generated by the **replication-template** command. Replace the source and target variables inside the template with the names of the replication source and target repositories. +``` +jf rt rplc template.json --vars "source=my-source-repo;target=my-target-repo" +``` + +#### Deleting Replication jobs + +This command permanently deletes a replication jobs from a repository. + +| | | +|-------------------|--------------------------------------------------------------------------------| +| Command name | rt replication-delete | +| Abbreviation | rt rpldel | +| Command options | | +| --server-id | \[Optional\]

Artifactory server ID configured using the config command. | +| --quiet | \[Default: $CI\]

Set to true to skip the delete confirmation message. | +| Command arguments | | +| repository key | The repository from which the replications will be deleted. | + +##### Example + +Delete a repository from Artifactory. +``` +jf rt rpldel my-repo-name +``` + +### Managing Permission Targets + +JFrog CLI offers commands creating, updating and deleting permission targets in Artifactory. To make it easier to create and update permission targets, the commands which create and update the permission targets accept a pre-defined configuration template file. This template file can also include variables. which can be later replaced with values, when creating or updating the permission target. The configuration template file is created using the **jf rt permission-target-template** command. + +#### Creating a Configuration Template + +This command creates a configuration template file, which should be used as an argument for the **jf rt permission-target-create** and **jf rt permission-target-update** commands. + +| | | +|-------------------|---------------------------------------------------------------------------------------------------------------| +| Command-name | rt permission-target-template | +| Abbreviation | rt ptt | +| Command options | The command has no options. | +| Command arguments | | +| template path | Specifies the local file system path for the template file created by the command. The file should not exist. | + +#### Creating / Updating Permission Targets + +This command creates a new permission target. The command accepts as an argument a configuration template, which can be created by the **jf rt permission-target-template** command. The template also supports variables, which can be replaced with values, provided when it is used. + +| | | +|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | permission-target-create / permission-target-update | +| Abbreviation | rt ptc / rt ptu | +| Command options | | +| --server-id | \[Optional\]

Artifactory server ID configured using the config command. | +| --vars | \[Optional\]

List of variables in the form of "key1=value1;key2=value2;..." to be replaced in the template. In the template, the variables should be used as follows: ${key1}. | +| Command arguments | | +| template path | Specifies the local file system path for the template file to be used for the permission target creation or update. The template can be created using the "jf rt ptt" command. | + +#### Deleting Permission Targets + +This command permanently deletes a permission target. + +| | | +|------------------------|--------------------------------------------------------------------------------| +| Command name | rt permission-target-delete | +| Abbreviation | rt ptdel | +| Command options | | +| --server-id | \[Optional\]

Artifactory server ID configured using the config command. | +| --quiet | \[Default: $CI\]

Set to true to skip the delete confirmation message. | +| Command arguments | | +| permission target name | The permission target that should be removed. | + +## 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. Similarly, you can **create and update release bundles** by providing the `--spec` command option. 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 and the file specs, then the inline options override their counterparts specified in the file specs. + +### File Spec Schemas + +#### Copy and Move Commands Spec Schema + +The file spec schema for the copy and move commands is as follows: +``` +{ + "files": [ + { + "pattern" or "aql": "[Mandatory]", + "target": "[Mandatory]", + "props": "[Optional]", + "excludeProps": "[Optional]", + "recursive": "[Optional, Default: 'true']", + "flat": "[Optional, Default: 'false']", + "exclusions": "[Optional, Applicable only when 'pattern' is specified]", + "archiveEntries": "[Optional]", + "build": "[Optional]", + "bundle": "[Optional]", + "validateSymlinks": "[Optional]", + "sortBy": "[Optional]", + "sortOrder": "[Optional, Default: 'asc']", + "limit": "[Optional], + "offset": [Optional] } + ] +} +``` + +#### Download Command Spec Schema + +The file spec schema for the download command is as follows: +``` +{ + "files": [ + { + "pattern" or "aql": "[Mandatory]", + "target": "[Optional]", + "props": "[Optional]", + "excludeProps": "[Optional]", + "recursive": "[Optional, Default: 'true']", + "flat": "[Optional, Default: 'false']", + "exclusions": "[Optional, Applicable only when 'pattern' is specified]", + "archiveEntries": "[Optional]", + "build": "[Optional]", + "bundle": "[Optional]", + "sortBy": "[Optional]", + "sortOrder": "[Optional, Default: 'asc']", + "limit": [Optional], + "offset": [Optional] } + ] +} +``` + +#### Create and Update Release Bundle Commands Spec Schema + +The file spec schema for the create and update release bundle commands is as follows: +``` +{ +"files": [ + { + "pattern" or "aql": "[Mandatory]", + "target": "[Optional]", + "props": "[Optional]", + "targetProps": "[Optional]", + "excludeProps": "[Optional]", + "recursive": "[Optional, Default: 'true']", + "flat": "[Optional, Default: 'false']", + "exclusions": "[Optional, Applicable only when 'pattern' is specified]", + "archiveEntries": "[Optional]", + "build": "[Optional]", + "bundle": "[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]", + "targetProps": "[Optional]", + "recursive": "[Optional, Default: 'true']", + "flat": "[Optional, Default: 'true']", + "regexp": "[Optional, Default: 'false']", + "ant": "[Optional, Default: 'false']", + "archive": "[Optional, Must be: 'zip']", + "exclusions": "[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]", + "excludeProps": "[Optional]", + "recursive": "[Optional, Default: 'true']", + "exclusions": "[Optional, Applicable only when 'pattern' is specified]", + "archiveEntries": "[Optional]", + "build": "[Optional]", + "bundle": "[Optional]", + "sortBy": "[Optional]", + "sortOrder": "[Optional, Default: 'asc']", + "limit": [Optional], + "offset": [Optional] } + ] +} +``` + +##### Examples + +The following examples can help you get started using File Specs. + +##### Example 1: + +Download all files located under the **all-my-frogs** directory in the **my-local-repo** repository to the **froggy** 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** 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 + +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": "all-my-frogs/zip/", + "props": "type=zip;status=ready" + }, + { + "pattern": "resources/*.tgz", + "target": "all-my-frogs/tgz/", + "props": "type=tgz;status=ready" + } + ] +} +``` + +##### Example 5: + +Upload all zip files located under the **resources** directory to the **zip** folder, under the **all-my-frogs** repository. +``` +{ + "files": [ + { + "pattern": "resources/*.zip", + "target": "all-my-frogs/zip/" + } + ] +} +``` + +##### Example 6: + +Package all files located (including subdirectories) under the **resources** directory into a zip archive named **archive.zip** , and upload it into the root of the **all-my-frogs** repository. +``` +{ + "files": [ + { + "pattern": "resources/", + "archive": "zip", + "target": "all-my-frogs/" + } + ] +} +``` + +###### **Example 7:** + +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/", + "exclusions": ["*.txt","all-my-frog/props.*"] + } + ] +} +``` + +###### **Example 8:** + +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": "all-my-frogs/files/", + "sortBy": ["created"], + "sortOrder": "desc", + "limit": 1 + } + ] +} +``` + +###### **Example 9:** + +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 10:** + +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": "all-my-frogs/files/", + "sortBy": ["created"], + "sortOrder": "desc", + "limit": 1, + "offset": 1 + } + ] +} +``` + +###### Example 11: + +This example shows how to [delete artifacts in artifactory under specified path based on how old they are](https://stackoverflow.com/questions/58328701/delete-artifacts-in-artifactory-under-specified-path-based-on-how-old-they-are). + +The following File Spec finds all the folders which match the following criteria: + +1. They are under the my-repo repository. +2. They are inside a folder with a name that matches abc-*-xyz and is located at the root of the repository. +3. Their name matches ver* +4. They were created more than 7 days ago. +``` +{ + "files": [ + { + "aql": { + "items.find": { + "repo": "myrepo", + "path": {"$match":"abc-*-xyz"}, + "name": {"$match":"ver*"}, + "type": "folder", + "$or": [ + { + "$and": [ + { + "created": { "$before":"7d" } + } + ] + } + ] + } + } + } + ] +} +``` + +###### Example 12 + +This example uses [Using Placeholders](https://jfrog.com/help/r/jfrog-cli/using-placeholders). For each .tgz file in the source directory, create a corresponding directory with the same name in the target repository and upload it there. For example, a file named froggy.tgz should be uploaded to my-local-rep/froggy. (froggy will be created a folder in Artifactory). +``` +{ + "files": [ + { + "pattern": "(*).tgz", + "target": "my-local-repo/{1}/", + } + ] +} +``` + + +###### Example 13 + +This examples uses [Using Placeholders](https://jfrog.com/help/r/jfrog-cli/using-placeholders). 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. +``` +{ + "files": [ + { + "pattern": "(frog*)", + "target": "my-local-repo/frogfiles/{1}-up", + "recursive": "false" + } + ] +} +``` + + +###### Example 14 + +The following two examples lead to the exact same outcome. +The first one uses [Using Placeholders](https://jfrog.com/help/r/jfrog-cli/using-placeholders), while the second one does not. Both examples download all files from the generic-local repository to be under the ֿֿmy/local/path/ local file-system path, while maintaining the original Artifactory folder hierarchy. Notice the different flat values in the two examples. +``` +{ + "files": [ + { + "pattern": "generic-local/{*}", + "target": "my/local/path/{1}", + "flat": "true" + } + ] +} + +{ + "files": [ + { + "pattern": "generic-local/", + "target": "my/local/path/", + "flat": "false" + } + ] +} +``` + +### Schema Validation + +[JSON schemas](https://json-schema.org/) allow you to annotate and validate JSON files. The JFrog File Spec schema is available in the [JSON Schema Store](https://www.schemastore.org/json/) catalog and in the following link: [https://github.com/jfrog/jfrog-cli/blob/v2/schema/filespec-schema.json](https://github.com/jfrog/jfrog-cli/blob/v2/schema/filespec-schema.json). + +###### Using Jetbrains IDEs (Intellij IDEA, Webstorm, Goland, etc...)? + +The File Spec schema is automatically applied to the following file patterns: + +**/filespecs/*.json + +\*filespec\*.json + +*.filespec + +###### Using Visual Studio Code? + +To apply the File Spec schema validation, install the [JFrog VS-Code extension](https://marketplace.visualstudio.com/items?itemName=JFrog.jfrog-vscode-extension). + +Alternatively, copy the following to your settings.json file: + +**settings.json** +``` +"json.schemas": [ + { + "fileMatch": ["**/filespecs/*.json", "\*filespec\*.json", "*.filespec"], + "url": "https://raw.githubusercontent.com/jfrog/jfrog-cli/v2/schema/filespec-schema.json" + } +] +``` + +## Downloading the Maven and Gradle 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. + +1. Create a remote Maven repository in Artifactory and name it **extractors**. When creating the repository, configure it to proxy [https://releases.jfrog.io/artifactory/oss-release-local](https://releases.jfrog.io/artifactory/oss-release-local) +2. Make sure that this Artifactory server is known to JFrog CLI, using the [jfrog c show](https://jfrog.com/help/r/jfrog-cli/showing-the-configured-servers) command. If not, configure it using the [jfrog c add](https://jfrog.com/help/r/jfrog-cli/Adding-and-Editing-Configured-Servers) command. +3. Set the **JFROG_CLI_EXTRACTORS_REMOTE** environment variable with the server ID of the Artifactory server you configured, followed by a slash, and then the name of the repository you created. For example **_my-rt-server/extractors_** + +## Transferring Files Between Artifactory Servers + +### Overview +The transfer-files command allows transferring (copying) all the files stored in one Artifactory instance to a different Artifactory instance. The command allows transferring the files stored in a single or multiple repositories. The command expects the relevant repository to already exist on the target instance and have the same name and type as the repositories on the source. + +### Limitations +1. Artifacts in remote repositories caches are not transferred. +2. The files transfer process allows transferring files that were created or modified on the source instance after the process started. However, files that were deleted on the source instance after the process started, are not deleted on the target instance by the process. +3. The files transfer process allows transferring files that were created or modified on the source instance after the process started. The custom properties of those files are also updated on the target instance. However, if only the custom properties of those file were modified on the source, but not the files' content, the properties are not modified on the target instance by the process. +4. The source and target repositories should have the same name and type. +5. Since the file are pushed from the source to the target instance, the source instance must have network connection to the target. + +### Before You Begin +1. Ensure that you can log in to the UI of both the source and target instances with users that have admin permissions and that you have the connection details (including credentials) to both instances. +2. Ensure that all the repositories on source Artifactory instance which files you'd like to transfer, also exist on the target instance, and have the same name and type on both instances. +3. Ensure that JFrog CLI is installed on a machine that has network access to both the source and target instances. + +### Running the Transfer Process +#### Step 1 - Set Up the Source Instance for Files Transfer + +To set up the source instance for files transfer, you must install the **data-transfer** user plugin in the primary node of the source instance. This section guides you through the installation steps. + +1. Install JFrog CLI on the primary node machine of the source instance as described [here](https://jfrog.com/help/r/jfrog-cli/installing-the-data-transfer-user-plugin-on-the-source-machine-manually). +2. Configure the connection details of the source Artifactory instance with your admin credentials by running the following command from the terminal. + ``` + jf c add source-server + ``` +3. Ensure that the **JFROG_HOME** environment variable is set and holds the value of JFrog installation directory. It usually points to the **/opt/jfrog** directory. In case the variable isn't set, set its value to point to the correct directory as described in the JFrog Product Directory Structure article. +4. If the source instance has internet access, you can install the **data-transfer** user plugin on the source machine automatically by running the following command from the terminal `jf rt transfer-plugin-install source-server`. If however the source instance has no internet access, install the plugin manually as described [here](https://jfrog.com/help/r/jfrog-cli/installing-the-data-transfer-user-plugin-on-the-source-machine-manually). + +#### Step 2 - Push the Files from the Source to the Target Instance + +Install JFrog CLI on any machine that has access to both the source and the target JFrog instances. To do this, follow the steps described [here](https://jfrog.com/help/r/jfrog-cli/installing-jfrog-cli-on-a-machine-with-network-access-to-the-source-and-target-machines). + +Run the following command to start pushing the files from all the repositories in source instance to the target instance. + +``` +jf rt transfer-files source-server target-server +``` + +This command may take a few days to push all the files, depending on your system size and your network speed. While the command is running, It displays the transfer progress visually inside the terminal. + +![transfer-files-progress](https://github.com/jfrog/jfrog-cli/raw/v2/documentation/images/transfer-files-progress.png) + +If you're running the command in the background, you use the following command to view the transfer progress. + +``` +jf rt transfer-files --status +``` + +![transfer-files-status](https://github.com/jfrog/jfrog-cli/raw/v2/documentation/images/transfer-files-status.png) + +In case you do not wish to transfer the files from all repositories, or wish to run the transfer in phases, you can use the `--include-repos` and `--exclude-repos` command options. Run the following command to see the usage of these options. + +``` +jf rt transfer-files -h +``` + +If the traffic between the source and target instance needs to be routed through an HTTPS proxy, refer to [this](https://jfrog.com/help/r/jfrog-cli/routing-the-traffic-from-the-source-to-the-target-through-an-https-proxy) section. + +You can stop the transfer process by hitting on **CTRL+C** if the process is running in the foreground, or by running the following command, if you're running the process in the background. + +``` +jf rt transfer-files --stop +``` + +The process will continue from the point it stopped when you re-run the command. + +While the file transfer is running, monitor the load on your source instance, and if needed, reduce the transfer speed or increase it for better performance. For more information, see the [Controlling the File Transfer Speed](https://jfrog.com/help/r/jfrog-cli/controlling-the-file-transfer-speed) section. + +A path to an errors summary file will be printed at the end of the run, referring to a generated CSV file. Each line on the summary CSV represents an error of a file that failed to be transferred. On subsequent executions of the `jf rt transfer-files` command, JFrog CLI will attempt to transfer these files again. + +Once the `jf rt transfer-files` command finishes transferring the files, you can run it again to transfer files which were created or modified during the transfer. You can run the command as many times as needed. Subsequent executions of the command will also attempt to transfer files failed to be transferred during previous executions of the command. + +**Note:** +> Read more about how the transfer files works in [this](https://jfrog.com/help/r/jfrog-cli/how-does-files-transfer-work) section. +--- + +## Installing the data-transfer User Plugin on the Source Machine Manually +To install the **data-transfer** user plugin on the source machine manually, follow these steps. +1. Download the following two files from a machine that has internet access. Download **data-transfer.jar** from https://releases.jfrog.io/artifactory/jfrog-releases/data-transfer/[RELEASE]/lib/data-transfer.jar and **dataTransfer.groovy** from https://releases.jfrog.io/artifactory/jfrog-releases/data-transfer/[RELEASE]/dataTransfer.groovy +2. Create a new directory on the primary node machine of the source instance and place the two files you downloaded inside this directory. +3. Install the **data-transfer** user plugin by running the following command from the terminal. Replace the *[plugin files dir]* token with the full path to the directory which includes the plugin files you downloaded. + ``` + jf rt transfer-plugin-install source-server --dir "[plugin files dir]" + ``` + +## Installing JFrog CLI on the Source Instance Machine + +Install JFrog CLI on your source instance by using one of the [#JFrog CLI Installers]. For example: + +```curl -fL https://install-cli.jfrog.io | sh``` + +**Note** + +If the source instance is running as a docker container, and you're not able to install JFrog CLI while inside the container, follow these steps. + +1. Connect to the host machine through the terminal. +2. Download the JFrog CLI executable into the correct directory by running this command: + + ```curl -fL https://getcli.jfrog.io/v2-jf | sh``` +3. Copy the JFrog CLI executable you've just downloaded into the container, by running the following docker command. Make sure to replace *[the container name]* with the name of the container. + + ```docker cp jf [the container name]:/usr/bin/jf``` +4. Connect to the container and run the following command to ensure JFrog CLI is installed: + + ```jf -v``` + +## How Does Files Transfer Work? +### Files Transfer Phases +The `jf rt transfer-files` command pushes the files from the source instance to the target instance as follows: + +- The files are pushed for each repository, one by one in sequence. +- For each repository, the process includes the following three phases: + - **Phase 1** pushes all the files in the repository to the target. + - **Phase 2** pushes files which have been created or modified after phase 1 started running (diffs). + - **Phase 3** attempts to push files which failed to be transferred in earlier phases (Phase 1 or Phase 2) or in previous executions of the command. +- If Phase 1 finished running for a specific repository, and you run the `jf rt transfer-files` command again, only **Phase 2** and **Phase 3** will be triggered. You can run the `jf rt transfer-files` as many times as needed, till you are ready to move your traffic to the target instance permanently. In any subsequent run of the command, **Phase 2** will transfer the newly created and modified files and **Phase 3** will retry transferring files which failed to be transferred in previous phases and also in previous runs of the command. + +**Using Replication** +> To help reduce the time it takes for Phase 2 to run, you may configure Event Based Push Replication for some or all of the local repositories on the source instance. With Replication configured, when files are created or updated on the source repository, they are immediately replicated to the corresponding repository on the target instance. +The replication can be configured at any time. Before, during or after the files transfer process. +--- + +### Files Transfer State +You can run the `jf rt transfer-files` command multiple times. This is needed to allow transferring files which have been created or updated after previous command executions. To achieve this, JFrog CLI stores the current state of the files transfer process in a directory named **transfer** located under the JFrog CLI home directory. You can usually find this directory at this location `~/.jfrog/transfer`. + +JFrog CLI uses the state stored in this directory to avoid repeating transfer actions performed in previous executions of the command. For example, once **Phase 1** is completed for a specific repository, subsequent executions of the command will skip **Phase 1** and run **Phase 2** and **Phase 3** only. + +In case you'd like to ignore the stored state, and restart the files transfer from scratch, you can add the `--ignore-state` option to the `jf rt transfer-files` command. + +## Installing JFrog CLI on a Machine with Network Access to the Source and Target Machines +It is recommended to run the `transfer-files` command from a machine that has network access to the source Artifactory URL. This allows spreading the transfer load on all the Artifactory cluster nodes. This machine should also have network access to the target Artifactory URL. + +Follows these steps to installing JFrog CLI on that machine. + +1. Install JFrog CLI by using one of the [#JFrog CLI Installers]. For example: + + ``` + curl -fL https://install-cli.jfrog.io | sh + ``` + +2. If your source instance is accessible only through an HTTP/HTTPS proxy, set the proxy environment variable as described [#here]. +3. Configure the connection details of the source Artifactory instance with your admin credentials. Run the following command and follow the instructions. + + ``` + jf c add source-server + ``` + +4. Configure the connection details of the target Artifactory instance as follows. + + ``` + jf c add target-server + ``` + +## Controlling the File Transfer Speed +The `jf rt transfer-files` command pushes the binaries from the source instance to the target instance. This transfer can take days, depending on the size of the total data transferred, the network bandwidth between the source and the target instance, and additional factors. + +Since the process is expected to run while the source instance is still being used, monitor the instance to ensure that the transfer does not add too much load to it. Also, you might decide to increase the load for faster a transfer rate, while you monitor the transfer. This section describes how to control the file transfer speed. + +By default, the `jf rt transfer-files` command uses 8 working threads to push files from the source instance to the target instance. Reducing this value will cause slower transfer speed and lower load on the source instance, and increasing it will do the opposite. We therefore recommend increasing it gradually. This value can be changed while the `jf rt transfer-files` command is running. There's no need to stop the process to change the total of working threads. The new value set will be cached by JFrog CLI and also used for subsequent runs from the same machine. To set the value, simply run the following interactive command from a new terminal window on the same machine which runs the `jf rt transfer-files` command. + +``` +jf rt transfer-settings +``` + +**Build-info repositories** +> When transferring files in build-info repositories, JFrog CLI limits the total of working threads to 8. This is done in order to limit the load on the target instance while transferring build-info. +--- + +## Routing the Traffic from the Source to the Target Through an HTTPS Proxy +The `jf rt transfer-files` command pushes the files directly from the source to the target instance over the network. In case the traffic from the source instance needs to be routed through an HTTPS proxy, follow these steps. + +1. Define the proxy details in the source instance UI as described in the [Managing Proxies documentation](https://jfrog.com/help/r/jfrog-platform-administration-documentation/managing-proxies). + +2. When running the `jf rt transfer-files` command, add the `--proxy-key` option to the command, with Proxy Key you configured in the UI as the option value. For example, if the Proxy Key you configured is my-proxy-key, run the command as follows: + + ``` + jf rt transfer-files my-source my-target --proxy-key my-proxy-key + ``` diff --git a/documentation/CLI-for-JFrog-Cloud-Transfer.md b/documentation/CLI-for-JFrog-Cloud-Transfer.md index a29c4f542..d088df2e6 100644 --- a/documentation/CLI-for-JFrog-Cloud-Transfer.md +++ b/documentation/CLI-for-JFrog-Cloud-Transfer.md @@ -1 +1,483 @@ -The documentation for JFrog CLI has been relocated to [this](https://docs.jfrog-applications.jfrog.io/jfrog-applications/jfrog-cli) website. \ No newline at end of file +# Transfer Artifactory Configuration and Files from Self-Hosted to JFrog Cloud + +## General +JFrog provides you the ability to migrate from a self-hosted JFrog Platform installation to JFrog Cloud so that you can seamlessly transition into JFrog Cloud. You can use the JFrog CLI to transfer the Artifactory configuration settings and binaries to JFrog Cloud. + +JFrog Cloud provides the same cutting edge functionalities of a self-hosted JFrog Platform Deployment (JPD), without the overhead of managing the databases and systems. If you are an existing JFrog self-hosted customer, you might want to move to JFrog Cloud to ease operations. JFrog provides a solution that allows you to replicate your self-hosted JPD to a JFrog Cloud JPD painlessly. + +The Artifactory Transfer solution, currently transfers the config and data of JFrog Artifactory only. Other products such as JFrog Xray, Distribution and JFrog Pipelines are currently not supported by this solution. + +In this page, we refer the source self-hosted instance as the source instance, and the target JFrog Cloud instance as the target instance. + +## Artifactory Version Support + +The Artifactory Transfer solution is supported for any version of Artifactory 7.x and Artifactory version 6.23.21 and above. + +## Transfer phases + +The transfer process include two phases, that you must perform in the following order: + +1. **Configuration Transfer:** Transfers the configuration entities like users, permissions, and repositories from the source instance to the target instance. + +2. **File Transfer:** Transfers the files (binaries) stored in the source instance repositories to the target instance repositories. + +--- +**Note** +> * Files that are cached by remote repositories aren't transferred. +> * The content of Artifactory's Trash Can isn't transferred. +--- + +You can do both steps while the source instance is in use. No downtime on the source instance is required while the transfer is in progress. + +## Limitations + +The following limitations need to be kept in mind before you start the migration process + +1. The Archive Search Enabled feature is not supported on JFrog Cloud. + +2. Artifactory System Properties are not transferred and JFrog Cloud defaults are applied after the transfer. + +3. User plugins are not supported on JFrog Cloud. + +4. Artifact Cold Storage is not supported in JFrog Cloud. + +5. Artifacts in remote repositories caches are not transferred. + +6. Federated repositories are transferred without their federation members. After the transfer, you'll need to reconfigure the federation as described in the Federated Repositories documentation.Federated Repositories + +7. Docker repositories with names that include dots aren't allowed in JFrog Cloud. + +8. Artifact properties with value longer than 2.4K characters are not supported in JFrog Cloud. Such properties are generally seen in Conan artifacts. The artifacts will transferred without the properties in this case. A report with these artifacts will become available to you at the end of the transfer. + +9. The files transfer process allows transferring files that were created or modified on the source instance after the process started. However, files that were deleted on the source instance after the process started, are not deleted on the target instance by the process. + +10. The files transfer process allows transferring files that were created or modified on the source instance after the process started. The custom properties of those files are also updated on the target instance . However, if only the custom properties of those file were modified on the source, but not the files' content, the properties are not modified on the target instance by the process. + + +## Before you begin + +1. If your source instance hosts files that are larger than 25 GB, they will be blocked during the transfer. To learn how to check whether large files are hosted by your source instance, and what to do in that case, read [this section](#Transferring files larger than 25 GB). + +2. Ensure that you can login to the UI of both the source and target instances with users that have admin permissions. + +3. Ensure that the target instance license does not support less features than the source instance license. + +4. Run the files transfer pre-checks as described [here](#running-pre-checks-before-initiating-the-files-transfer-process). + +5. Ensure that all the remote repositories on the source Artifactory instance have network access to their destination URL once they are created in the target instance. Even if one remote or federated repository does not have access, the configuration transfer operation will be canceled. You do have the option of excluding specific repositories from being transferred. + +6. Ensure that all the replications configured on the source Artifactory instance have network access to their destination URL once they are created in the target instance. + +7. Ensure that you have a user that can log in to [MyJFrog](https://my.jfrog.com/login/). + +8. Ensure that you can login to the primary node of your source instance through a terminal. + +## Running the transfer process + +Perform the following steps to transfer configuration and artifacts from the source to the target instance. You must run the steps in the exact sequence and do not run any of the commands in parallel. + +### Step 1: Enabling configuration transfer on the target instance + +By default, the target does not have the APIs required for the configuration transfer. Enabling the target instance for configuration transfer is done through [MyJFrog](https://my.jfrog.com/login/). Once the configuration transfer is complete, you must disable the configuration transfer in [MyJFrog](https://my.jfrog.com/login/) as described in Step 4 below. + +--- +**Warning** +> * Enabling configuration transfer will trigger a shutdown of JFrog Xray, Distribution, Insights and Pipelines in the cloud and these services will therefore become unavailable. Once you disable the configuration transfer later on in the process, these services will be started up again. +> * Enabling configuration transfer will scale down JFrog Artifactory, which will reduce its available resources. Once you disable the configuration transfer later on in the process, Artifactory will be scaled up again. +--- + +Follow the below steps for enabling the configuration transfer. + +1: Log in to [MyJFrog](https://my.jfrog.com/login/). + +2: Click on **Settings**. + +3: Under the **Transfer Artifactory Configuration from Self-Hosted to Cloud** section, click on the **acknowledgment**checkbox. You cannot enable configuration transfer until you select the checkbox. +![image](images/transfer-1.png) + +4: If you have an Enterprise+ subscription with more than one Artifactory instance, select the target instance from the drop-down menu. + +5: Toggle **Enable Configuration Transfer** on to enable the transfer. The process may take a few minutes to complete. +![image](images/transfer-2.png) + +6: The configuration transfer is now enabled and you can continue with the transfer process. + +### Step 2: Set up the source instance for pushing files to the target instance + +To set up the source instance, you must install the data-transfer user plugin in the primary node of the source instance. This section guides you through the installation steps. + +1: Install JFrog CLI on the primary node machine of the source instance as described [here](#installing-jfrog-cli-on-the-source-instance-machine). + +2: Configure the connection details of the source Artifactory instance with your admin credentials by running the following command from the terminal. + + ```sh + jf c add source-server + ``` + +3: Ensure that the **JFROG\_HOME** environment variable is set and holds the value of JFrog installation directory. It usually points to the **/opt/jfrog** directory. In case the variable isn't set, set its value to point to the correct directory as described in the JFrog Product Directory Structure article.System Directories + +If the source instance has internet access, follow this single step: + +**Download and install the data-transfer user plugin by running the following command from the terminal.** + +```sh +jf rt transfer-plugin-install source-server +``` + +If the source instance has no internet access, follow these steps instead. + +1: Download the following two files from a machine that has internet access: + Download **data-transfer.jar** from [https://releases.jfrog.io/artifactory/jfrog-releases/data-transfer/\[RELEASE\]/lib/data-transfer.jar](https://releases.jfrog.io/artifactory/jfrog-releases/data-transfer/%5BRELEASE%5D/lib/data-transfer.jar). + Download **dataTransfer.groovy** from [https://releases.jfrog.io/artifactory/jfrog-releases/data-transfer/\[RELEASE\]/dataTransfer.groovy](https://releases.jfrog.io/artifactory/jfrog-releases/data-transfer/%5BRELEASE%5D/dataTransfer.groovy). + +2: Create a new directory on the primary node machine of the source instance and place the two files you downloaded inside this directory. + +3: Install the data-transfer user plugin by running the following command from the terminal. Replace the `` token with the full path to the directory which includes the plugin files you downloaded. + + ```sh + jf rt transfer-plugin-install source-server --dir "" + ``` + +### Step 3: Transfer configuration from the source instance to the target instance +--- +**Warning** +> The following process will wipe out the entire configuration of the target instance, and replace it with the configuration of the source instance. This includes repositories and users. +--- + +1: Install JFrog CLI on the source instance machine as described [here](#installing-jfrog-cli-on-the-source-instance-machine). + +2: Configure the connection details of the source Artifactory instance with your admin credentials by running the following command from the terminal. + ```sh + jf c add source-server + ``` + +3: Configure the connection details of the target Artifactory server with your admin credentials by running the following command from the terminal. + ```sh + jf c add target-server + ``` + +4: Run the following command to verify that the target URLs of all the remote repositories are accessible from the target. + ```sh + jf rt transfer-config source-server target-server --prechecks + ``` + If the command output shows that a target URL isn't accessible for any of the repositories, you'll need to make the URL accessible before proceeding to transferring the config. You can then rerun the command to ensure that the URLs are accessible. + +--- +**Note** +> The following process will wipe out the entire configuration of the target instance, and replace it with the configuration of the source instance. This includes repositories and users. +--- + +5: Transfer the configuration from the source to the target by running the following command. + ```sh + jf rt transfer-config source-server target-server + ``` + This command might take up to two minutes to run. +--- +**Note** +> * By default, the command will not transfer the configuration if it finds that the target instance isn't empty. This can happen for example if you ran the transfer-config command before. If you'd like to force the command run anyway, and overwrite the existing configuration on the target, run the command with the `--force` option. +> * In case you do not wish to transfer all repositories, you can use the `--include-repos` and `--exclude-repos` command options. Run the following command to see the usage of these options. +> ```jf rt transfer-config -h``` +--- + +6: View the command output in the terminal to verify that there are no errors. The command output is divided in to the following four phases: + ```sh + ========== Phase 1/4 - Preparations ========== + ========== Phase 2/4 - Export configuration from the source Artifactory ========== + ========== Phase 3/4 - Download and modify configuration ========== + ========== Phase 4/4 - Import configuration to the target Artifactory ========== + ``` + +7: View the log to verify there are no errors. + +![image](images/transfer-3.png) + +The target instance should now be accessible with the admin credentials of the source instance. Log into the target instance UI. The target instance must have the same repositories as the source. + +### Step 4: Disabling configuration transfer on the target instance + +Once the configuration transfer is successful, you need to disable the configuration transfer on the target instance. This is important both for security reasons and the target server is set to be low on resources while configuration transfer is enabled. + +1: Login to [MyJFrog](https://my.jfrog.com/login/) + +2: Under the Actions menu, choose **Enable Configuration Transfer**. + +3: Toggle **Enable Configuration Transfer** to **off** to disable configuration transfer. + +Disabling the configuration transfer might take some time. + +### Step 5: Push the files from the source to the target instance + +1: Install JFrog CLI on any machine that has access to both the source and the target JFrog instances. To do this, follow the steps described [here](#installing-jfrog-cli-on-a-machine-with-network-access-to-the-source-and-target-machines). + +2: Run the following command to start pushing the files from all the repositories in source instance to the target instance. + ```sh + jf rt transfer-files source-server target-server + ``` + +This command may take a few days to push all the files, depending on your system size and your network speed. While the command is running, It displays the transfer progress visually inside the terminal. +![image](images/transfer-4.png) + +If you're running the command in the background, you use the following command to view the transfer progress. +```sh +jf rt transfer-files --status +``` + +![image](images/transfer-5.png) + +--- +**Note** +> In case you do not wish to transfer the files from all repositories, or wish to run the transfer in phases, you can use the `--include-repos` and `--exclude-repos` command options. Run the following command to see the usage of these options. +--- + +```sh +jf rt transfer-files -h +``` + +* If the traffic between the source and target instance needs to be routed through an HTTPS proxy, refer to [this](#routing-the-traffic-from-the-source-to-the-target-through-an-https-proxy) section. + +* You can stop the transfer process by hitting on CTRL+C if the process is running in the foreground, or by running the following command, if you're running the process in the background. + +```sh +jf rt transfer-files --stop +``` + +The process will continue from the point it stopped when you re-run the command. + +While the file transfer is running, monitor the load on your source instance, and if needed, reduce the transfer speed or increase it for better performance. For more information, see the [Controlling the file transfer speed](#controlling-the-file-transfer-speed). + +1: A path to an errors summary file will be printed at the end of the run, referring to a generated CSV file. Each line on the summary CSV represents an error log of a file that failed to to be transferred. On subsequent executions of the `jf rt transfer-files`command, JFrog CLI will attempt to transfer these files again. + +2: Once the`jf rt transfer-files`command finishes transferring the files, you can run it again to transfer files which were created or modified while the transfer. You can run the command as many times as needed. Subsequent executions of the command will also attempt to transfer files that failed to be transferred during previous executions of the command. + +--- +**Note** +> Read more about how the transfer files works in [this](#how-does-files-transfer-work) section. +--- + +### Step 6: Sync the configuration between the source and the target + +You have the option to sync the configuration between the source and target after the files transfer process is complete. You may want to so this if new config entities, such as projects, repositories or users were created or modified on the source, while the files transfer process has been running. To do this, simply repeat steps 1-3 above. + +## Transferring projects and repositories from multiple source instances + +The **jf rt transfer-config** command transfers all the config entities (users, groups, projects, repositories and more) from the source to the target instance. While doing so, the existing configuration on the target is deleted and replaced with the new configuration from the source. If you'd like to transfer the projects and repositories from multiple source instances to a single target instance, while preserving the existing configuration on the target, follow the below steps. + +--- +**Note** +> These steps trigger the transfer of the projects and repositories only. Other configuration entities like users are currently not supported. +--- + +1: Ensure that you have admin access tokens for both the source and target instances. You'll have to use an admin access token and not an Admin username and password. + +2: Install JFrog CLI on any machine that has access to both the source and the target instances using the steps described [here](#installing-jfrog-cli-on-a-machine-with-network-access-to-the-source-and-target-machines). Make sure to use the admin access tokens and not an admin username and password when configuring the connection details of the source and the target. + +3: Run the following command to merge all the projects and repositories from the source to the target instance. + ```sh + jf rt transfer-config-merge source-server target-server + ``` + +--- +**Note** +> In case you do not wish to transfer the files from all projects or the repositories, or wish to run the transfer in phases, you can use the `--include-projects, --exclude-projects, --include-repos` and `--exclude-repos` command options. Run the following command to see the usage of these options. +--- + +```sh +jf rt transfer-config-merge -h +``` + +## How does files transfer work? + +### Files transfer phases + +The `jf rt transfer-files` command pushes the files from the source instance to the target instance as follows: + +* The files are pushed for each repository, one by one in sequence. + +* For each repository, the process includes the following three phases: + +* **Phase 1** pushes all the files in the repository to the target. + +* **Phase 2** pushes files which have been created or modified after phase 1 started running (diffs). + +* **Phase 3** attempts to push files which failed to be transferred in earlier phases (**Phase 1** or **Phase 2**) or in previous executions of the command. + +* If **Phase 1** finished running for a specific repository, and you run the `jf rt transfer-files` command again, only **Phase 2** and **Phase 3** will be triggered. You can run the `jf rt transfer-files` as many times as needed, till you are ready to move your traffic to the target instance permanently. In any subsequent run of the command, **Phase 2** will transfer the newly created and modified files and **Phase 3** will retry transferring files which failed to be transferred in previous phases and also **in previous runs of the command**. + +### Using Replication + +To help reduce the time it takes for Phase 2 to run, you may configure Event Based Push Replication for some or all of the local repositories on the source instance. With Replication configured, when files are created or updated on the source repository, they are immediately replicated to the corresponding repository on the target instance.Repository Replication + +The replication can be configured at any time. Before, during or after the files transfer process. + +### Files transfer state + +You can run the `jf rt transfer-files` command multiple times. This is needed to allow transferring files which have been created or updated after previous command executions. To achieve this, JFrog CLI stores the current state of the files transfer process in a directory named `transfer` under the JFrog CLI home directory. You can usually find this directory at this location `~/.jfrog/transfer`. + +JFrog CLI uses the state stored in this directory to avoid repeating transfer actions performed in previous executions of the command. For example, once **Phase 1** is completed for a specific repository, subsequent executions of the command will skip **Phase 1** and run **Phase 2** and **Phase 3** only. + +In case you'd like to ignore the stored state, and restart the files transfer from scratch, you can add the `--ignore-state` option to the `jf rt transfer-files` command. + +## Installing JFrog CLI on a machine with network access to the source and target machines + +Unlike the transfer-config command, which should be run from the primary note machines of Artifactory, it is recommended to run the transfer-files command from a machine that has network access to the source Artifactory URL. This allows spreading the transfer load on all the Artifactory cluster nodes. This machine should also have network access to the target Artifactory URL. + +Follows these steps to installing JFrog CLI on that machine. + +1: Install JFrog CLI by using one of the [JFrog CLI Installers](https://jfrog.com/getcli/). For example: + ```sh + curl -fL https://install-cli.jfrog.io | sh + ``` + +2: If your source instance is accessible only through an HTTP/HTTPS proxy, set the proxy environment variable as described [here](https://jfrog.com/help/r/jfrog-cli/proxy-support). + +3: Configure the connection details of the source Artifactory instance with your admin credentials. Run the following command and follow the instructions. + ```sh + jf c add source-server + ``` + +4: Configure the connection details of the target Artifactory instance. + ```sh + jf c add target-server + ``` + +## Installing JFrog CLI on the source instance machine + +Install JFrog CLI on your source instance by using one of the [JFrog CLI Installers](https://jfrog.com/getcli/). For example: +```sh +curl -fL https://install-cli.jfrog.io | sh +``` + +--- +**Note** +> If the source instance is running as a docker container, and you're not able to install JFrog CLI while inside the container, follow these steps. +--- + +1: Connect to the host machine through the terminal. + +2: Download the JFrog CLI executable into the correct directory by running this command. + ```sh + curl -fL https://getcli.jfrog.io/v2-jf | sh + ``` + +3: Copy the JFrog CLI executable you've justdownloadedto the container, by running the following docker command. Make sure to replace``with the name of the container. + ```sh + docker cp jf :/usr/bin/jf + ``` + +4: Connect to the container and run the following command to ensure JFrog CLI is installed + ```sh + jf -v + ``` + +## Controlling the file transfer speed + +The `jf rt transfer-files` command pushes the binaries from the source instance to the target instance. This transfer can take days, depending on the size of the total data transferred, the network bandwidth between the source and the target instance, and additional factors. + +Since the process is expected to run while the source instance is still being used, monitor the instance to ensure that the transfer does not add too much load to it. Also, you might decide to increase the load for faster transfer while you monitor the transfer. This section describes how to control the file transfer speed. + +By default, the `jf rt transfer-files` command uses 8 working threads to push files from the source instance to the target instance. Reducing this value will cause slower transfer speed and lower load on the source instance, and increasing it will do the opposite. We therefore recommend increasing it gradually. This value can be changed while the `jf rt transfer-files` command is running. There's no need to stop the process to change the total of working threads. The new value set will be cached by JFrog CLI and also used for subsequent runs from the same machine. To set the value, simply run the following interactive command from a new terminal window on the same machine which runs the `jf rt transfer-files` command. + +```sh +jf rt transfer-settings +``` + +## Build-info repositories + +When transferring files in build-info repositories, JFrog CLI limits the total of working threads to 8. This is done in order to limit the load on the target instance while transferring build-info. + +## Manually copying the filestore to reduce the transfer time + +When your self-hosted Artifactory hosts hundreds of terabytes of binaries, you may consult with your JFrog account manager about the option of reducing the files transfer time by manually copying the entire filestore to the JFrog Cloud storage. This reduces the transfer time, because the binaries content do not need to be transferred over the network. + +The `jf rt transfer-files` command transfers the metadata of the binaries to the database (file paths, file names, properties and statistics). The command also transfers the binaries that have been created and modified after you copy the filestore. + +To run the files transfer after you copy the filestore, add the `--filestore` command option to the `jf rt transfer-files` command. + +## Running pre-checks before initiating the files transfer process + +Before initiating the files transfer process, we highly recommend running pre-checks, to identify issues that can affect the transfer. You trigger the pre-checks by running a JFrog CLI command on your terminal. The pre-checks will verify the following: + +1: There's network connectivity between the source and target instances. + +2: The source instance does not include artifacts with properties with values longer than 2.4K characters. This is important, because values longer than 2.4K characters are not supported in JFrog Cloud, and those properties are skipped during the transfer process. + +To run the pre-checks, follow these steps: + +1: Install JFrog CLI on any machine that has access to both the source and the target JFrog instances. To do this, follow the steps described [here](#installing-jfrog-cli-on-a-machine-with-network-access-to-the-source-and-target-machines). + +2: Run the following command: + ```sh + jf rt transfer-files source-server target-server --prechecks + ``` + +--- +**Note** +> If the traffic between the source and target instance needs to be routed through an HTTPS proxy, add the --proxy-key command option as described in [this](#routing-the-traffic-from-the-source-to-the-target-through-an-https-proxy) section. +--- + +## Transferring files larger than 25 GB + +By default, files that are larger than 25 GB will be blocked by the JFrog Cloud infrastructure during the files transfer. To check whether your source Artifactory instance hosts files larger than that size, do the following. + +1: Run the following curl command from your terminal, after replacing the ``, `` and `` tokens with your source instance details. The command execution may take a few minutes, depending on the number of files hosted by Artifactory. + ```sh + curl -X POST /artifactory/api/search/aql -H "Content-Type: text/plain" -d 'items.find({"name" : {"$match":"\*"}}).include("size").sort({"$desc" : \["size"\]}).limit(1)' -u : + ``` + +2: You should get a result that looks like the following. + ``` + { + "results":[ + { + "size":132359021 + } + ], + "range":{ + "start_pos":0, + "end_pos":1, + "total":1, + "limit":1 + } + } + ``` + +The value of **size** represents the largest file size hosted by your source Artifactory instance. + +3: If the size value you received is larger than 25000000000, please avoid initiating the files transfer before contacting JFrog Support, to check whether this size limit can be increased for you. You can contact Support by sending an email to [support@jfrog.com](mailto:support@jfrog.com) + +## Routing the traffic from the source to the target through an HTTPS proxy + +The `jf rt transfer-files` command pushes the files directly from the source to the target instance over the network. In case the traffic from the source instance needs to be routed through an HTTPS proxy, follow these steps. + +1: Define the proxy details in the source instance UI as described in the Managing ProxiesManaging Proxies documentation. + +2: When running the `jf rt transfer-files` command, add the `--proxy-key` option to the command, with Proxy Key you configured in the UI as the option value. For example, if the Proxy Key you configured is **my-proxy-key**, run the command as follows: + ```sh + jf rt transfer-files my-source my-target --proxy-key my-proxy-key + ``` + +## Frequently asked questions + +**Why is the total files count on my source and target instances different after the files transfer finishes?** + +It is expected to see sometimes significant differences between the files count on the source and target instances, after the transfer ends. These differences can be caused by many reasons, and in most cases are not an indication for an issue. For example, Artifactory may include file cleanup policies that are triggered by the files deployment. This can cause some files to be cleaned up from the target repository after they are transferred. + +**How can I validate that all files were transferred from the source to the target instance?** + +There's actually no need to validate that all files were transferred at the end of the transfer process. JFrog CLI performs this validation for you while the process is running. It does that as follows. + +1. JFrog CLI traverses the repositories on the source instance and pushes all files to the target instance. + +2. If a file fails to reach the target instance or isn't deployed there successfully, the source instance logs this error with the file details. + +3. At the end of the transfer process, JFrog CLI provides you with a summary of all files which failed to be pushed. + +4. The failures are also logged inside the `transfer` directory under the JFrog CLI home directory. This directory is usually located at `~/.jfrog/transfer`. Subsequent runs of the jf rt `transfer-files` command use this information for attempting another transfer of the files. + +**Does JFrog CLI validate the integrity of files, after they are transferred to the target instance?** + +Yes. The source Artifactory instance stores a checksum for every file it hosts. When files are transferred to the target instance, they are transferred with the checksums as HTTP headers. The target instance calculates the checksum for each file it receives, and then compares it to the received checksum. If the checksums don't match, the target reports this to the source, which will attempt to transfer the file again at a later stage of the process. + +**Can I stop the jf rt transfer-files command and then start it again? Would that cause any issue?** + +You can stop the command at any time by hitting CTRL+C and then run it again. JFrog CLI stores the state of the transfer process in the "transfer" directory under the JFrog CLI home directory. This directory is usually located at ~/.jfrog/transfer. Subsequent executions of the command use the data stored in that directory to try and avoid transferring files that have already been transferred in previous command executions. diff --git a/documentation/CLI-for-JFrog-Curation.md b/documentation/CLI-for-JFrog-Curation.md index 4f324c184..651068ab3 100644 --- a/documentation/CLI-for-JFrog-Curation.md +++ b/documentation/CLI-for-JFrog-Curation.md @@ -1 +1,68 @@ -The documentation for JFrog CLI has been relocated to [this](https://docs.jfrog-applications.jfrog.io/jfrog-applications/jfrog-cli) website. \ No newline at end of file +JFrog CLI : CLI for JFrog Curation +====================================== + + +Overview +-------- +JFrog Curation enables you to block malicious or risky open-source packages entering your software supply chain. +What can you do with Curation? +* Track the open-source packages downloaded by your organization to gain centralized visibility and control. +* Prevent harmful packages from getting into your software development pipelines. +* Protect against known and unknown threats, allowing only trusted software packages into your SDLC. +* Create policies to block packages with known vulnerabilities, malicious code, operational risk, or license compliance issues. + +For more information on JFrog Curation and how to set it up, see the JFrog Curation general documentation at https://jfrog.com/help. + +JFrog Curation requires [Xray version 3.78.9](https://jfrog.com/help/r/jfrog-release-information/xray-3.78.9) and above, and [Artifactory version 7.63.5](https://jfrog.com/help/r/jfrog-release-information/artifactory-7.63) and above. It also requires Enterprise X and Enterprise + subscriptions. + +--- + +### Commands + +Audit your Project with JFrog Curation + + +**Note** +> The **curation-audit** command currently only supports npm projects. + +The **jf curation-audit** command enables developers to scan project dependencies to find packages that were blocked by the JFrog curation service. This command provides developers with more detailed information, such as whether the blocked package is the project’s direct dependency or is a transitive dependency. This information helps developers to resolve blocked packages more efficiently as they will be able to make a more informative decision based on what Policy violation occurred and what exactly needs to be resolved. + +For each blocked package the CLI provides the violated Curation Policies. The command builds a deep dependencies graph for the project, and requests the Curation status by a HEAD request for each node in the tree. It uses the package manager that is used in the project to build the dependencies graph. + +Before running the command, do the following: +1) Connect the JFrog CLI to your JFrog Platform instance by running the **jf c add** command. +2) Ensure your project is configured in the JFrog CLI with the repository you would like to resolve dependencies from. Set the repository with the **jf npmc** command inside the project directory. +

+ + +| | | +|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------| +| **Command name** | curation-audit | +| **Abbreviation** | ca | +| **Command options** | | +| --format | \[Default: table\]

Defines the output format of the command. Acceptable values are: table and json. | +| --working-dirs | \[Optional\]

A comma separated list of relative working directories, to determine the audit targets locations. | +| --threads | \[Default: 10\]

The number of parallel threads used to determine the curation status for each package in the project tree. | | + +#### **Output Example** + +![image](images/jf-ca-output.png) + + +**Example 1** + +Audit the project in the current directory. Displays all known packages that were blocked by Curation Policies. + + jf curation-audit + +**Example 2** + +Audit the projects according to the specific paths defined in the "working-dirs" option. Displays all known packages that were blocked by Curation Policies for all projects. The data is displayed in separate tables. + + jf curation-audit --working-dirs="/path/to/project/npm_project1,/path/to/project/npm_project2" + +**Example 3** + +Audit the project in the current directory using 5 threads to check the packages Curation status in parallel. Displays all known packages blocked by Curation Policies. + + jf curation-audit --threads=5 diff --git a/documentation/CLI-for-JFrog-Distribution.md b/documentation/CLI-for-JFrog-Distribution.md index 4f324c184..fab7885d5 100644 --- a/documentation/CLI-for-JFrog-Distribution.md +++ b/documentation/CLI-for-JFrog-Distribution.md @@ -1 +1,210 @@ -The documentation for JFrog CLI has been relocated to [this](https://docs.jfrog-applications.jfrog.io/jfrog-applications/jfrog-cli) website. \ No newline at end of file +JFrog CLI: CLI for JFrog Distribution +====================================== + + +Overview +-------- + +This page describes how to use JFrog CLI with [JFrog Distribution](https://jfrog-staging-external.fluidtopics.net/r/help/Software-Distribution-Distribution). + +Read more about JFrog CLI [here](https://jfrog.com/help/r/jfrog-cli). + +### Syntax + +When used with JFrog Distribution, JFrog CLI uses the following syntax: + + $ jf ds command-name global-options command-options arguments + +### Managing Access Keys + + + +### Commands + +The following sections describe the commands available in the JFrog CLI for use with JFrog Distribution. + +### Creating or updating an unsigned Release Bundle + +This command creates and updates an unsigned Release Bundle v1 on JFrog Distribution. + +--- +**Note** +> This commands require version 2.0 or higher of [JFrog Distribution](https://jfrog-staging-external.fluidtopics.net/r/help/Software-Distribution-Distribution). +--- + +| | | +|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | release-bundle-create / release-bundle-update | +| Abbreviation | rbc / rbu | +| Command options | | +| --server-id | \[Optional\]

Artifactory server ID configured using the config command. | +| --spec | \[Optional\]

Path to a file spec. For more details, please refer to[Using File Specs](https://www.jfrog.com/confluence/display/CLI/CLI+for+JFrog+Artifactory#CLIforJFrogArtifactory-UsingFileSpecs). | +| --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}. | +| --target-props | \[Optional\]

The list of properties, in the form of key1=value1;key2=value2,..., to be added to the artifacts after distribution of the Release Bundle v1. | +| --target | \[Optional\]

The target path for distributed artifacts on the Edge node. If not specified, the artifacts will have the same path and name on the Edge node as on the source Artifactory server. For flexibility in specifying the distribution path, you can include [placeholders](https://www.jfrog.com/confluence/display/CLI/CLI+for+JFrog+Artifactory#CLIforJFrogArtifactory-UsingPlaceholders) in the form of {1}, {2} which are replaced by corresponding tokens in the pattern path that are enclosed in parenthesis. | +| --dry-run | \[Default: false\]

Set to true to disable communication with JFrog Distribution. | +| --sign | \[Default: false\]

If set to true, automatically signs the Release Bundle version. | +| --passphrase | \[Optional\]

The passphrase for the signing key. | +| --desc | \[Optional\]

Description of the Release Bundle. | +| --release-notes-path | \[Optional\]

Path to a file describes the release notes for the Release Bundle version. | +| --release-notes-syntax | \[Default: plain_text\]

The syntax for the release notes. Can be one of _markdown_, _asciidoc_, or _plain_text_. | +| --exclusions | \[Optional\]

A list of semicolon-separated exclude path patterns to be excluded from the Release Bundle. Allows using wildcards. | +| --repo | \[Optional\]

A repository name at source Artifactory in which to store Release Bundle artifacts. If not provided, Artifactory will use the default one. | +| --insecure-tls | \[Default: false\]

Set to true to skip TLS certificates verification. | +| --detailed-summary | \[Default: false\]

Set to true to return the SHA256 value of the Release Bundle manifest. | +| Command arguments | | +| release bundle name | The name of the Release Bundle. | +| release bundle version | The Release Bundle version. | +| pattern | Specifies the source path in Artifactory from which the artifacts should be bundled, in the following format: <repository name>/<repository path>. You can use wildcards to specify multiple artifacts. This argument should not be sent along with the _--spec_ option. | + +##### Examples + +##### Example 1 + +Create a Release Bundle v1 with the name myApp and version 1.0.0. The Release Bundle will include the files defined in the File Spec specified by the --spec option. + + jf ds rbc --spec=/path/to/rb-spec.json myApp 1.0.0 + +##### Example 2 + +Create a Release Bundle v1 with the name myApp and version 1.0.0. The Release Bundle will include the files defined in the File Spec specified by the --spec option. GPG signs the Release Bundle after it is created. + + jf ds rbc --spec=/path/to/rb-spec.json --sign myApp 1.0.0 + +##### Example 3 + +Update the Release Bundle v1 with the name myApp and version 1.0.0. The Release Bundle will include the files defined in the File Spec specified by the --spec option. + + jf ds rbu --spec=/path/to/rb-spec.json myApp 1.0.0 + +##### Example 4 + +Update the Release Bundle v1 with the name myApp and version 1.0.0. The Release Bundle will include all the zip files inside the zip folder, located at the root of the _my-local-repo_ repository. + + jf ds rbu myApp 1.0.0 "my-local-repo/zips/*.zip" + +##### Example 5 + +Update the Release Bundle v1 with the name myApp and version 1.0.0. The Release Bundle will include all the zip files inside the zip folder, located at the root of the _my-local-repo_ repository. The files will be distributed to the Edge node to the _target-zips_ folder, under the root of the _my-target-repo_ repository. + + jf ds rbu myApp 1.0.0 "my-local-repo/zips/*.zip" --target my-target-repo/target-zips/ + +##### Example 6 + +This example uses [placeholders](https://www.jfrog.com/confluence/display/CLI/CLI+for+JFrog+Artifactory#CLIforJFrogArtifactory-UsingPlaceholders). It creates a Release Bundle v1 with the name myApp and version 1.0.0. The Release Bundle will include all the zip files inside the zip folder, located at the root of the _my-local-repo_ repository. The files will be distributed to the Edge node to the _target-zips_ folder, under the root of the _my-target-repo_ repository. In addition, the distributed files will be renamed on the Edge node, by adding _-target_ to the name of each file. + + jf ds rbc myApp 1.0.0 "my-local-repo/zips/(*).zip" --target "my-target-repo/target-zips/{1}-target.zip" + +### Signing an Existing Release Bundle + +This command GPG signs an existing Release Bundle on JFrog Distribution. + +--- +**Note** +> These commands require version 2.0 or higher of[JFrog Distribution](https://www.jfrog.com/confluence/display/JFROG/JFrog+Distribution). +--- + +| | | +|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | release-bundle-sign | +| Abbreviation | rbs | +| Command options | | +| --server-id | \[Optional\]

Artifactory server ID configured using the config command. | +| --passphrase | \[Optional\]

The passphrase for the signing key. | +| --repo | \[Optional\]

A repository name at source Artifactory to store Release Bundle artifacts in. If not provided, Artifactory will use the default one. | +| --insecure-tls | \[Default: false\]

Set to true to skip TLS certificates verification. | +| --detailed-summary | \[Default: false\]

Set to true to return the SHA256 value of the Release Bundle manifest. | +| Command arguments | | +| release bundle name | The name of the Release Bundle. | +| release bundle version | The Release Bundle version. | + +##### Examples + +##### Example 1 + +GPG signs the Release Bundle v1 with the name myApp and version 1.0.0. + + jf ds rbs --passphrase="<passphrase>" myApp 1.0.0 + +### Distributing a Release Bundle + +This command distributes a Release Bundle v1 to the Edge nodes. + +--- +**Note** +> These commands require version 2.0 or higher of [JFrog Distribution](https://www.jfrog.com/confluence/display/JFROG/JFrog+Distribution). +--- + +| | | +|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | release-bundle-distribute | +| Abbreviation | rbd | +| Command options | | +| --server-id | \[Optional\]

Artifactory server ID configured using the config command. | +| --sync | \[Default: false\]

Set to true to enable sync distribution (the command execution will end when the distribution process ends). | +| --max-wait-minutes | \[Default: 60\]

Max minutes to wait for sync distribution. | +| --create-repo | \[Default: false\]

Set to true to create the repository on the edge if it does not exist. | +| --dry-run | \[Default: false\]

Set to true to disable communication with JFrog Distribution. | +| --dist-rules | \[Optional\]

Path to a file, which includes the Distribution Rules in a JSON format.

**Distribution Rules JSON structure**

{
"distribution_rules": \[
{
"site_name": "DC-1",
"city_name": "New-York",
"country_codes": \["1"\]
},
{
"site_name": "DC-2",
"city_name": "Tel-Aviv",
"country_codes": \["972"\]
}
\]
}

The Distribution Rules format also supports wildcards. For example:

{
"distribution_rules": \[
{
"site_name": "*",
"city_name": "*",
"country_codes": \["*"\]
}
\]
} | +| --site | \[Default: *\]

Wildcard filter for site name. | +| --city | \[Default: *\]

Wildcard filter for site city name. | +| --country-codes | \[Default: *\]

Semicolon-separated list of wildcard filters for site country codes. | +| --insecure-tls | \[Default: false\]

Set to true to skip TLS certificates verification. | +| Command arguments | | +| release bundle name | The name of the Release Bundle. | +| release bundle version | The Release Bundle version. | + +##### Examples + +##### Example 1 + +Distribute the Release Bundle v1 with the name myApp and version 1.0.0. Use the distribution rules defined in the specified file. + + jf ds rbd --dist-rules=/path/to/dist-rules.json myApp 1.0.0 + + + +### Deleting a Release Bundle + +This command deletes a Release Bundle v1 from the Edge nodes and optionally from Distribution as well. + +--- +**Note** +> These commands require version 2.0 or higher of[JFrog Distribution](https://www.jfrog.com/confluence/display/JFROG/JFrog+Distribution). +--- + +| | | +|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | release-bundle-delete | +| Abbreviation | rbdel | +| Command options | | +| --server-id | \[Optional\]

Artifactory server ID configured using the config command. | +| --sync | \[Default: false\]

Set to true to enable sync deletion (the command execution will end when the deletion process ends). | +| --max-wait-minutes | \[Default: 60\]

Max minutes to wait for sync deletion. | +| --dry-run | \[Default: false\]

Set to true to disable communication with JFrog Distribution. | +| --dist-rules | \[Optional\]

Path to a file, which includes the distribution rules in a JSON format. | +| --site | \[Default: *\]

Wildcard filter for site name. | +| --city | \[Default: *\]

Wildcard filter for site city name. | +| --country-codes | \[Default: *\]

Semicolon-separated list of wildcard filters for site country codes. | +| --delete-from-dist | \[Default: false\]

Set to true to delete the Release Bundle version in JFrog Distribution itself after deletion is complete in the specified Edge nodes. | +| --quiet | \[Default: false\]

Set to true to skip the delete confirmation message. | +| --insecure-tls | \[Default: false\]

Set to true to skip TLS certificates verification. | +| Command arguments | | +| release bundle name | The name of the Release Bundle. | +| release bundle version | The Release Bundle version. | + +##### Examples + +##### Example 1 + +Delete the Release Bundle v1 with the name myApp and version 1.0.0 from the Edge nodes only, according to the definition in the distribution rules file. + + jf ds rbdel --dist-rules=/path/to/dist-rules.json myApp 1.0.0 + +##### Example 2 + +Delete the Release Bundle v1 with the name myApp and version 1.0.0 from the Edge nodes, according to the definition in the distribution rules file. The Release Bundle will also be deleted from the Distribution service itself. + + jf ds rbdel --delete-from-dist --dist-rules=/path/to/dist-rules.json myApp 1.0.0 + + diff --git a/documentation/CLI-for-JFrog-Lifecycle.md b/documentation/CLI-for-JFrog-Lifecycle.md index 4f324c184..eaccb5bd6 100644 --- a/documentation/CLI-for-JFrog-Lifecycle.md +++ b/documentation/CLI-for-JFrog-Lifecycle.md @@ -1 +1,189 @@ -The documentation for JFrog CLI has been relocated to [this](https://docs.jfrog-applications.jfrog.io/jfrog-applications/jfrog-cli) website. \ No newline at end of file +# JFrog CLI: CLI for JFrog Release Lifecycle Management + +## Overview + +This page describes how to use JFrog CLI with [JFrog Release Lifecycle Management](https://jfrog.com/help/r/jfrog-artifactory-documentation/jfrog-release-lifecycle-management-solution). + +Read more about JFrog CLI [here](https://jfrog.com/help/r/jfrog-cli). + +--- +**Note** +> JFrog Release Lifecycle Management is only available since [Artifactory 7.63.2](https://jfrog.com/help/r/jfrog-release-information/artifactory-7.63.2-cloud). +--- + +### Commands + +The following sections describe the commands available in JFrog CLI when performing Release Lifecycle Management operations on Release Bundles v2. + +### Creating a Release Bundle v2 from builds or from existing Release Bundles + +This command creates a Release Bundle v2 from published build-infos or from existing Release Bundles. +1. To create a Release Bundle from published build-infos, provide the `--builds` option, which accepts a path to a file using the following JSON format: + ```json + { + "builds": [ + { + "name": "build name", + "number": "build number", + "project": "project" + } + ] + } + ``` + `number` is optional (if left empty, the latest build will be used) + + `project` is optional (if left empty, the default project will be used) + +2. To create a Release Bundle v2 from existing Release Bundles, provide the `--release-bundles` option, which accepts a path to a file using the following JSON format: + ```json + { + "releaseBundles": [ + { + "name": "release bundle name", + "version": "release bundle version", + "project": "project" + } + ] + } + ``` + `project` is optional (if left empty, the default project will be used) + +| | | +|------------------------|----------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | release-bundle-create | +| Abbreviation | rbc | +| Command options | | +| --builds | \[Optional\]

Path to a JSON file containing information about the source builds from which to create a Release Bundle. | +| --project | \[Optional\]

JFrog Project key associated with the Release Bundle version. | +| --release-bundles | \[Optional\]

Path to a JSON file containing information about the source Release Bundles from which to create a Release Bundle. | +| --server-id | \[Optional\]

Platform server ID configured using the `jf c add` command. | +| --signing-key | \[Mandatory\]

The GPG/RSA key-pair name given in Artifactory. | +| --sync | \[Default: false\]

Set to true to run synchronously. | +| Command arguments | | +| release bundle name | Name of the newly created Release Bundle. | +| release bundle version | Version of the newly created Release Bundle. | + +#### Examples + +##### Example 1 + +Create a Release Bundle v2 with the name "myApp" and version "1.0.0", with signing key pair "myKeyPair". +The Release Bundle will include the artifacts of the builds that were provided in the builds spec. +``` +jf rbc --builds=/path/to/builds-spec.json --signing-key=myKeyPair myApp 1.0.0 +``` +##### Example 2 + +Create a Release Bundle v2 with the name "myApp" and version "1.0.0", with signing key pair "myKeyPair". +The Release Bundle will include the artifacts of the Release Bundles that were provided in the Release Bundles spec. +``` +jf rbc --release-bundles=/path/to/release-bundles-spec.json --signing-key=myKeyPair myApp 1.0.0 +``` +##### Example 3 + +Create a Release Bundle v2 synchronously with the name "myApp" and version "1.0.0", in project "project0", with signing key pair "myKeyPair". +The Release Bundle will include the artifacts of the Release Bundles that were provided in the Release Bundles spec. +``` +jf rbc --release-bundles=/path/to/release-bundles-spec.json --signing-key=myKeyPair --sync=true --project=project0 myApp 1.0.0 +``` +### Promoting a Release Bundle v2 + +This command promotes a Release Bundle v2 to a target environment. + +| | | +|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | release-bundle-promote | +| Abbreviation | rbp | +| Command options | | +| --overwrite | \[Default: false\]

Set to true to replace artifacts with the same name but a different checksum, if such already exist at the promotion targets. By default, the promotion is stopped when a conflict occurs. | +| --project | \[Optional\]

Project key associated with the Release Bundle version. | +| --server-id | \[Optional\]

Platform server ID configured using the config command. | +| --signing-key | \[Mandatory\]

The GPG/RSA key-pair name given in Artifactory. | +| --sync | \[Default: false\]

Set to true to run synchronously. | +| Command arguments | | +| release bundle name | Name of the Release Bundle to promote. | +| release bundle version | Version of the Release Bundle to promote. | +| environment | Name of the target environment for the promotion. | + +#### Examples +##### Example 1 + +Promote a Release Bundle v2 named "myApp" version "1.0.0" to environment "PROD". +Use signing key pair "myKeyPair". +``` +jf rbp --signing-key=myKeyPair myApp 1.0.0 PROD +``` +##### Example 2 + +Promote a Release Bundle v2 synchronously to environment "PROD". +The Release Bundle is named "myApp", version "1.0.0", of project "project0". +Use signing key pair "myKeyPair" and overwrite in case of conflicts. +``` +jf rbp --signing-key=myKeyPair --project=project0 --overwrite=true --sync=true myApp 1.0.0 PROD +``` + +### Distributing a release bundle + +This command distributes a Release Bundle v2 to an edge node. + +| | | +|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command-name | release-bundle-distribute | +| Abbreviation | rbd | +| Command options | | +| --create-repo | \[Default: false\]

Set to true to create the repository on the edge if it does not exist. | +| --dry-run | \[Default: false\]

Set to true to disable communication with JFrog Distribution. | +| --dist-rules | \[Optional\]

Path to a file, which includes the Distribution Rules in a JSON format. See [structure](#distribution-rules-structure) bellow. | +| --site | \[Default: *\]

Wildcard filter for site name. | +| --city | \[Default: *\]

Wildcard filter for site city name. | +| --country-codes | \[Default: *\]

Semicolon-separated list of wildcard filters for site country codes. | +| --insecure-tls | \[Default: false\]

Set to true to skip TLS certificates verification. | +| --mapping-pattern | \[Optional\]

Specify along with 'mapping-target' to distribute artifacts to a different path on the edge node. You can use wildcards to specify multiple artifacts. | +| --mapping-target | \[Optional\]

The target path for distributed artifacts on the edge node. If not specified, the artifacts will have the same path and name on the edge node, as on the source Artifactory server. For flexibility in specifying the distribution path, you can include [placeholders](https://www.jfrog.com/confluence/display/CLI/CLI+for+JFrog+Artifactory#CLIforJFrogArtifactory-UsingPlaceholders) in the form of {1}, {2} which are replaced by corresponding tokens in the pattern path that are enclosed in parenthesis. | +| Command arguments | | +| release bundle name | Name of the Release Bundle to distribute. | +| release bundle version | Version of the Release Bundle to distribute. | + +#### Distribution Rules Structure: + ```json + { + "distribution_rules": [ + { + "site_name": "DC-1", + "city_name": "New-York", + "country_codes": ["1"] + }, + { + "site_name": "DC-2", + "city_name": "Tel-Aviv", + "country_codes": ["972"] + } + ] + } + ``` +The Distribution Rules format also supports wildcards. For example: + ```json + { + "distribution_rules": [ + { + "site_name": "", + "city_name": "", + "country_codes": ["*"] + } + ] + } + ``` + +#### Examples + +#### Example 1 +Distribute the Release Bundle v2 named myApp with version 1.0.0. Use the distribution rules defined in the specified file. + + jf rbd --dist-rules=/path/to/dist-rules.json myApp 1.0.0 + +#### Example 2 + +Distribute the Release Bundle v2 named myApp with version 1.0.0 using the default distribution rules. +Map files under the 'source' directory to be placed under the 'target' directory. + + jf rbd --dist-rules=/path/to/dist-rules.json --mapping-pattern="(*)/source/(*)" --mapping-target="{1}/target/{2}" myApp 1.0.0 \ No newline at end of file diff --git a/documentation/CLI-for-JFrog-Mission-Control.md b/documentation/CLI-for-JFrog-Mission-Control.md index 4f324c184..812bb140c 100644 --- a/documentation/CLI-for-JFrog-Mission-Control.md +++ b/documentation/CLI-for-JFrog-Mission-Control.md @@ -1 +1,140 @@ -The documentation for JFrog CLI has been relocated to [this](https://docs.jfrog-applications.jfrog.io/jfrog-applications/jfrog-cli) website. \ No newline at end of file +JFrog CLI : CLI for JFrog Mission Control +========================================= + +Overview +-------- + +This page describes how to use JFrog CLI with JFrog Mission Control. + +Read more about JFrog CLI [here](https://jfrog.com/help/r/jfrog-cli). + +Syntax +------ + + $ jfrog mc command-name arguments global-options command-options + +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:` (Optional) Mission Control URL.

`--access-token:` (Optional) Mission Control admin access token.

**Use the config command**

To avoid having to set these for every command, you may set them once using the [config](#CLIforJFrogMissionControl-Configuration) command and then omit them for every following command. | +| command-options | A set of options corresponding to the command | +| arguments | A set of arguments corresponding to the command | + + + +* * * + +Commands +-------- + +The following sections describe the commands available in the JFrog CLI for use with JFrog Mission Control. + +### Adding a JPD + +| | | +|-------------------|----------------------------------------------------------------| +| Command name | jpd-add | +| Abbreviation | ja | +| Description | Adds a JPD to Mission Control | +| Command arguments | | +| Config | Path to a JSON configuration file containing the JPD details. | +| Command options | The command accepts no options, other than the global options. | + +#### **Config JSON schema** +``` +{ + "name" : "jpd-0", + "url" : "http://jpd:8080/test", + "token" : "some-token", + "location" : { + "city_name" : "San Francisco", + "country_code" : "US", + "latitude" : 37.7749, + "longitude" : 122.4194 + }, + "tags" : \[ "tag0", "tag1" \] +} +``` + + +**Example** + + jf mc ja path/to/jpd/config.json + +### Deleting a JPD + +| | | +|-------------------|----------------------------------------------------------------| +| Command name | jpd-delete | +| Abbreviation | jd | +| Description | Delete a JPD from Mission Control. | +| Command arguments | | +| JPD ID | The ID of the JPD to be removed from Mission Control. | +| | | +| Command options | The command accepts no options, other than the global options. | + +**Example** + + jf mc jd my-jpd-id + +### Acquiring a License + +| | | +|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command name | license-acquire | +| Abbreviation | la | +| Description | Acquire a license from the specified bucket and mark it as taken by the provided name. | +| Command arguments | | +| Bucket ID | Bucket name or identifier to acquire license from. | +| Name | A custom name used to mark the license as taken. Can be a JPD ID or a temporary name. If the license does not end up being used by a JPD, this is the name that should be used to release the license. | +| | | +| Command options | The command accepts no options, other than the global options. | + +**Examples** + +##### Example 1 + +Assign a license from the _my-bucket-id_ and mark it as taken by _my-unique-name_. + + jf mc la my-bucket-id my-unique-name + +### Deploying a License + +| | | +|-------------------|-----------------------------------------------------------------------------------------------------| +| Command name | license-deploy | +| Abbreviation | ld | +| Description | specified bucket to an existing JPD. You may also deploy a number of licenses to an Artifactory HA. | +| Command arguments | | +| Bucket ID | Bucket name or identifier to deploy licenses from. | +| JPD ID | An existing JPD's ID. | +| | | +| Command options | | +| --license-count | \[Default: 1\]

The number of licenses to deploy. Minimum value is 1. | + +**Example** + +Deploy a single license from _my-bucket-id_ on _my-jpd-id_. + + jf mc ld my-bucket-id my-jpd-id + +### Releasing a License + +| | | +|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------| +| Command name | license-release | +| Abbreviation | lr | +| Description | Release all licenses of a JPD and return them to the specified bucket. | +| Command arguments | | +| Bucket ID | Bucket name or identifier to release all of its licenses. | +| JPD ID | If the license is used by a JPD, pass the JPD's ID. If the license was only acquired but is not used, pass the name it was acquired with. | +| | | +| Command options | The command accepts no options, other than the global options. | + +**Example** + +Releases all licenses of _my-jpd-id_ to _my-bucket-id_. + + jf mc lr my-bucket-id my-jpd-id diff --git a/documentation/CLI-for-JFrog-Pipelines.md b/documentation/CLI-for-JFrog-Pipelines.md index 4f324c184..bd387f804 100644 --- a/documentation/CLI-for-JFrog-Pipelines.md +++ b/documentation/CLI-for-JFrog-Pipelines.md @@ -1 +1,138 @@ -The documentation for JFrog CLI has been relocated to [this](https://docs.jfrog-applications.jfrog.io/jfrog-applications/jfrog-cli) website. \ No newline at end of file +Overview +-------- + +This page describes how to use JFrog CLI with JFrog Pipelines. + +Read more about JFrog CLI [here](https://jfrog-external.fluidtopics.net/r/help/JFrog-CLI/JFrog-CLI). + +Syntax +------ + + $ jf pl command-name arguments command-options + +Where: + +| | | +|-----------------|-------------------------------------------------------------------------------------------------| +| command-name | The command to execute. Note that you can use either the full command name or its abbreviation. | +| command-options | A set of options corresponding to the command | +| arguments | A set of arguments corresponding to the command | + + + + +* * * + +Commands +-------- + +The following sections describe the commands available in the JFrog CLI for use with JFrog Pipelines. + +### Checking Pipelines Version + +Check the version of Pipelines installation. + +| | | +|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------| +| Command name | pl version | +| Abbreviation | v | +| Command arguments | The command accepts no arguments. | +| Command options | | +| --server-id | \[Optional\]

Specify Pipelines server for which the version is to be fetched. If not specified, the default configured server is used. | + +#### **Example** + + jf pl version --server-id repo21 + +### Getting Run Status + +Get the status of the run for the specified pipeline. + +| | | +|-------------------|---------------------------------------------------------------------------------------------------------------------------| +| Command name | pl status | +| Abbreviation | s | +| Command arguments | The command accepts no arguments. | +| | | +| Command options | | +| --pipeline-name | \[Optional\]

Name of the pipeline. | +| --branch | \[Optional\]

Name of the multi branch. | +| --monitor | \[Optional\]

Continuous monitoring until pipeline reaches end state.

Default time is 1 hour and 30 minutes. | +| --server-id | \[Optional\]

Name of the server. | +| --single-branch | \[Optional\]

To be used when using a single branch. | + +**Examples** + +**Single Branch** + + jf pl status --pipeline-name myPipeline --single-branch --server-id repo21 --monitor --single-branch + +**Multi Branch** + + jf pl status --pipeline-name myPipeline --branch main/jobs --server-id repo21 --monitor + +### Triggering a Pipeline + +Trigger a pipeline run. + +| | | +|-------------------|----------------------------------------------------------------------------------------------------------| +| Command name | pl trigger | +| Abbreviation | t | +| Command options | | +| --server-id | \[Optional\]

Name of the server. | +| --single-branch | \[Optional\]

To be used when using a single branch. When used, `branch_name` argument is ignored. | +| Command arguments | | +| pipeline_name | Name of the pipeline to be triggered. | +| branch_name | Name of the multi branch. | + +**Examples** + +**Single Branch** + + jf pl trigger myPipeline main/jobs --single-branch --server-id repo21 + +**Multi Branch** + + jf pl trigger myPipeline main/jobs --server-id repo21 + +### ![](attachments/180127127/180127382.png) + +### Syncing Pipeline Source + +Perform a sync to load the latest pipeline source. + +| | | +|-----------------|--------------------------------------------------------------------------------------| +| Command name | pl sync | +| Abbreviation | sy | +| Command options | | +| --server-id | \[Optional\]

Name of the server. | +| --repository | \[Optional\]

Full name of the repository where the pipeline source is stored. | +| --branch | \[Optional\]

Name of branch that has the pipeline source. | + +**Example** + + jf pl sync --repository jfrog/artifactory --branch main/jobs --server-id repo21 + +![](attachments/180127127/180127380.png) + +### Sync Status of Pipeline Source + +Get the current status of the pipeline source sync. + +| | | +|-------------------|------------------------------------------------------------------| +| Command name | pl sync-status | +| Abbreviation | ss | +| Command options | | +| --server-id | \[Optional\]

Name of the server. | +| Command arguments | | +| full\_repo\_name | Full name of the repository where the pipeline source is stored. | +| branch_name | Name of the branch. | + +**Example** + + jf pl sync-status jfrog/artifactory main/jobs --server-id repo21 + +![](attachments/180127127/180127381.png) diff --git a/documentation/CLI-for-JFrog-Xray.md b/documentation/CLI-for-JFrog-Xray.md index 4f324c184..57b96f506 100644 --- a/documentation/CLI-for-JFrog-Xray.md +++ b/documentation/CLI-for-JFrog-Xray.md @@ -1 +1,466 @@ -The documentation for JFrog CLI has been relocated to [this](https://docs.jfrog-applications.jfrog.io/jfrog-applications/jfrog-cli) website. \ No newline at end of file +# JFrog CLI : CLI for JFrog Xray + +## Overview +This page describes how to use JFrog CLI with JFrog Xray. +Read more about JFrog CLI[here](https://jfrog.com/help/r/jfrog-cli). + +### Authentication +When used with Xray, JFrog CLI offers several means of authentication: JFrog CLI does not support accessing Xray without authentication. + +#### Authenticating with Username and Password +To authenticate yourself using your Xray login credentials, either configure your credentials once using the_jf c add_command or provide the following option to each command. + +| | | +|----------------|---------------------------------------------------------| +| Command option | Description | +| --url | JFrog Xray API endpoint URL. It usually ends with /xray | +| --user | JFrog username | +| --password | JFrog password | + +#### Authenticating with an Access Token +To authenticate yourself using an Xray Access Token, either configure your Access Token once using the _jf c add_command or provide the following option to each command. + +| | | +|----------------|---------------------------------------------------------| +| Command option | Description | +| --url | JFrog Xray API endpoint URL. It usually ends with /xray | +| --access-token | JFrog access token | + + +* * * + +## Scanning Project Dependencies +### General +The _**jf audit**_ command allows scanning your source code dependencies to find security vulnerabilities and license violations, with the ability to scan against your Xray policies. The command builds a deep dependencies graph for your project, scans it with Xray, and displays the results. +It uses the package manager used by the project to build the dependencies graph. + +Currently, the following package managers are supported: + +|Go Go|Gradle Gradle|Maven Maven (3.1+)|npm npm|Yarn Yarn| +|:----|:----|:----|:----|:----| +|.NET .NET|NuGet NuGet|Pip Pip|Pipenv Pipenv|Poetry Poetry| + +The command will detect the package manager used by the project automatically. It requires version 3.29.0 or above of Xray and also version 2.13.0 or above of JFrog CLI. + +### Advanced Scans +This command also supports the following Advanced Scans with the **Advanced Security Package** enabled on the JFrog Platform instance. To enable the Advanced Security Package, contact us using [this](https://jfrog.com/advanced-security-contact-us/) form. + +* **Static Application Security Testing (SAST)**: Provides fast and accurate security-focused engines that detect zero-day security vulnerabilities on your source code sensitive operations, while minimizing false positives. +* **Vulnerability Contextual Analysis**: This feature uses the code context to eliminate false positive reports on vulnerable dependencies that are not applicable to the code. For CVE vulnerabilities that are applicable to your code, Frogbot will create pull request comments on the relevant code lines with full descriptions regarding the security issues caused by the CVE. Vulnerability Contextual Analysis is currently supported for Python, JavaScript, and Java code. +* **Secrets Detection**: Detect any secrets left exposed inside the code. to stop any accidental leak of internal tokens or credentials. +* **Infrastructure as Code scans (IaC)**: Scan Infrastructure as Code (Terraform) files for early detection of cloud and infrastructure misconfigurations. + +--- +**Note** + +> +* The **jf audit** command does not extract the internal content of the scanned dependencies. This means that if a package includes other vulnerable components bundled inside the binary, they may not be shown as part of the results. This is contrary to the **jf scan** command, which drills down into the package content. +--- + +| | | +|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Command name** | audit | +| **Abbreviation** | aud | +| **Command options** | | +| --server-id | \[Optional\]

Server ID configured using the _jf c add_ command. If not specified, the default configured server is used. | +| --project | \[Optional\]

JFrog project key, to enable Xray to determine security violations accordingly. The command accepts this option only if the --repo-path and --watches options are not provided. If none of the three options are provided, the command will show all known vulnerabilities | +| --repo-path | \[Optional\]

Artifactory repository path in the form of <repository>/<path in the repository>, to enable Xray to determine violations accordingly. The command accepts this option only if the --project and --watches options are not provided. If none of the three options are provided, the command will show all known vulnerabilities | +| --watches | \[Optional\]

A comma-separated list of Xray watches, to enable Xray to determine violations accordingly. The command accepts this option only if the --repo-path and --repo-path options are not provided. If none of the three options are provided, the command will show all known vulnerabilities | +| --licenses | \[Default: false\]

Set if you'd also like the list of licenses to be displayed. | +| --format | \[Default: table\]

Defines the output format of the command. Acceptable values are: table and json. | +| --fail | \[Default: true\]

Set to false if you do not wish the command to return exit code 3, even if the 'Fail Build' rule is matched by Xray. | +| --use-wrapper | \[Default: false\] \[Gradle\]

Set to true if you'd like to use the Gradle wrapper. | +| --dep-type | \[Default: all\] \[npm\]

Defines npm dependencies type. Possible values are: all, devOnly and prodOnly | +| --exclude-test-deps | \[Default: false\] \[Gradle\]

Set to true if you'd like to exclude Gradle test dependencies from Xray scanning. | +| --requirements-file | \[Optional\] \[Pip\]

Defines pip requirements file name. For example: 'requirements.txt' | +| --working-dirs | \[Optional\]

A comma-separated list of relative working directories, to determine the audit targets locations. | +| --fixable-only | \[Optional\]

Set to true if you wish to display issues that have a fix version only. | +| --min-severity | \[Optional\]

Set the minimum severity of issues to display. The following values are accepted: Low, Medium, High or Critical | +| --go | \[Default: false\]

Set to true to request audit for a Go project. | +| --gradle | \[Default: false\]

Set to true to request audit for a Gradle project. | +| --mvn | \[Default: false\]

Set to true to request audit for a Maven project. | +| --npm | \[Default: false\]

Set to true to request audit for a npm project. | +| --nuget | \[Default: false\]

Set to true to request audit for a .Net project. | +| --pip | \[Default: false\]

Set to true to request audit for a Pip project. | +| --pipenv | \[Default: false\]

Set to true to request audit for a Pipenv project. | +| --yarn | \[Default: false\]

Set to true to request audit for a Yarn project. | +| **Command arguments** | The command accepts no arguments | + +#### **Output Example** + + + + + + + +#### Examples + +**Example 1** + +Audit the project at the current directory. Show all known vulnerabilities, regardless of the policies defined in Xray. +``` +jf audit +``` + +**Example 2** + +Audit the project at the current directory. Show all known vulnerabilities, regardless of the policies defined in Xray. Show only maven and npm vulnerabilities. +``` +jf audit --mvn --npm +``` + +**Example 3** + +Audit the project at the current directory using a watch named _watch1_ watch defined in Xray. +``` +jf audit --watches "watch1" +``` + +**Example 4** + +Audit the project at the current directory using _watch1_ and _watch2_defined in Xray. +``` +jf audit --watches "watch1,watch2" +``` + +**Example 5** + +Audit the project at the current directory using the policies defined for project-1. +``` +jf audit --project "project-1" +``` + +**Example 6** + +Audit the project at the current directory using the policies defined for the _libs-local/release-artifacts/_ path in Artifactory. +``` +jf audit --repo-path "libs-local/release-artifacts/" +``` + +### Running cUrl + +Execute a cUrl command, using the configured Xray details. The command expects the cUrl client to be included in the PATH. + +| | | +|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command name | xr curl | +| Abbreviation | xr cl | +| Command options | | +| --server-id | \[Optional\]

Server ID configured using the _jf c add_ command. If not specified, the default configured server is used. | +| Command arguments | | +| cUrl arguments and flags | The same list of arguments and flags passed to cUrl, except for the following changes:

1. The full Xray URL should not be passed. Instead, the REST endpoint URI should be sent.
2. The login credentials should not be passed. Instead, the --server-id should be used. | + +#### **Examples** + +**Example 1** + +Execute the cUrl client, to send a GET request to the /api/system/version endpoint to the default configured Xray server. +``` +jf xr curl -XGET /api/v1/system/version +``` + +**Example 2** + +Execute the cUrl client, to send a GET request to the /api/v1/system/version endpoint to the configured my-xr-server server ID. +``` +jf rt curl -XGET /api/v1/system/version --server-id my-xr-server +``` + +## On-Demand Binary Scan + +The [on-demand binary scanning](https://jfrog-staging-external.fluidtopics.net/r/help/DevSecOps-Xray/Xray-On-Demand-Binary-Scan)enables you to point to a binary in your local file system and receive a report that contains a list of vulnerabilities, licenses, and policy violations for that binary prior to uploading the binary or build to Artifactory. + +### Scanning Files on the Local File System + +This **jf scan**_ command scans files on the local file system with Xray. + +--- +**Note** +> This command requires: + +* Version 3.29.0 or above of Xray +* Version 2.1.0 or above of JFrog CLI +--- + +| | | +|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Command name** | scan | +| **Abbreviation** | s | +| **Command options** | | +| --server-id | \[Optional\]

Server ID configured using the _jf c add_ command. If not specified, the default configured server is used. | +| --spec | \[Optional\]

Path to a file specifying the files to scan. If the pattern argument is provided to the command, this option should not be provided. | +| --project | \[Optional\]

JFrog project key, to enable Xray to determine security violations accordingly. The command accepts this option only if the --repo-path and --watches options are not provided. If none of the three options are provided, the command will show all known vulnerabilities. | +| --repo-path | \[Optional\]

Artifactory repository path in the form of <repository>/<path in the repository>, to enable Xray to determine violations accordingly. The command accepts this option only if the --project and --watches options are not provided. If none of the three options are provided, the command will show all known vulnerabilities. | +| --watches | \[Optional\]

A comma-separated list of Xray watches, to enable Xray to determine violations accordingly. The command accepts this option only if the --project and --repo-path options are not provided. If none of the three options are provided, the command will show all known vulnerabilities. | +| --licenses | \[Default: false\]

Set if you also require the list of licenses to be displayed. | +| --format=json | \[Optional\]

Produces a JSON file containing the scan results. | +| **Command arguments** | | +| **Pattern** | Specifies the local file system path to artifacts to be scanned. You can specify multiple files by using wildcards. | + +**Output Example** + +![image](images/jf-scan-output.png) + +**Examples** + +**Example 1** + +Scans all the files located at the path/ti/files/ file-system directory using the watch1 watch defined in Xray. +``` +jf s "path/to/files/" --watches "watch1" +``` + +**Example 2** +Scans all the files located at the path/ti/files/ file-system directory using the _watch1_ and _watch2_ Watches defined in Xray. +``` +jf s "path/to/files/" --watches "watch1,watch2" +``` + +**Example 3** + +Scans all the zip files located at the path/ti/files/ file-system directory using the _watch1_ and _watch2_ Watches defined in Xray. +``` +jf s "path/to/files/*.zip" --watches "watch1,watch2" +``` + +**Example 4** + +Scans all the tgz files located at the path/ti/files/ file-system directory using the policies defined for project-1. +``` +jf s "path/to/files/*.tgz" --project "project-1" +``` + +**Example 5** +Scans all the tgz files located in the current directory using the policies defined for the libs-local/release-artifacts/ path in Artifactory. +``` +jf s "*.tgz" --repo-path "libs-local/release-artifacts/" +``` + +**Example 6** +Scans all the tgz files located at the current directory. Show all known vulnerabilities, regardless of the policies defined in Xray. +``` +jf s "*.tgz" +``` + +### Scanning Docker Containers on the Local File System + +This j_**f docker scan**_ command scans docker containers located on the local file-system using the _**docker client**_ and _**JFrog Xray**_. The containers don't need to be deployed to Artifactory or any other container registry before it can be scanned. + +--- +**Note** +> This command requires: + +* Version 3.40.0 or above of Xray +* Version 2.11.0 or above of JFrog CLI +--- + +| | | +|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Command name** | docker scan | +| **Abbreviation** | | +| **Command options** | | +| --server-id | \[Optional\]

Server ID configured using the _jf c add_ command. If not specified, the default configured server is used. | +| --project | \[Optional\]

JFrog project key, to enable Xray to determine security violations accordingly. The command accepts this option only if the --repo-path and --watches options are not provided. If none of the three options are provided, the command will show all known vulnerabilities. | +| --repo-path | \[Optional\]

Artifactory repository path in the form of <repository>/<path in the repository>, to enable Xray to determine violations accordingly. The command accepts this option only if the --project and --watches options are not provided. If none of the three options are provided, the command will show all known vulnerabilities. | +| --watches | \[Optional\]

A comma separated list of Xray watches, to enable Xray to determine violations accordingly. The command accepts this option only if the --repo-path and --repo-path options are not provided. If none of the three options are provided, the command will show all known vulnerabilities. | +| --licenses | \[Default: false\]

Set if you also require the list of licenses to be displayed. | +| --format=json | \[Optional\]

Produces a JSON file containing the scan results. | +| **Command arguments** | | +| **Pattern** | Specifies the local file system path to artifacts to be scanned. You can specify multiple files by using wildcards. | + + + +**Output Example** + +![image](images/docker-scan.png) + +**Examples** + +**Example 1** + +Scan the local _reg1/repo1/img1:1.0.0_ container and show all known vulnerabilities, regardless of the policies defined in Xray. + +``` +$ docker images +REPOSITORY TAG IMAGE ID CREATED SIZE +reg1/repo1/img1 1.0.0 6446ea57df7b 19 months ago 5.57MB +$ +$ jf docker scan reg1/repo1/img1:1.0.0 +``` + + +**Example 2** + +Scan the local _reg1/repo1/img1:1.0.0_ container and show all violations according to the policy associated with _my-project_ JFrog project. + +``` +$ docker images +REPOSITORY TAG IMAGE ID CREATED SIZE +reg1/repo1/img1 1.0.0 6446ea57df7b 19 months ago 5.57MB +$ +$ jf docker scan reg1/repo1/img1:1.0.0 --project my-project +``` + + +**Example 3** + +Scan the local _reg1/repo1/img1:1.0.0_ container and show all violations according to the policy associated with _my-watch_ Xray Watch. + +``` +$ docker images +REPOSITORY TAG IMAGE ID CREATED SIZE +reg1/repo1/img1 1.0.0 6446ea57df7b 19 months ago 5.57MB +$ +$ jf docker scan reg1/repo1/img1:1.0.0 --watches my-watch +``` + + +**Example 4** + +Scan the local _reg1/repo1/img1:1.0.0_ container and show all violations according to the policy associated with the _releases-local/app1/_ path in Artifactory. + +``` +$ docker images +REPOSITORY TAG IMAGE ID CREATED SIZE +reg1/repo1/img1 1.0.0 6446ea57df7b 19 months ago 5.57MB +$ +$ jf docker scan reg1/repo1/img1:1.0.0 --repo-path releases-local/app1/ +``` + +### Scanning Image Tarballs on the Local File System + +The ‘`scan`’ command can be used to scan tarballs of Docker and OCI images on the local file system. + +It requires saving the image on the file system as an uncompressed tarball using a compliant tool, and then scanning it with the ‘`jf s`’ command. The image must be saved to the file system uncompressed, in a `.tar` file name. + +--- +**Note** +> This command requires: + +* Version 3.61.5 or above of Xray. +* Version 2.14.0 or above of JFrog CLI. +--- + + +#### Docker Client + +#### Use Docker client ‘`docker save`’ command to save the image to the file system for scanning. + +**Example**: + + +``` +$ docker images +REPOSITORY TAG IMAGE ID CREATED SIZE +my-image 1.0.0 aaaaabbcccddd 2 months ago 1.12MB + +$ docker save --output my-image-docker.tar my-image:1.0.0 +$ jf s my-image-docker.tar +``` + + +#### Skopeo + +Use Skopeo CLI to save an image to the file system. Output image can be either OCI or Docker format. + +**Example**: + + +``` +$ docker images +REPOSITORY TAG IMAGE ID CREATED SIZE +my-image 1.0.0 aaaaabbcccddd 2 months ago 1.12MB + +// Scan an image in Docker format +$ skopeo copy docker-daemon:my-image:1.0.0 docker-archive:my-image-docker.tar +$ jf s my-image-docker.tar + +// Scan an image in OCI format +$ skopeo copy docker-daemon:my-image:1.0.0 oci-archive:my-image-oci.tar +$ jf s my-image-oci.tar +``` + + +#### Podman + +Use Podman CLI to save an image to the file system. Output image can be either OCI or Docker format. + +**Example**: + + +``` +$ podman images +REPOSITORY TAG IMAGE ID CREATED SIZE +my-image 1.0.0 aaaaabbcccddd 2 months ago 1.12MB + +// Scan an image in Docker format +$ podman save --format=docker-archive -o my-image-docker.tar my-image:1.0.0 +$ jf s my-image-docker.tar + +// Scan an image in OCI format +$ podman save --format=oci -o my-image-oci.tar my-image:1.0.0 +$ jf s my-image-oci.tar +``` + + +#### Kaniko + +Use Kaniko ‘`--tarPath’` flag to save built images to the file system, and later scan them with JFrog CLI. The example below is running Kaniko in Docker. + +**Example**: + + +``` +$ cat Dockerfile + +FROM alpine:3.16 + +$ docker run -it --rm -v $(pwd):/workspace gcr.io/kaniko-project/executor:v1.8.1-debug -f Dockerfile --no-push --tarPath my-image.tar -d my-image:1.0 -c . --cleanup + +$ jf s my-image.tar +``` + +## Scanning Published Builds + +JFrog CLI is integrated with JFrog Xray and JFrog Artifactory, allowing you to have your build artifacts and dependencies scanned for vulnerabilities and license violations. This command allows scanning a build, which had already been published to Artifactory using the [build-publish command](https://jfrog.com/help/r/jfrog-cli/publishing-build-info). + +| | | +|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command name | build-scan | +| Abbreviation | bs | +| Command options | | +| --server-id | \[Optional\]

Server ID configured by the _jf c add_ command. If not specified, the default configured server is used. | +| --vuln | \[Optional\]

Set if you'd like to receive all vulnerabilities, regardless of the policy configured in Xray. | +| --fail | \[Default: true\]

When set, 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. | +| --format | \[Default: table\]

Defines the output format of the command. The accepted values are: **_table_** and _**json**_. | +| --project | \[Optional\]

JFrog project key | +| --rescan | \[Default: false\]

Set to true when scanning an already successfully scanned build, for example after adding an ignore rule. | +| Command arguments | The command accepts two arguments. | +| Build name | Build name to be scanned. | +| Build number | Build number to be scanned. | + +##### Example +``` +jf bs my-build-name 18 +``` + +## Downloading updates for Xray's database + +The offline-update command downloads updates to Xray's vulnerabilities database. The Xray UI allows building the command structure for you. + +| | | +|-------------------|------------------------------------------------------------------------------------------------------------| +| Command name | xr offline-update | +| Abbreviation | xr ou | +| Command options | | +| --license-id | \[Mandatory\]

Xray license ID. | +| --from | \[Optional\]

From update date in YYYY-MM-DD format. | +| --to | \[Optional\]

To update date in YYYY-MM-DD format. | +| --version | \[Optional\]

Xray API version. | +| --target | \[Default: ./\]

Path for downloaded update files. | +| --dbsyncv3 | \[Default: false\]

Set to true to use Xray DBSync V3. | +| --periodic | \[Default: false\]

Set to true to get the Xray DBSync V3 Periodic Package (Use with dbsyncv3 flag). | +| Command arguments | The command accepts no arguments. | + +* * * diff --git a/documentation/JFrog-CLI.md b/documentation/JFrog-CLI.md index 4be56f28c..046f351fd 100644 --- a/documentation/JFrog-CLI.md +++ b/documentation/JFrog-CLI.md @@ -1 +1,531 @@ -The documentation for JFrog CLI has been relocated to [this](https://docs.jfrog-applications.jfrog.io/jfrog-applications/jfrog-cli) website. \ No newline at end of file +# JFrog CLI +![image](images/jfrog-cli-intro.png) + +## About JFrog CLI +### General + +JFrog CLI is a compact and smart client that provides a simple interface that automates access to JFrog products simplifying your automation scripts making them more readable and easier to maintain. JFrog CLI works with JFrog Artifactory, Xray, Distribution, Pipelines and Mission Control, (through their respective REST APIs) making your scripts more efficient and reliable in several ways: + +### Advanced upload and download capabilities + +JFrog CLI allows you to upload and download artifacts concurrently by a configurable number of threads that help your automated builds run faster. For big artifacts, you can define a number of chunks to split files for parallel download. + +JFrog CLI optimizes both upload and download operations by skipping artifacts that already exist in their target location. Before uploading an artifact, JFrog CLI queries Artifactory with the artifact's checksum. If it already exists in Artifactory's storage, the CLI skips sending the file, and if necessary, Artifactory only updates its database to reflect the artifact upload. Similarly, when downloading an artifact from Artifactory, if the artifact already exists in the same download path, it will be skipped. With checksum optimization, long upload and download operations can be paused in the middle, and then be continued later where they were left off. + +JFrog CLI supports uploading files to Artifactory using wildcard patterns, regular expressions and ANT patterns, giving you an easy way to collect all the files you wish to upload. You can also download files using wildcard patterns. + +### Support for popular package managers and build tools + +JFrog CLI offers comprehensive support for popular package managers and build tools. It seamlessly integrates with package managers like npm, Maven, NuGet, Docker and more, allowing you to easily manage and publish packages. + +### Binaries and dependencies scanning + +JFrog CLI empowers you with robust scanning capabilities to ensure the security and compliance of your software artifacts, including containers. It integrates with JFrog Xray, enabling you to scan and analyze your projects and packages, including containers, for vulnerabilities, license compliance, and quality issues. With JFrog CLI, you can proactively identify and mitigate potential risks, ensuring the integrity and safety of your software supply chain. + +### Support for Build-Info + +Build-Info is a comprehensive metadata Software Bill of Materials (SBOM) that captures detailed information about the components used in a build. It serves as a vital source of information, containing version history, artifacts, project modules, dependencies, and other crucial data collected during the build process. By storing this metadata in Artifactory, developers gain traceability and analysis capabilities to improve the quality and security of their builds. The Build-Info encompasses project module details, artifacts, dependencies, environment variables, and more. It is collected and outputted in a JSON format, facilitating easy access to information about the build and its components. JFrog CLI can create build-info and store the build-info in Artifactory. + +## Contributing to JFrog CLI Documentation +We value your input in making the JFrog CLI documentation better. You can help us enhance and improve it by recommending changes and additions. To contribute, follow these steps: + +1. Go to the JFrog CLI project on GitHub: https://github.com/jfrog/jfrog-cli. +2. Locate the documentation source files under the **documentation** directory at the root of the project. +3. Create a pull request with your proposed changes and additions. Ensure that the target branch for your pull request is **dev**. + +Your contributions will be reviewed, and if accepted, they will be merged into the documentation to benefit the entire JFrog CLI community. + +## Read More + +* [CLI for JFrog Artifactory](https://jfrog.com/help/r/jfrog-cli/cli-for-jfrog-artifactory) +* [CLI for JFrog Curation](https://jfrog.com/help/r/jfrog-cli/cli-for-jfrog-curation) +* [CLI for JFrog Distribution](https://jfrog.com/help/r/jfrog-cli/cli-for-jfrog-distribution) +* [CLI for JFrog Mission Control](https://jfrog.com/help/r/jfrog-cli/cli-for-jfrog-mission-control) +* [CLI for JFrog Pipelines](https://jfrog.com/help/r/jfrog-cli/cli-for-jfrog-pipelines) +* [CLI for JFrog Xray](https://jfrog.com/help/r/jfrog-cli/cli-for-jfrog-xray) +* [CLI for JFrog Release Lifecycle Management](https://jfrog.com/help/r/jfrog-cli/cli-for-jfrog-release-lifecycle-management) +* [Transfer Artifactory Configuration and Files fron Self-Hosted to JFrog Cloud](https://jfrog.com/help/r/jfrog-cli/transfer-artifactory-configuration-and-files-from-self-hosted-to-jfrog-cloud) + +* * * + +## JFrog CLI v2 +### Overview + +JFrog CLI v2 was launched in July 2021. It includes changes to the functionality and usage of some of the legacy JFrog CLI commands. The changes are the result of feedback we received from users over time through GitHub, making the usage and functionality easier and more intuitive. For example, some of the default values changed, and are now more consistent across different commands. We also took this opportunity for improving and restructuring the code, as well as replacing old and deprecated functionality. + +Most of the changes included in v2 are breaking changes compared to the v1 releases. We therefore packaged and released these changes under JFrog CLI v2, allowing users to migrate to v2 only when they are ready. + +New enhancements to JFrog CLI are planned to be introduced as part of V2 only. V1 receives very little development attention nowadays. We therefore encourage users who haven't yet migrated to V2, to do so. + +### List of changes in JFrog CLI v2 + +1. The default value of the _**--flat**_ option is now set to false for the _**jfrog rt upload**_ command. +2. The deprecated syntax of the _**jfrog rt mvn**_ command is no longer supported. To use the new syntax, the project needs to be first configured using the **jfrog rt mvnc** command. +3. The deprecated syntax of the _**jfrog rt gradle**_ command is no longer supported. To use the new syntax, the project needs to be first configured using the _**jfrog rt gradlec**_ command. +4. The deprecated syntax of the **jfrog rt npm** and _**jfrog rt npm-ci**_ commands is no longer supported. To use the new syntax, the project needs to be first configured using the _**jfrog rt npmc**_ command. +5. The deprecated syntax of the _**jfrog rt go**_ command is no longer supported. To use the new syntax, the project needs to be first configured using the _**jfrog rt go-config**_ command. +6. The deprecated syntax of the _**jfrog rt nuget**_ command is no longer supported. To use the new syntax, the project needs to be first configured using the _**jfrog rt nugetc**_ command. +7. All Bintray commands are removed. +8. The _**jfrog rt config**_ command is removed and replaced by the _**jfrog config add**_ command. +9. The _**jfrog rt use**_ command is removed and replaced with the _**jfrog config use**_. +10. The _**--props**_ command option and _**props**_ file spec property for the _**jfrog rt upload**_ command are removed, and replaced with the _**--target-props**_ command option and _**targetProps**_ file spec property respectively. +11. The following commands are removed + ``` + jfrog rt release-bundle-create + jfrog rt release-bundle-delete + jfrog rt release-bundle-distribute + jfrog rt release-bundle-sign + jfrog rt release-bundle-update + ``` + and replaced with the following commands respectively + ``` + jfrog ds release-bundle-create + jfrog ds release-bundle-delete + jfrog ds release-bundle-distribute + jfrog ds release-bundle-sign + jfrog ds release-bundle-update + ``` +12. The _**jfrog rt go-publish**_ command now only supports Artifactory version 6.10.0 and above. Also, the command no longer accepts the target repository as an argument. The target repository should be pre-configured using the _**jfrog rt go-config**_ command. +13. The _**jfrog rt go**_ command no longer falls back to the VCS when dependencies are not found in Artifactory. +14. The _**--deps**_, _**--publish-deps**_, _**--no-registry**_ and _**--self**_ options of the _**jfrog rt go-publish**_ command are now removed. +15. The _**--apiKey**_ option is now removed. The API key should now be passed as the value of the _**--password**_ option. +16. The _**--exclude-patterns**_ option is now removed, and replaced with the _**--exclusions**_ option. The same is true for the _**excludePatterns**_ file spec property, which is replaced with the _**exclusions**_ property. +17. The _**JFROG_CLI_JCENTER\_REMOTE\_SERVER**_ and _**JFROG_CLI_JCENTER\_REMOTE\_REPO**_ environment variables are now removed and replaced with the _**JFROG_CLI_EXTRACTORS_REMOTE**_ environment variable. +18. The _**JFROG_CLI_HOME**_ environment variable is now removed and replaced with the _**JFROG_CLI_HOME_DIR**_ environment variable. +19. The _**JFROG_CLI_OFFER_CONFIG**_ environment variable is now removed and replaced with the _**CI**_ environment variable. Setting CI to true disables all prompts. +20. The directory structure is now changed when the _**jfrog rt download**_ command is used with placeholders and -_**-flat=false**_ (--flat=false is now the default). When placeholders are used, the value of the _**--flat**_ option is ignored. +21. When the **jfrog rt upload** command now uploads symlinks to Artifactory, the target file referenced by the symlink is uploaded to Artifactory with the symlink name. If the **--symlink** options is used, the symlink itself (not the referenced file) is uploaded, with the referenced file as a property attached to the file. + + + +## Download and installation +### General + +To download the executable, please visit the [JFrog CLI Download Site](https://www.jfrog.com/getcli/). + +You can also download the sources from the [JFrog CLI Project](https://github.com/JFrog/jfrog-cli-go) on GitHub where you will also find instructions on how to build JFrog CLI. + +The legacy name of JFrog CLI's executable is _**jfrog**_. In an effort to make the CLI usage easier and more convenient, we recently exposed a series of new installers, which install JFrog CLI with the new _**jf**_ executable name. For backward compatibility, the old installers will remain available. We recommend however migrating to the newer _**jf**_ executable name. + +### JFrog CLI v2 "jf" installers + +The following installers are available for JFrog CLI v2. These installers make JFrog CLI available through the _**jf**_ executable. + +**Debian** +``` +wget -qO - https://releases.jfrog.io/artifactory/jfrog-gpg-public/jfrog\_public\_gpg.key | sudo apt-key add - +echo "deb https://releases.jfrog.io/artifactory/jfrog-debs xenial contrib" | sudo tee -a /etc/apt/sources.list; +apt update; +apt install -y jfrog-cli-v2-jf; +``` + +**RPM** +``` +echo "\[jfrog-cli\]" > jfrog-cli.repo; +echo "name=jfrog-cli" >> jfrog-cli.repo; +echo "baseurl=https://releases.jfrog.io/artifactory/jfrog-rpms" >> jfrog-cli.repo; +echo "enabled=1" >> jfrog-cli.repo; +rpm --import https://releases.jfrog.io/artifactory/jfrog-gpg-public/jfrog\_public\_gpg.key +sudo mv jfrog-cli.repo /etc/yum.repos.d/; +yum install -y jfrog-cli-v2-jf; +``` + +**Homebrew** +``` +brew install jfrog-cli +``` + +**Install with cUrl** +``` +curl -fL https://install-cli.jfrog.io | sh +``` + +**Download with cUrl** +``` +curl -fL https://getcli.jfrog.io/v2-jf | sh +``` + +**NPM** +``` +npm install -g jfrog-cli-v2-jf +``` + +**Docker** +``` +Slim: +docker run releases-docker.jfrog.io/jfrog/jfrog-cli-v2-jf jf -v + +Full: +docker run releases-docker.jfrog.io/jfrog/jfrog-cli-full-v2-jf jf -v +``` + +**Powershell** +``` +powershell "Start-Process -Wait -Verb RunAs powershell '-NoProfile iwr https://releases.jfrog.io/artifactory/jfrog-cli/v2-jf/\[RELEASE\]/jfrog-cli-windows-amd64/jf.exe -OutFile $env:SYSTEMROOT\\system32\\jf.exe'" +``` + +**Chocolatey** +``` +choco install jfrog-cli-v2-jf +``` + + +### JFrog CLI v2 "jfrog" installers + +The following installers are available for JFrog CLI v2. These installers make JFrog CLI available through the _**jfrog**_ executable. + +**Debian** +``` +wget -qO - https://releases.jfrog.io/artifactory/jfrog-gpg-public/jfrog\_public\_gpg.key | sudo apt-key add - +echo "deb https://releases.jfrog.io/artifactory/jfrog-debs xenial contrib" | sudo tee -a /etc/apt/sources.list; +apt update; +apt install -y jfrog-cli-v2; +``` + +**RPM** +``` +echo "\[jfrog-cli\]" > jfrog-cli.repo; +echo "name=jfrog-cli" >> jfrog-cli.repo; +echo "baseurl=https://releases.jfrog.io/artifactory/jfrog-rpms" >> jfrog-cli.repo; +echo "enabled=1" >> jfrog-cli.repo; +rpm --import https://releases.jfrog.io/artifactory/jfrog-gpg-public/jfrog\_public\_gpg.key +sudo mv jfrog-cli.repo /etc/yum.repos.d/; +yum install -y jfrog-cli-v2; +``` + +**Homebrew** +``` +brew install jfrog-cli +``` + +**Download with Curl** +``` +curl -fL https://getcli.jfrog.io/v2 | sh +``` + +**NPM** +``` +npm install -g jfrog-cli-v2 +``` + +**Docker** +``` +Slim: +docker run releases-docker.jfrog.io/jfrog/jfrog-cli-v2 jfrog -v + +Full: +docker run releases-docker.jfrog.io/jfrog/jfrog-cli-full-v2 jfrog -v +``` + +**Chocolatey** +``` +choco install jfrog-cli +``` + +### JFrog CLI v1 (legacy) installers + +The following installations are available for JFrog CLI v1. These installers make JFrog CLI available through the _**jfrog**_ executable. + +**Debian** +``` +wget -qO - https://releases.jfrog.io/artifactory/jfrog-gpg-public/jfrog\_public\_gpg.key | sudo apt-key add - +echo "deb https://releases.jfrog.io/artifactory/jfrog-debs xenial contrib" | sudo tee -a /etc/apt/sources.list; +apt update; +apt install -y jfrog-cli; +``` + +**RPM** +``` +echo "\[jfrog-cli\]" > jfrog-cli.repo; +echo "name=jfrog-cli" >> jfrog-cli.repo; +echo "baseurl=https://releases.jfrog.io/artifactory/jfrog-rpms" >> jfrog-cli.repo; +echo "enabled=1" >> jfrog-cli.repo; +rpm --import https://releases.jfrog.io/artifactory/jfrog-gpg-public/jfrog\_public\_gpg.key +sudo mv jfrog-cli.repo /etc/yum.repos.d/; +yum install -y jfrog-cli; +``` + +**Download with cUrl** +``` +curl -fL https://getcli.jfrog.io | sh +``` + +**NPM** +``` +npm install -g jfrog-cli-go +``` + +**Docker** +``` +Slim: +docker run releases-docker.jfrog.io/jfrog/jfrog-cli jfrog -v + +Full: +docker run releases-docker.jfrog.io/jfrog/jfrog-cli-full jfrog -v +``` + +**Go** +``` +GO111MODULE=on go get github.com/jfrog/jfrog-cli; +if \[ -z "$GOPATH" \] +then binPath="$HOME/go/bin"; +else binPath="$GOPATH/bin"; +fi; +mv "$binPath/jfrog-cli" "$binPath/jfrog"; +echo "$($binPath/jfrog -v) is installed at $binPath"; +``` + +## System Requirements + +JFrog CLI runs on any modern OS that fully supports the [Go programming language](https://golang.org/). + + + +## Usage + +To use the CLI, [install](https://jfrog.com/getcli/) it on your local machine, or [download](https://jfrog.com/getcli/) its executable, place it anywhere in your file system and add its location to your `PATH` environment variable. + +### Environment Variables + +The **jf options** command displays all the supported environment variables. + +JFrog CLI makes use of the following environment variables: + +| | | +|------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Variable Name** | **Description** | +| **JFROG_CLI_LOG_LEVEL** | \[Default: INFO\]

This variable determines the log level of the JFrog CLI.
Possible values are: DEBUG, INFO, WARN and ERROR.
If set to ERROR, JFrog CLI logs error messages only. It is useful when you wish to read or parse the JFrog CLI output and do not want any other information logged. | +| **JFROG_CLI_LOG_TIMESTAMP** | \[Default: TIME\]

Controls the log messages timestamp format. Possible values are: TIME, DATE\_AND\_TIME, and OFF. | +| **JFROG_CLI_HOME_DIR** | \[Default: ~/.jfrog\]

Defines the JFrog CLI home directory. | +| **JFROG_CLI_TEMP_DIR** | \[Default: The operating system's temp directory\]

Defines the temp directory used by JFrog CLI. | +| **JFROG_CLI_PLUGINS_SERVER** | \[Default: Official JFrog CLI Plugins registry\]

Configured Artifactory server ID from which to download JFrog CLI Plugins. | +| **JFROG_CLI_PLUGINS_REPO** | \[Default: 'jfrog-cli-plugins'\]

Can be optionally used with the JFROG_CLI_PLUGINS_SERVER environment variable. Determines the name of the local repository to use. | +| **JFROG_CLI_RELEASES_REPO** | Configured Artifactory repository name from which to download the jar needed by the mvn/gradle command.
This environment variable's value format should be `/`.
The repository should proxy https://releases.jfrog.io.
This environment variable is used by the 'jf mvn' and 'jf gradle' commands, and also by the 'jf audit' command, when used for maven or gradle projects. | +| **JFROG_CLI_SERVER_ID** | Server ID configured using the config command, unless sent as a command argument or option. | +| **CI** | \[Default: false\]

If true, disables interactive prompts and progress bar. | + +## JFrog Platform Configuration + +### Web Login to the JFrog Platform + +You can use the `jf login` command to authenticate with the JFrog Platform through the web browser. +This command is solely interactive, meaning it does not receive any options and cannot be used in a CI server. + +![login-page.png](images/login-page.png) +![login-successful.png](images/login-successful.png) + +### Adding and Editing Configured Servers + +The `jf config add` and `jf config edit` commands are used to add and edit JFrog Platform server configuration, stored in JFrog CLI's configuration storage. These configured servers can be used by the other commands. The configured servers' details can be overridden per command by passing in alternative values for the URL and login credentials. The values configured are saved in file under the JFrog CLI home directory. + +| | | +|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command name | config add / config edit | +| Abbreviation | c add / c edit | +| Command options | | +| --access-token | \[Optional\]

Access token. | +| --artifactory-url | \[Optional\]

Artifactory URL. | +| --basic-auth-only | \[Default: false\]

Used for Artifactory authentication. Set to true to disable replacing username and password/API key with automatically created access token that's refreshed hourly. Username and password/API key will still be used with commands which use external tools or the JFrog Distribution service. Can only be passed along with username and password/API key options. | +| --client-cert-key-path | \[Optional\]

Private key file for the client certificate in PEM format. | +| --client-cert-path | \[Optional\]

Client certificate file in PEM format. | +| --dist-url | \[Optional\]

Distribution URL. | +| --enc-password | \[Default: true\]

If true, the configured password will be encrypted using Artifactory's[encryption API](https://www.jfrog.com/confluence/display/RTF/Artifactory+REST+API#ArtifactoryRESTAPI-GetUserEncryptedPassword)before being stored. If false, the configured password will not be encrypted. | +| --insecure-tls | Default: false\]

Set to true to skip TLS certificates verification, while encrypting the Artifactory password during the config process. | +| --interactive | \[Default: true, unless $CI is true\]

Set to false if you do not want the config command to be interactive. | +| --mission-control-url | \[Optional\]

Mission Control URL. | +| --password | \[Optional\]

JFrog Platform password. | +| --pipelines-url | \[Optional\]

Pipelines URL. | +| --ssh-key-path | \[Optional\]

For authentication with Artifactory. SSH key file path. | +| --url | \[Optional\]

JFrog platform URL. | +| --user | \[Optional\]

JFrog Platform username. | +| --xray-url | \[Optional\] Xray URL. | +| --overwrite | \[Available for `jf config add` only\]

\[Default: false\]

Overwrites the instance configuration if an instance with the same ID already exists. | +| Command arguments | | +| server ID | A unique ID for the server configuration. | + +### Removing Configured Servers + +The `jf config remove` command is used to remove JFrog Platform server configuration, stored in JFrog CLI's configuration storage. + +| | | +|-------------------|--------------------------------------------------------------------------------------| +| Command name | config remove | +| Abbreviation | c rm | +| Command options | | +| --quiet | \[Default: $CI\]

Set to true to skip the delete confirmation message. | +| Command arguments | | +| server ID | The server ID to remove. If no argument is sent, all configured servers are removed. | + +### Showing the Configured Servers + +The `jf config show` command shows the stored configuration. You may show a specific server's configuration by sending its ID as an argument to the command. + +| | | +|-------------------|-----------------------------------------------------------------------------------------| +| Command name | config show | +| Abbreviation | c s | +| Command arguments | | +| server ID | The ID of the server to show. If no argument is sent, all configured servers are shown. | + +### Setting a Server as Default + +The `jf config use` command sets a configured server as default. The following commands will use this server. + +| | | +|-------------------|-----------------------------------------| +| Command name | config use | +| Command arguments | | +| server ID | The ID of the server to set as default. | + +### Exporting and Importing Configuration + +The `jf config export` command generates a token, which stores the server configuration. This token can be used by the `jf config import` command, to import the configuration stored in the token, and save it in JFrog CLI's configuration storage. + +#### Export + +| | | +|-------------------|--------------------------------| +| Command name | config export | +| Abbreviation | c ex | +| Command arguments | | +| server ID | The ID of the server to export | + +#### Import + +| | | +|-------------------|---------------------| +| Command name | config import | +| Abbreviation | c im | +| Command arguments | | +| server token | The token to import | + +## Setting up a CI Pipeline + +The **ci-setup** command allows setting up a basic CI pipeline with the JFrog Platform, while automatically configuring the JFrog Platform to serve the pipeline. It is an interactive command, which prompts you with a series for questions, such as your source control details, your build tool, build command and your CI provider. The command then uses this information to do following: + +* Create the repositories in JFrog Artifactory, to be used by the pipeline to resolve dependencies. +* Configure JFrog Xray to scan the build. +* Generate a basic CI pipeline, which builds and scans your code. + +You can use the generated CI pipeline as a working starting point and then expand it as needed. + +The command currently supports the following package managers: + +* Maven +* Gradle +* npm. + +and the following CI providers: + +* JFrog Pipelines +* Jenkins +* GitHub Actions. + +Usage: +``` +jf ci-setup +``` + + +## Proxy Support + +JFrog CLI supports using an HTTP/S proxy. All you need to do is set HTTP_PROXY or HTTPS_PROXY environment variable with the proxy URL. + +HTTP_PROXY, HTTPS_PROXY and NO_PROXY are the industry standards for proxy usages. + +| | | +|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Variable Name** | **Description** | +| HTTP_PROXY | Determines a URL to an HTTP proxy. | +| HTTPS_PROXY | Determines a URL to an HTTPS proxy. | +| NO_PROXY | Use this variable to bypass the proxy to IP addresses, subnets or domains. This may contain a comma-separated list of hostnames or IPs without protocols and ports. A typical usage may be to set this variable to Artifactory’s IP address. | + +## Shell Auto-Completion + +If you're using JFrog CLI from a bash, zsh, or fish shells, you can install JFrog CLI's auto-completion scripts. + +### Install JFrog CLI with Homebrew? +If you're installing JFrog CLI using Homebrew, the bash, zsh, or fish auto-complete scripts are automatically installed by Homebrew. Please make sure that your _.bash_profile_ or _.zshrc_ are configured as described in the [Homebrew Shell Completion documentation](https://docs.brew.sh/Shell-Completion). + +### Using Oh My Zsh? +With your favourite text editor, open $HOME/.zshrc and add **jfrog** to the plugin list. + +For example: +``` +plugins=(git mvn npm sdk jfrog) +``` + +To install auto-completion for **bash**, run the following command and follow the instructions to complete the installation: +``` +jf completion bash --install +``` + +To install auto-completion for **zsh**, run the following command and follow the instructions to complete the installation: +``` +jf completion zsh --install +``` + +To install auto-completion for **fish**, run the following command: +``` +jf completion fish --install +``` + +## Sensitive Data Encryption + +Since version 1.37.0, JFrog CLI supports encrypting the sensitive data stored in JFrog CLI's config. To enable encryption, follow these steps. + +* Create a random 32 character master key. Make sure that the key size is exactly 32 characters. For example _f84hc22dQfhe9f8ydFwfsdn48!wejh8A_ +* Create a file named **security.yaml** under **~/.jfrog/security**. + +> If you modified the default JFrog CLI home directory by setting JFROG_CLI_HOME_DIR environment variable, then the **security/security.yaml** file should br created under the configured home directory. + +* Add the master key you generated to security.yaml. The file content should be: + +``` +version: 1 +masterKey: "your master key" +``` +* Make sure that the only permission security.yaml has is read for the user running JFrog CLI. + +The configuration will be encrypted the next time JFrog CLI attempts to access the config. + +> Warning: When upgrading JFrog CLI from a version prior to 1.37.0 to version 1.37.0 or above, JFrog CLI automatically makes changes to the content of the ~/`_.jfrog_` directory, to support the new functionality introduced in version 1.37.0. Before making these changes, the content of the `_~/.jfrog_` directory is backed up inside the ~/`_.jfrog/backup_` directory. Therefore, after enabling sensitive data encryption, it is recommended to remove the `_backup_` directory, to ensure no sensitive data is left unencrypted. + + +## JFrog CLI Plugins +### General + +JFrog CLI Plugins allow enhancing the functionality of JFrog CLI to meet the specific user and organization needs. The source code of a plugin is maintained as an open source Go project on GitHub. All public plugins are registered in [JFrog CLI's Plugins Registry](https://github.com/jfrog/jfrog-cli-plugins-reg). We encourage you, as developers, to create plugins and share them publicly with the rest of the community. When a plugin is included in the registry, it becomes publicly available and can be installed using JFrog CLI. Read the [JFrog CLI Plugins Developer Guide](https://github.com/jfrog/jfrog-cli/blob/dev/guides/jfrog-cli-plugins-developer-guide.md) if you wish to create and publish your own plugins. + +### Installing Plugins + +A plugin which is included [JFrog CLI's Plugins Registry](https://github.com/jfrog/jfrog-cli-plugins-reg) can be installed using the following command. +``` +$ jf plugin install the-plugin-name +``` +This command will install the plugin from the official public registry by default. You can also install a plugin from a private JFrog CLI Plugin registry, as described in the _Private Plugins Registries_ section. + +### Private Plugins Registries + +In addition to the public official JFrog CLI Plugins Registry, JFrog CLI supports publishing and installing plugins to and from private JFrog CLI Plugins Registries. A private registry can be hosted on any Artifactory server. It uses a local generic Artifactory repository for storing the plugins. + +To create your own private plugins registry, follow these steps. + +* On your Artifactory server, create a local generic repository named _jfrog-cli-plugins_. +* Make sure your Artifactory server is included in JFrog CLI's configuration, by running the _jf c show_ command. +* If needed, configure your Artifactory instance using the _jfrog c add_ command. +* Set the ID of the configured server as the value of the JFROG_CLI_PLUGINS_SERVER environment variable. +* If you wish the name of the plugins repository to be different from jfrog-cli-plugins, set this name as the value of the JFROG_CLI_PLUGINS_REPO environment variable. + +The **jf plugin install** command will now install plugins stored in your private registry. + +To publish a plugin to the private registry, run the following command, while inside the root of the plugin's sources directory. This command will build the sources of the plugin for all the supported operating systems. All binaries will be uploaded to the configured registry. +``` +jf plugin publish the-plugin-name the-plugin-version +``` + +## Release Notes +* [Release notes](https://github.com/jfrog/jfrog-cli/releases) for [JFrog CLI v2](https://jfrog.com/help/r/jfrog-cli/jfrog-cli-v2) +* [Release notes](https://github.com/jfrog/jfrog-cli/blob/v1/RELEASE.md#release-notes) for the legacy releases of JFrog CLI + + diff --git a/documentation/images/audit1.png b/documentation/images/audit1.png new file mode 100644 index 000000000..104eaebea Binary files /dev/null and b/documentation/images/audit1.png differ diff --git a/documentation/images/audit2.png b/documentation/images/audit2.png new file mode 100644 index 000000000..dc7cd7adc Binary files /dev/null and b/documentation/images/audit2.png differ diff --git a/documentation/images/audit3.png b/documentation/images/audit3.png new file mode 100644 index 000000000..916f1a95c Binary files /dev/null and b/documentation/images/audit3.png differ diff --git a/documentation/images/docker-scan.png b/documentation/images/docker-scan.png new file mode 100644 index 000000000..eaf738e63 Binary files /dev/null and b/documentation/images/docker-scan.png differ diff --git a/documentation/images/jf-ca-output.png b/documentation/images/jf-ca-output.png new file mode 100644 index 000000000..c44a614eb Binary files /dev/null and b/documentation/images/jf-ca-output.png differ diff --git a/documentation/images/jf-scan-output.png b/documentation/images/jf-scan-output.png new file mode 100644 index 000000000..d38917734 Binary files /dev/null and b/documentation/images/jf-scan-output.png differ diff --git a/documentation/images/jfrog-cli-intro.png b/documentation/images/jfrog-cli-intro.png new file mode 100644 index 000000000..67650a7e5 Binary files /dev/null and b/documentation/images/jfrog-cli-intro.png differ diff --git a/documentation/images/login-page.png b/documentation/images/login-page.png new file mode 100644 index 000000000..8f133dede Binary files /dev/null and b/documentation/images/login-page.png differ diff --git a/documentation/images/login-successful.png b/documentation/images/login-successful.png new file mode 100644 index 000000000..6390fc94b Binary files /dev/null and b/documentation/images/login-successful.png differ diff --git a/documentation/images/transfer-1.png b/documentation/images/transfer-1.png new file mode 100644 index 000000000..9a5274175 Binary files /dev/null and b/documentation/images/transfer-1.png differ diff --git a/documentation/images/transfer-2.png b/documentation/images/transfer-2.png new file mode 100644 index 000000000..d969d6fc1 Binary files /dev/null and b/documentation/images/transfer-2.png differ diff --git a/documentation/images/transfer-3.png b/documentation/images/transfer-3.png new file mode 100644 index 000000000..c963cfa31 Binary files /dev/null and b/documentation/images/transfer-3.png differ diff --git a/documentation/images/transfer-4.png b/documentation/images/transfer-4.png new file mode 100644 index 000000000..1bd3ea2b8 Binary files /dev/null and b/documentation/images/transfer-4.png differ diff --git a/documentation/images/transfer-5.png b/documentation/images/transfer-5.png new file mode 100644 index 000000000..943d7b218 Binary files /dev/null and b/documentation/images/transfer-5.png differ diff --git a/documentation/images/transfer-files-progress.png b/documentation/images/transfer-files-progress.png new file mode 100644 index 000000000..1bd3ea2b8 Binary files /dev/null and b/documentation/images/transfer-files-progress.png differ diff --git a/documentation/images/transfer-files-status.png b/documentation/images/transfer-files-status.png new file mode 100644 index 000000000..943d7b218 Binary files /dev/null and b/documentation/images/transfer-files-status.png differ diff --git a/go.mod b/go.mod index 74cefe8c1..7fe0e0330 100644 --- a/go.mod +++ b/go.mod @@ -7,10 +7,10 @@ require ( github.com/buger/jsonparser v1.1.1 github.com/go-git/go-git/v5 v5.9.0 github.com/gocarina/gocsv v0.0.0-20230616125104-99d496ca653d - github.com/jfrog/build-info-go v1.9.16 - github.com/jfrog/gofrog v1.3.2 - github.com/jfrog/jfrog-cli-core/v2 v2.47.0 - github.com/jfrog/jfrog-client-go v1.35.0 + github.com/jfrog/build-info-go v1.9.15 + github.com/jfrog/gofrog v1.3.1 + github.com/jfrog/jfrog-cli-core/v2 v2.46.1 + github.com/jfrog/jfrog-client-go v1.34.5 github.com/jszwec/csvutil v1.8.0 github.com/mholt/archiver/v3 v3.5.1 github.com/stretchr/testify v1.8.4 @@ -129,10 +129,10 @@ require ( gopkg.in/yaml.v3 v3.0.1 // indirect ) -// replace github.com/jfrog/build-info-go => github.com/jfrog/build-info-go v1.8.9-0.20231130093251-25c79868c10c +// replace github.com/jfrog/build-info-go => github.com/jfrog/build-info-go v1.8.9-0.20231107094842-97a0ca9da395 -// replace github.com/jfrog/jfrog-cli-core/v2 => github.com/jfrog/jfrog-cli-core/v2 v2.31.1-0.20231130101652-2aaa8c0c51ec +// replace github.com/jfrog/jfrog-cli-core/v2 => github.com/jfrog/jfrog-cli-core/v2 v2.31.1-0.20231105094115-13b1588fc537 -// replace github.com/jfrog/gofrog => github.com/jfrog/gofrog v1.3.2-0.20231130091721-6d742be8bc7a +// replace github.com/jfrog/gofrog => github.com/jfrog/gofrog v1.2.6-0.20230418122323-2bf299dd6d27 -// replace github.com/jfrog/jfrog-client-go => github.com/jfrog/jfrog-client-go v1.28.1-0.20231126134442-14887b84b87a +// replace github.com/jfrog/jfrog-client-go => github.com/jfrog/jfrog-client-go v1.28.1-0.20231101142932-422f20520a28 diff --git a/go.sum b/go.sum index 0b90df0fa..a1346db72 100644 --- a/go.sum +++ b/go.sum @@ -237,16 +237,16 @@ github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99 h1:BQSFePA1RWJOl github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99/go.mod h1:1lJo3i6rXxKeerYnT8Nvf0QmHCRC1n8sfWVwXF2Frvo= github.com/jedib0t/go-pretty/v6 v6.4.8 h1:HiNzyMSEpsBaduKhmK+CwcpulEeBrTmxutz4oX/oWkg= github.com/jedib0t/go-pretty/v6 v6.4.8/go.mod h1:Ndk3ase2CkQbXLLNf5QDHoYb6J9WtVfmHZu9n8rk2xs= -github.com/jfrog/build-info-go v1.9.16 h1:zMNxUXve4CZndhlbaEGwgayWPY8CRyPzSobvTKYRPcg= -github.com/jfrog/build-info-go v1.9.16/go.mod h1:/5VZXH2Ud0IK3cOFwPykjwPOaEcHhzzbjnRiou+YKpM= -github.com/jfrog/gofrog v1.3.2 h1:TktKP+PdZdxjkYZxWWIq4DkTGSYtr9Slsy+egZpEhUY= -github.com/jfrog/gofrog v1.3.2/go.mod h1:AQo5Fq0G9nDEF6icH7MYQK0iohR4HuEAXl8jaxRuT6Q= +github.com/jfrog/build-info-go v1.9.15 h1:DN7DKZq6H5FlHfL3Lu8fo4t2INgczRgT09dJiZjJ1oo= +github.com/jfrog/build-info-go v1.9.15/go.mod h1:XVFk2rCYhIdc7+hIGE8TC3le5PPM+xYHU22udoE2b7Q= +github.com/jfrog/gofrog v1.3.1 h1:QqAwQXCVReT724uga1AYqG/ZyrNQ6f+iTxmzkb+YFQk= +github.com/jfrog/gofrog v1.3.1/go.mod h1:IFMc+V/yf7rA5WZ74CSbXe+Lgf0iApEQLxRZVzKRUR0= github.com/jfrog/jfrog-apps-config v1.0.1 h1:mtv6k7g8A8BVhlHGlSveapqf4mJfonwvXYLipdsOFMY= github.com/jfrog/jfrog-apps-config v1.0.1/go.mod h1:8AIIr1oY9JuH5dylz2S6f8Ym2MaadPLR6noCBO4C22w= -github.com/jfrog/jfrog-cli-core/v2 v2.47.0 h1:sY3iQurLL4/z/HJRkoLKvoN8hezEk/dupsvAgURUoGI= -github.com/jfrog/jfrog-cli-core/v2 v2.47.0/go.mod h1:RFQwrZ1qXAQ+X0xfuzxBBDIYuRnDsPy12xlyjuOpUog= -github.com/jfrog/jfrog-client-go v1.35.0 h1:VTyrR/jFlWInRdGYswa2fwFc1Thsh6eGMnHuqhDVh7s= -github.com/jfrog/jfrog-client-go v1.35.0/go.mod h1:cG0vdKXbyfupKgSYmwA5FZPco6zSfyJi3eEYOxuqm/k= +github.com/jfrog/jfrog-cli-core/v2 v2.46.1 h1:4bkyykJk9OUJFXW44NmYGlOmhu6HVG43KUtY5p/wsQA= +github.com/jfrog/jfrog-cli-core/v2 v2.46.1/go.mod h1:S+KpcxVw9O3jY1KtzvbFtnejinc4GgbykQNhLLtfR8I= +github.com/jfrog/jfrog-client-go v1.34.5 h1:NYZrOHvT5D5BwwHdArIz5WnbP+DPbADjV/SPdN33bfQ= +github.com/jfrog/jfrog-client-go v1.34.5/go.mod h1:0PVhP6xGvBBaUzOU9LKf5OYkke/gY2IFILHA++iabFM= github.com/jstemmer/go-junit-report v0.0.0-20190106144839-af01ea7f8024/go.mod h1:6v2b51hI/fHJwM22ozAgKL4VKDeJcHhJFhtBdhmNjmU= github.com/jstemmer/go-junit-report v0.9.1/go.mod h1:Brl9GWCQeLvo8nXZwPNNblvFj/XSXhF0NWZEnDohbsk= github.com/jszwec/csvutil v1.8.0 h1:G7vS2LGdpZZDH1HmHeNbxOaJ/ZnJlpwGFvOkTkJzzNk= diff --git a/inttestutils/transfer.go b/inttestutils/transfer.go index 1422d5649..8d6ce6a72 100644 --- a/inttestutils/transfer.go +++ b/inttestutils/transfer.go @@ -154,7 +154,7 @@ func AsyncUpdateThreads(wg *sync.WaitGroup, filesTransferFinished *bool, t *test // Wait for the number of threads to be updated to the non-zero default and increace the number of threads by 1 for !*filesTransferFinished { - threadsCount = transferfiles.GetChunkBuilderThreads() + threadsCount = transferfiles.GetThreads() if threadsCount == 0 { time.Sleep(time.Second) continue @@ -166,13 +166,13 @@ func AsyncUpdateThreads(wg *sync.WaitGroup, filesTransferFinished *bool, t *test // Wait for the number of threads to be increase by 1 for !*filesTransferFinished { - if transferfiles.GetChunkBuilderThreads() == threadsCount+1 { + if transferfiles.GetThreads() == threadsCount+1 { return } time.Sleep(time.Second) } // If false, the transfer-files process is finished before the threads changed - assert.Failf(t, "Number of threads did not change as expected", "Actual: %d, Expected: %d", transferfiles.GetChunkBuilderThreads(), threadsCount+1) + assert.Failf(t, "Number of threads did not change as expected", "Actual: %d, Expected: %d", transferfiles.GetThreads(), threadsCount+1) }() } diff --git a/lifecycle_test.go b/lifecycle_test.go index 719834409..16fc61248 100644 --- a/lifecycle_test.go +++ b/lifecycle_test.go @@ -192,8 +192,6 @@ func deleteReleaseBundle(t *testing.T, lcManager *lifecycle.LifecycleServicesMan } assert.NoError(t, lcManager.DeleteReleaseBundle(rbDetails, services.ReleaseBundleQueryParams{Async: false})) - // Wait after remote deleting. Can be removed once remote deleting supports sync. - time.Sleep(5 * time.Second) } func remoteDeleteReleaseBundle(t *testing.T, lcManager *lifecycle.LifecycleServicesManager, rbName, rbVersion string) { diff --git a/main_test.go b/main_test.go index f9d4fb07b..41805010a 100644 --- a/main_test.go +++ b/main_test.go @@ -55,7 +55,7 @@ func setupIntegrationTests() { if (*tests.TestArtifactory && !*tests.TestArtifactoryProxy) || *tests.TestArtifactoryProject { InitArtifactoryTests() } - if *tests.TestNpm || *tests.TestGradle || *tests.TestMaven || *tests.TestGo || *tests.TestNuget || *tests.TestPip || *tests.TestPipenv { + if *tests.TestNpm || *tests.TestGradle || *tests.TestMaven || *tests.TestGo || *tests.TestNuget || *tests.TestPip || *tests.TestPipenv || *tests.TestPoetry { InitBuildToolsTests() } if *tests.TestDocker || *tests.TestPodman || *tests.TestDockerScan { @@ -85,7 +85,7 @@ func tearDownIntegrationTests() { if (*tests.TestArtifactory && !*tests.TestArtifactoryProxy) || *tests.TestArtifactoryProject { CleanArtifactoryTests() } - if *tests.TestNpm || *tests.TestGradle || *tests.TestMaven || *tests.TestGo || *tests.TestNuget || *tests.TestPip || *tests.TestPipenv || *tests.TestDocker || *tests.TestPodman || *tests.TestDockerScan { + if *tests.TestNpm || *tests.TestGradle || *tests.TestMaven || *tests.TestGo || *tests.TestNuget || *tests.TestPip || *tests.TestPipenv || *tests.TestPoetry || *tests.TestDocker || *tests.TestPodman || *tests.TestDockerScan { CleanBuildToolsTests() } if *tests.TestDistribution { diff --git a/pipenv_test.go b/pipenv_test.go index f5b7b9bc6..5293e5a6e 100644 --- a/pipenv_test.go +++ b/pipenv_test.go @@ -20,6 +20,7 @@ import ( func TestPipenvInstall(t *testing.T) { // Init pipenv test. initPipenvTest(t) + tests.SkipKnownFailingTest(t) // Populate cli config with 'default' server. oldHomeDir, newHomeDir := prepareHomeDir(t) diff --git a/poetry_test.go b/poetry_test.go new file mode 100644 index 000000000..3188ad34d --- /dev/null +++ b/poetry_test.go @@ -0,0 +1,129 @@ +package main + +import ( + biutils "github.com/jfrog/build-info-go/utils" + "os" + "path/filepath" + "strconv" + "testing" + + clientTestUtils "github.com/jfrog/jfrog-client-go/utils/tests" + + buildinfo "github.com/jfrog/build-info-go/entities" + "github.com/jfrog/jfrog-cli-core/v2/utils/coreutils" + "github.com/jfrog/jfrog-cli/inttestutils" + "github.com/jfrog/jfrog-cli/utils/tests" + "github.com/jfrog/jfrog-client-go/utils/io/fileutils" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestPoetryInstall(t *testing.T) { + // Init poetry test. + initPoetryTest(t) + tests.SkipKnownFailingTest(t) + // Populate cli config with 'default' server. + oldHomeDir, newHomeDir := prepareHomeDir(t) + defer func() { + assert.NoError(t, os.Setenv(coreutils.HomeDir, oldHomeDir)) + assert.NoError(t, fileutils.RemoveTempDir(newHomeDir)) + }() + + // Create test cases. + allTests := []struct { + name string + project string + outputFolder string + moduleId string + args []string + cleanAfterExecution bool + }{ + {"poetry", "poetryproject", "cli-poetry-build", "cli-poetry-build:0.1.0", []string{"poetry", "install", "--build-name=" + tests.PoetryBuildName}, true}, + } + + // Run test cases. + for buildNumber, test := range allTests { + t.Run(test.name, func(t *testing.T) { + testPoetryCmd(t, createPoetryProject(t, test.outputFolder, test.project), strconv.Itoa(buildNumber), test.moduleId, test.args) + if test.cleanAfterExecution { + // cleanup + inttestutils.DeleteBuild(serverDetails.ArtifactoryUrl, tests.PoetryBuildName, artHttpDetails) + } + }) + } + tests.CleanFileSystem() +} + +func testPoetryCmd(t *testing.T, projectPath, buildNumber, module string, args []string) { + wd, err := os.Getwd() + assert.NoError(t, err, "Failed to get current dir") + chdirCallback := clientTestUtils.ChangeDirWithCallback(t, wd, projectPath) + defer chdirCallback() + + args = append(args, "--build-number="+buildNumber) + + jfrogCli := tests.NewJfrogCli(execMain, "jf", "") + err = jfrogCli.WithoutCredentials().Exec(args...) + if err != nil { + assert.Fail(t, "Failed executing poetry install command", err.Error()) + return + } + + inttestutils.ValidateGeneratedBuildInfoModule(t, tests.PoetryBuildName, buildNumber, "", []string{module}, buildinfo.Python) + assert.NoError(t, artifactoryCli.Exec("bp", tests.PoetryBuildName, buildNumber)) + + publishedBuildInfo, found, err := tests.GetBuildInfo(serverDetails, tests.PoetryBuildName, buildNumber) + if err != nil { + assert.NoError(t, err) + return + } + if !found { + assert.True(t, found, "build info was expected to be found") + return + } + + buildInfo := publishedBuildInfo.BuildInfo + require.NotEmpty(t, buildInfo.Modules, "Poetry build info was not generated correctly, no modules were created.") + assert.Len(t, buildInfo.Modules[0].Dependencies, 3, "Incorrect number of artifacts found in the build-info") + assert.Equal(t, module, buildInfo.Modules[0].Id, "Unexpected module name") + assertPoetryDependenciesRequestedBy(t, buildInfo.Modules[0], module) +} + +func assertPoetryDependenciesRequestedBy(t *testing.T, module buildinfo.Module, moduleName string) { + for _, dependency := range module.Dependencies { + switch dependency.Id { + case "toml:0.10.2", "pexpect:4.8.0": + assert.EqualValues(t, [][]string{{moduleName}}, dependency.RequestedBy) + case "ptyprocess:0.7.0": + assert.EqualValues(t, [][]string{{"pexpect:4.8.0", moduleName}}, dependency.RequestedBy) + default: + assert.Fail(t, "Unexpected dependency "+dependency.Id) + } + } +} + +func createPoetryProject(t *testing.T, outFolder, projectName string) string { + projectSrc := filepath.Join(filepath.FromSlash(tests.GetTestResourcesPath()), "poetry", projectName) + projectTarget := filepath.Join(tests.Out, outFolder+"-poetry-"+projectName) + err := fileutils.CreateDirIfNotExist(projectTarget) + assert.NoError(t, err) + + // Copy poetry project + err = biutils.CopyDir(projectSrc, projectTarget, true, nil) + assert.NoError(t, err) + + // Copy poetry-config file. + configSrc := filepath.Join(filepath.FromSlash(tests.GetTestResourcesPath()), "poetry", "poetry.yaml") + configTarget := filepath.Join(projectTarget, ".jfrog", "projects") + _, err = tests.ReplaceTemplateVariables(configSrc, configTarget) + assert.NoError(t, err) + return projectTarget +} + +func initPoetryTest(t *testing.T) { + if !*tests.TestPoetry { + t.Skip("Skipping Poetry test. To run Poetry test add the '-test.poetry=true' option.") + } + require.True(t, isRepoExist(tests.PoetryRemoteRepo), tests.PoetryRemoteRepo+" test repository doesn't exist.") + require.True(t, isRepoExist(tests.PoetryVirtualRepo), tests.PoetryVirtualRepo+" test repository doesn't exist.") +} diff --git a/schema/filespec-schema.json b/schema/filespec-schema.json index 37b5892dc..ef325c155 100644 --- a/schema/filespec-schema.json +++ b/schema/filespec-schema.json @@ -42,21 +42,6 @@ } } }, - "pathMapping": { - "description": "If specified, determines release-bundle source and target paths for artifacts that had been fetched using aql.", - "properties": { - "input": { - "type": "string", - "description": "The input path for mapping.", - "examples": ["(.*)/old_folder/(.*)"] - }, - "output": { - "type": "string", - "description": "The output path for mapping.", - "examples": ["$1/new_folder/$2"] - } - } - }, "archive": { "type": "string", "enum": ["zip"], @@ -242,7 +227,6 @@ ] } }, - "pathMapping": { "required": ["aql"] }, "build": { "not": { "required": ["bundle", "limit", "offset"] } }, "bundle": { "not": { "required": ["build", "limit", "offset"] } }, "excludeArtifacts": { "required": ["build"] }, diff --git a/testdata/filespecs/dist_create_with_mapping.json b/testdata/filespecs/dist_create_with_mapping.json index 72b6075de..98502d1d9 100644 --- a/testdata/filespecs/dist_create_with_mapping.json +++ b/testdata/filespecs/dist_create_with_mapping.json @@ -1,20 +1,8 @@ { "files": [ { - "aql": { - "items.find": { - "repo": "${DIST_REPO1}", - "path": "data", - "$or": [ - { - "name": { - "$match": "*" - } - } - ] - } - }, - "pathMapping": { "input": "${DIST_REPO1}/data/(.*)", "output": "${DIST_REPO2}/target/$1" } + "pattern": "${DIST_REPO1}/data/(*)", + "target": "${DIST_REPO2}/target/{1}" } ] -} \ No newline at end of file +} diff --git a/testdata/filespecs/dist_create_with_pattern_and_target.json b/testdata/filespecs/dist_create_with_pattern_and_target.json deleted file mode 100644 index 98502d1d9..000000000 --- a/testdata/filespecs/dist_create_with_pattern_and_target.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "files": [ - { - "pattern": "${DIST_REPO1}/data/(*)", - "target": "${DIST_REPO2}/target/{1}" - } - ] -} diff --git a/testdata/go/projectmissingdependency/projectmissingdependecy.go b/testdata/go/projectmissingdependency/projectmissingdependecy.go index b59c02118..30c5ed4ce 100644 --- a/testdata/go/projectmissingdependency/projectmissingdependecy.go +++ b/testdata/go/projectmissingdependency/projectmissingdependecy.go @@ -12,4 +12,4 @@ func execDependency() { func Exec() { fmt.Println("Executing ") execDependency() -} +} \ No newline at end of file diff --git a/testdata/poetry/poetry.yaml b/testdata/poetry/poetry.yaml new file mode 100644 index 000000000..b590b9e4f --- /dev/null +++ b/testdata/poetry/poetry.yaml @@ -0,0 +1,5 @@ +version: 1 +type: poetry +resolver: + repo: ${POETRY_VIRTUAL_REPO} + serverId: default \ No newline at end of file diff --git a/testdata/poetry/poetryproject/poetry.lock b/testdata/poetry/poetryproject/poetry.lock new file mode 100644 index 000000000..dad791dc6 --- /dev/null +++ b/testdata/poetry/poetryproject/poetry.lock @@ -0,0 +1,45 @@ +[[package]] +name = "pexpect" +version = "4.8.0" +description = "Pexpect allows easy control of interactive console applications." +category = "main" +optional = false +python-versions = "*" + +[package.dependencies] +ptyprocess = ">=0.5" + +[[package]] +name = "ptyprocess" +version = "0.7.0" +description = "Run a subprocess in a pseudo terminal" +category = "main" +optional = false +python-versions = "*" + +[[package]] +name = "toml" +version = "0.10.2" +description = "Python Library for Tom's Obvious, Minimal Language" +category = "main" +optional = false +python-versions = ">=2.6, !=3.0.*, !=3.1.*, !=3.2.*" + +[metadata] +lock-version = "1.1" +python-versions = "*" +content-hash = "c22eacac00585ca6c65bbb1e992145332c3a3c9da9714ea29d9d90e6dfe9924b" + +[metadata.files] +pexpect = [ + {file = "pexpect-4.8.0-py2.py3-none-any.whl", hash = "sha256:0b48a55dcb3c05f3329815901ea4fc1537514d6ba867a152b581d69ae3710937"}, + {file = "pexpect-4.8.0.tar.gz", hash = "sha256:fc65a43959d153d0114afe13997d439c22823a27cefceb5ff35c2178c6784c0c"}, +] +ptyprocess = [ + {file = "ptyprocess-0.7.0-py2.py3-none-any.whl", hash = "sha256:4b41f3967fce3af57cc7e94b888626c18bf37a083e3651ca8feeb66d492fef35"}, + {file = "ptyprocess-0.7.0.tar.gz", hash = "sha256:5c5d0a3b48ceee0b48485e0c26037c0acd7d29765ca3fbb5cb3831d347423220"}, +] +toml = [ + {file = "toml-0.10.2-py2.py3-none-any.whl", hash = "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b"}, + {file = "toml-0.10.2.tar.gz", hash = "sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"}, +] diff --git a/testdata/poetry/poetryproject/pyproject.toml b/testdata/poetry/poetryproject/pyproject.toml new file mode 100644 index 000000000..d056175a5 --- /dev/null +++ b/testdata/poetry/poetryproject/pyproject.toml @@ -0,0 +1,16 @@ +[tool.poetry] +name = "cli-poetry-build" +version = "0.1.0" +description = "" +authors = ["Tal Arian "] + +[tool.poetry.dependencies] +python = "*" +toml = "0.10.2" +pexpect = "4.8.0" + +[tool.poetry.dev-dependencies] + +[build-system] +requires = ["poetry-core>=1.0.0"] +build-backend = "poetry.core.masonry.api" diff --git a/utils/cliutils/cli_consts.go b/utils/cliutils/cli_consts.go index 12f01e2a9..5ed8962ce 100644 --- a/utils/cliutils/cli_consts.go +++ b/utils/cliutils/cli_consts.go @@ -4,7 +4,7 @@ import "time" const ( // General CLI constants - CliVersion = "2.52.0" + CliVersion = "2.51.1" ClientAgent = "jfrog-cli-go" // CLI base commands constants: diff --git a/utils/cliutils/utils.go b/utils/cliutils/utils.go index 94d888400..e101b863c 100644 --- a/utils/cliutils/utils.go +++ b/utils/cliutils/utils.go @@ -5,7 +5,6 @@ import ( "errors" "fmt" "github.com/jfrog/gofrog/version" - "github.com/jfrog/jfrog-client-go/utils/log" "io" "net/http" "os" @@ -27,6 +26,7 @@ import ( clientutils "github.com/jfrog/jfrog-client-go/utils" "github.com/jfrog/jfrog-client-go/utils/errorutils" "github.com/jfrog/jfrog-client-go/utils/io/content" + "github.com/jfrog/jfrog-client-go/utils/log" "github.com/urfave/cli" ) diff --git a/utils/tests/consts.go b/utils/tests/consts.go index 8b3b93a6b..b6e99dc77 100644 --- a/utils/tests/consts.go +++ b/utils/tests/consts.go @@ -42,7 +42,6 @@ const ( DelSpecExclusions = "delete_spec_exclusions.json" DistributionCreateByAql = "dist_create_by_aql.json" DistributionCreateWithMapping = "dist_create_with_mapping.json" - DistributionCreateWithPatternAndTarget = "dist_create_with_pattern_and_target.json" DistributionMappingDownload = "dist_mapping_download_spec.json" DistributionRepoConfig1 = "dist_repository_config1.json" DistributionRepoConfig2 = "dist_repository_config2.json" @@ -83,6 +82,8 @@ const ( PypiVirtualRepositoryConfig = "pypi_virtual_repository_config.json" PipenvRemoteRepositoryConfig = "pipenv_remote_repository_config.json" PipenvVirtualRepositoryConfig = "pipenv_virtual_repository_config.json" + PoetryRemoteRepositoryConfig = "poetry_remote_repository_config.json" + PoetryVirtualRepositoryConfig = "poetry_virtual_repository_config.json" RepoDetailsUrl = "api/repositories/" ServerId = "testServerId" SearchPromotedDocker = "search_promoted_docker.json" @@ -175,6 +176,8 @@ var ( PypiVirtualRepo = "cli-pypi-virtual" PipenvRemoteRepo = "cli-pipenv-pypi-remote" PipenvVirtualRepo = "cli-pipenv-pypi-virtual" + PoetryRemoteRepo = "cli-poetry-pypi-remote" + PoetryVirtualRepo = "cli-poetry-pypi-virtual" DockerLocalRepo = "cli-docker-local" DockerLocalPromoteRepo = "cli-docker-local-promote" DockerRemoteRepo = "cli-docker-remote" @@ -203,6 +206,7 @@ var ( NuGetBuildName = "cli-nuget-build" PipBuildName = "cli-pip-build" PipenvBuildName = "cli-pipenv-build" + PoetryBuildName = "cli-poetry-build" RtBuildName1 = "cli-rt-build1" RtBuildName2 = "cli-rt-build2" RtBuildNameWithSpecialChars = "cli-rt-a$+~&^a#-build3" diff --git a/utils/tests/utils.go b/utils/tests/utils.go index b3eeb3950..19540b144 100644 --- a/utils/tests/utils.go +++ b/utils/tests/utils.go @@ -65,6 +65,7 @@ var ( TestNuget *bool TestPip *bool TestPipenv *bool + TestPoetry *bool TestPlugins *bool TestXray *bool TestAccess *bool @@ -100,6 +101,7 @@ func init() { TestNuget = flag.Bool("test.nuget", false, "Test Nuget") TestPip = flag.Bool("test.pip", false, "Test Pip") TestPipenv = flag.Bool("test.pipenv", false, "Test Pipenv") + TestPoetry = flag.Bool("test.poetry", false, "Test Poetry") TestPlugins = flag.Bool("test.plugins", false, "Test Plugins") TestXray = flag.Bool("test.xray", false, "Test Xray") TestAccess = flag.Bool("test.access", false, "Test Access") @@ -339,6 +341,8 @@ var reposConfigMap = map[*string]string{ &PypiVirtualRepo: PypiVirtualRepositoryConfig, &PipenvRemoteRepo: PipenvRemoteRepositoryConfig, &PipenvVirtualRepo: PipenvVirtualRepositoryConfig, + &PoetryRemoteRepo: PoetryRemoteRepositoryConfig, + &PoetryVirtualRepo: PoetryVirtualRepositoryConfig, &RtDebianRepo: DebianTestRepositoryConfig, &RtLfsRepo: GitLfsTestRepositoryConfig, &RtRepo1: Repo1RepositoryConfig, @@ -396,6 +400,7 @@ func GetNonVirtualRepositories() map[*string]string { TestNuget: {&NugetRemoteRepo}, TestPip: {&PypiRemoteRepo}, TestPipenv: {&PipenvRemoteRepo}, + TestPoetry: {&PoetryRemoteRepo}, TestPlugins: {&RtRepo1}, TestXray: {}, TestAccess: {&RtRepo1}, @@ -420,6 +425,7 @@ func GetVirtualRepositories() map[*string]string { TestNuget: {}, TestPip: {&PypiVirtualRepo}, TestPipenv: {&PipenvVirtualRepo}, + TestPoetry: {&PoetryVirtualRepo}, TestPlugins: {}, TestXray: {}, TestAccess: {}, @@ -455,6 +461,7 @@ func GetBuildNames() []string { TestNuget: {&NuGetBuildName}, TestPip: {&PipBuildName}, TestPipenv: {&PipenvBuildName}, + TestPoetry: {&PoetryBuildName}, TestPlugins: {}, TestXray: {}, TestAccess: {}, @@ -502,6 +509,8 @@ func getSubstitutionMap() map[string]string { "${PYPI_VIRTUAL_REPO}": PypiVirtualRepo, "${PIPENV_REMOTE_REPO}": PipenvRemoteRepo, "${PIPENV_VIRTUAL_REPO}": PipenvVirtualRepo, + "${POETRY_REMOTE_REPO}": PoetryRemoteRepo, + "${POETRY_VIRTUAL_REPO}": PoetryVirtualRepo, "${BUILD_NAME1}": RtBuildName1, "${BUILD_NAME2}": RtBuildName2, "${BUNDLE_NAME}": BundleName, @@ -558,6 +567,8 @@ func AddTimestampToGlobalVars() { PypiVirtualRepo += uniqueSuffix PipenvRemoteRepo += uniqueSuffix PipenvVirtualRepo += uniqueSuffix + PoetryRemoteRepo += uniqueSuffix + PoetryVirtualRepo += uniqueSuffix RtDebianRepo += uniqueSuffix RtLfsRepo += uniqueSuffix RtRepo1 += uniqueSuffix @@ -581,6 +592,7 @@ func AddTimestampToGlobalVars() { NuGetBuildName += uniqueSuffix PipBuildName += uniqueSuffix PipenvBuildName += uniqueSuffix + PoetryBuildName += uniqueSuffix RtBuildName1 += uniqueSuffix RtBuildName2 += uniqueSuffix RtBuildNameWithSpecialChars += uniqueSuffix