From dafe5890ef7c11b3d3efc0f4c0940373416a65c6 Mon Sep 17 00:00:00 2001 From: Michael Sverdlov Date: Wed, 16 Aug 2023 16:41:59 +0300 Subject: [PATCH 1/2] Fix docs Signed-off-by: Michael Sverdlov --- README.md | 4 +- documentation/CLI-for-JFrog-Artifactory.md | 14 ++- documentation/CLI-for-JFrog-Distribution.md | 18 ++- .../CLI-for-JFrog-Mission-Control.md | 6 +- documentation/CLI-for-JFrog-Xray.md | 63 +++++++---- documentation/JFrog-CLI.md | 106 ++++++++++++------ guides/jfrog-cli-plugins-developer-guide.md | 14 ++- 7 files changed, 147 insertions(+), 78 deletions(-) diff --git a/README.md b/README.md index b16f33d2a..118ce210c 100644 --- a/README.md +++ b/README.md @@ -243,8 +243,8 @@ # Overview -JFrog CLI is a compact and smart client that provides a simple interface that automates access to _Artifactory_ and -_Mission Control_ through their respective REST APIs. +JFrog CLI is a compact and smart client that provides a simple interface that automates access to **Artifactory** and +**Mission Control** through their respective REST APIs. By using the JFrog CLI, you can greatly simplify your automation scripts making them more readable and easier to maintain. Several features of the JFrog CLI makes your scripts more efficient and reliable: diff --git a/documentation/CLI-for-JFrog-Artifactory.md b/documentation/CLI-for-JFrog-Artifactory.md index 1eb4376ff..cebb20cd5 100644 --- a/documentation/CLI-for-JFrog-Artifactory.md +++ b/documentation/CLI-for-JFrog-Artifactory.md @@ -131,7 +131,9 @@ Any wildcard enclosed in parentheses in the source path can be matched with a co ##### **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). +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 ``` @@ -235,8 +237,8 @@ This command is used to upload files to Artifactory. | --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. | +| 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 @@ -2869,7 +2871,9 @@ If you're using JFrog CLI on a machine which has no access to the internet, you 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_** +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 @@ -2992,7 +2996,7 @@ The `jf rt transfer-files` command pushes the files from the source instance to **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. +> The replication can be configured at any time. Before, during or after the files transfer process. --- ### Files Transfer State diff --git a/documentation/CLI-for-JFrog-Distribution.md b/documentation/CLI-for-JFrog-Distribution.md index 0aa69a781..f78d3e239 100644 --- a/documentation/CLI-for-JFrog-Distribution.md +++ b/documentation/CLI-for-JFrog-Distribution.md @@ -47,7 +47,7 @@ This commands creates and updates an unsigned Release Bundle on JFrog Distributi | --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_. | +| --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 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. | @@ -55,7 +55,7 @@ This commands creates and updates an unsigned Release Bundle on JFrog Distributi | 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. | +| 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 @@ -79,19 +79,27 @@ Update the release bundle with name myApp and version 1.0.0. The release bundle ##### Example 4 -Update the release bundle with 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. +Update the release bundle with 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 with 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 on the Edge Node to the _target-zips_ folder, under the root of the _my-target-repo_ repository. +Update the release bundle with 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 on 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 the release bundle with 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 on 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. +This example +uses [placeholders](https://www.jfrog.com/confluence/display/CLI/CLI+for+JFrog+Artifactory#CLIforJFrogArtifactory-UsingPlaceholders). +It creates the release bundle with 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 on 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" diff --git a/documentation/CLI-for-JFrog-Mission-Control.md b/documentation/CLI-for-JFrog-Mission-Control.md index 812bb140c..3198d1e73 100644 --- a/documentation/CLI-for-JFrog-Mission-Control.md +++ b/documentation/CLI-for-JFrog-Mission-Control.md @@ -96,7 +96,7 @@ The following sections describe the commands available in the JFrog CLI for use ##### Example 1 -Assign a license from the _my-bucket-id_ and mark it as taken by _my-unique-name_. +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 @@ -116,7 +116,7 @@ Assign a license from the _my-bucket-id_ and mark it as taken by _my-unique-name **Example** -Deploy a single license from _my-bucket-id_ on _my-jpd-id_. +Deploy a single license from **my-bucket-id** on **my-jpd-id**. jf mc ld my-bucket-id my-jpd-id @@ -135,6 +135,6 @@ Deploy a single license from _my-bucket-id_ on _my-jpd-id_. **Example** -Releases all licenses of _my-jpd-id_ to _my-bucket-id_. +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-Xray.md b/documentation/CLI-for-JFrog-Xray.md index 4bd355393..82157c09a 100644 --- a/documentation/CLI-for-JFrog-Xray.md +++ b/documentation/CLI-for-JFrog-Xray.md @@ -8,7 +8,9 @@ Read more about JFrog CLI[here](https://jfrog.com/help/r/jfrog-cli). 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. + +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. | | | |----------------|---------------------------------------------------------| @@ -18,7 +20,9 @@ To authenticate yourself using your Xray login credentials, either configure you | --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. + +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. | | | |----------------|---------------------------------------------------------| @@ -31,7 +35,11 @@ To authenticate yourself using an Xray Access Token, either configure your Acces ## Scanning Project Dependencies ### General -The _**jf audit**_ command allows scanning your source code dependencies to find security vulnerabilities and licenses 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. + +The **jf audit** command allows scanning your source code dependencies to find security vulnerabilities and licenses +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. * Maven (mvn) - Version 3.1.0 or above of Maven is supported. * Gradle (gradle) @@ -65,7 +73,7 @@ This command also supports the following Advanced Scans with the **Advanced Secu | **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. | +| --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 | @@ -77,7 +85,7 @@ This command also supports the following Advanced Scans with the **Advanced Secu | --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. | +| --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. | @@ -86,7 +94,7 @@ This command also supports the following Advanced Scans with the **Advanced Secu | --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. | +| --yarn | \[Default: false\]

Set to true to request audit for a Yarn project. | | **Command arguments** | The command accepts no arguments | #### **Output Example** @@ -115,14 +123,14 @@ jf audit --mvn --npm **Example 3** -Audit the project at the current directory using a watch named _watch1_ watch defined in Xray. +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. +Audit the project at the current directory using **watch1** and **watch2**defined in Xray. ``` jf audit --watches "watch1,watch2" ``` @@ -136,7 +144,9 @@ 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. +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/" ``` @@ -150,7 +160,7 @@ Execute a cUrl command, using the configured Xray details. The command expects t | 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. | +| --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. | @@ -176,7 +186,7 @@ The [on-demand binary scanning](https://jfrog-staging-external.fluidtopics.net/r ### Scanning Files on the Local File System -This **jf scan**_ command scans files on the local file system with Xray. +This **jf scan** command scans files on the local file system with Xray. --- **Note** @@ -191,7 +201,7 @@ This **jf scan**_ command scans files on the local file system with Xray. | **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. | +| --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. | @@ -215,14 +225,17 @@ 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. +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. +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" ``` @@ -248,7 +261,9 @@ 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. +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** @@ -263,7 +278,7 @@ This j_**f docker scan**_ command scans docker containers located on the local f | **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. | +| --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. | @@ -282,7 +297,8 @@ This j_**f docker scan**_ command scans docker containers located on the local f **Example 1** -Scan the local _reg1/repo1/img1:1.0.0_ container and show all known vulnerabilities, regardless of the policies defined in Xray. +Scan the local **reg1/repo1/img1:1.0.0** container and show all known vulnerabilities, regardless of the policies +defined in Xray. ``` $ docker images @@ -295,7 +311,8 @@ $ 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. +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 @@ -308,7 +325,8 @@ $ 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. +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 @@ -321,7 +339,8 @@ $ 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. +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 @@ -433,10 +452,10 @@ JFrog CLI is integrated with JFrog Xray and JFrog Artifactory, allowing you to h | 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. | +| --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**_. | +| --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. | diff --git a/documentation/JFrog-CLI.md b/documentation/JFrog-CLI.md index 33d8b8abe..bca5ab72e 100644 --- a/documentation/JFrog-CLI.md +++ b/documentation/JFrog-CLI.md @@ -57,16 +57,22 @@ New enhancements to JFrog CLI are planned to be introduced as part of V2 only. V ### 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. +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. +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 @@ -83,15 +89,24 @@ New enhancements to JFrog CLI are planned to be introduced as part of V2 only. V 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. +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. @@ -103,11 +118,15 @@ To download the executable, please visit the [JFrog CLI Download Site](https:// 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. +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. +The following installers are available for JFrog CLI v2. These installers make JFrog CLI available through the **jf** +executable. **Debian** ``` @@ -170,7 +189,8 @@ 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. +The following installers are available for JFrog CLI v2. These installers make JFrog CLI available through the **jfrog** +executable. **Debian** ``` @@ -222,7 +242,8 @@ 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. +The following installations are available for JFrog CLI v1. These installers make JFrog CLI available through the * +*jfrog** executable. **Debian** ``` @@ -335,7 +356,8 @@ The **config add** and **config edit** commands are used to add and edit JFrog P ### Removing Configured Servers -The _config remove_ command is used to remove JFrog Platform server configuration, stored in JFrog CLI's configuration storage. +The **config remove** command is used to remove JFrog Platform server configuration, stored in JFrog CLI's configuration +storage. | | | |-------------------|--------------------------------------------------------------------------------------| @@ -348,7 +370,8 @@ The _config remove_ command is used to remove JFrog Platform server configuratio ### Showing the Configured Servers -The _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. +The **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. | | | |-------------------|-----------------------------------------------------------------------------------------| @@ -359,7 +382,7 @@ The _config show_ command shows the stored configuration. You may show a specifi ### Setting a Server as Default -The _config use_ command sets a configured server as default. The following commands will use this server. +The **config use** command sets a configured server as default. The following commands will use this server. | | | |-------------------|-----------------------------------------| @@ -369,7 +392,9 @@ The _config use_ command sets a configured server as default. The following comm ### Exporting and Importing Configuration -The _config export_ command generates a token, which stores the server configuration. This token can be used by the _config import_ command, to import the configuration stored in the token, and save it in JFrog CLI's configuration storage. +The **config export** command generates a token, which stores the server configuration. This token can be used by the +_config import_ command, to import the configuration stored in the token, and save it in JFrog CLI's configuration +storage. #### Export @@ -435,7 +460,10 @@ HTTP_PROXY, HTTPS_PROXY and NO_PROXY are the industry standards for proxy usages 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). + +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. @@ -464,10 +492,12 @@ jf completion fish --install 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 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. +> 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: @@ -479,7 +509,11 @@ masterKey: "your master key" 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. +> 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 @@ -493,7 +527,9 @@ A plugin which is included [JFrog CLI's Plugins Registry](https://github.com/jfr ``` $ 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. + +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 @@ -501,10 +537,10 @@ In addition to the public official JFrog CLI Plugins Registry, JFrog CLI support 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. +* 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. diff --git a/guides/jfrog-cli-plugins-developer-guide.md b/guides/jfrog-cli-plugins-developer-guide.md index e985ad44b..876ea81f7 100644 --- a/guides/jfrog-cli-plugins-developer-guide.md +++ b/guides/jfrog-cli-plugins-developer-guide.md @@ -55,9 +55,10 @@ Well, plugins can do almost anything. The sky is the limit. 1. You have access to most of the JFrog CLI code base. This is because your plugin code depends on the [https://github.com/jfrog/jfrog-cli-core](https://github.com/jfrog/jfrog-cli-core) module. It is a dependency - declared in your project's *go.mod* file. Feel free to explore the *jfrog-cli-core* code base, and use it as part of + declared in your project's **go.mod** file. Feel free to explore the **jfrog-cli-core** code base, and use it as part + of your plugin. -2. You can also add other Go packages to your *go.mod* and use them in your code. +2. You can also add other Go packages to your **go.mod** and use them in your code. 3. You can package any external resources, such as executables or configuration files, and have them published alongside your plugin. Read more about this [here](jfrog-cli-plugins-developer-guide.md#having-your-plugin-use-external-resources) @@ -70,7 +71,7 @@ To make a new plugin available for anyone to use, you need to register the plugi registry is hosted in [https://github.com/jfrog/jfrog-cli-plugins-reg](https://github.com/jfrog/jfrog-cli-plugins-reg). The registry includes a descriptor file in YAML format for each registered plugin, inside the *plugins* directory. To include your plugin in the registry, create a pull request to add the plugin descriptor file for your plugin according -to this file name format: *your-plugin-name.yml*. +to this file name format: **your-plugin-name.yml**. ### Guidelines for developing and publishing plugins @@ -154,9 +155,10 @@ 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 ```jf 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. +* 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 From f8d57c9bf396e080bb167676cc0a087ea8e023b1 Mon Sep 17 00:00:00 2001 From: Michael Sverdlov Date: Wed, 16 Aug 2023 16:44:18 +0300 Subject: [PATCH 2/2] Fix docs Signed-off-by: Michael Sverdlov --- artifactory/cli.go | 2 +- buildtools/cli.go | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/artifactory/cli.go b/artifactory/cli.go index 065205971..1e02ab521 100644 --- a/artifactory/cli.go +++ b/artifactory/cli.go @@ -995,7 +995,7 @@ func getRetryWaitTime(c *cli.Context) (waitMilliSecs int, err error) { } func getRetryWaitTimeVerificationError() error { - return errorutils.CheckError(errors.New("The '--retry-wait-time' option should have a numeric value with 's'/'ms' suffix. " + cliutils.GetDocumentationMessage())) + return errorutils.CheckErrorf("The '--retry-wait-time' option should have a numeric value with 's'/'ms' suffix. " + cliutils.GetDocumentationMessage()) } func dockerPromoteCmd(c *cli.Context) error { diff --git a/buildtools/cli.go b/buildtools/cli.go index 508edb996..3cea56118 100644 --- a/buildtools/cli.go +++ b/buildtools/cli.go @@ -842,7 +842,7 @@ func GetNpmConfigAndArgs(c *cli.Context) (configFilePath string, args []string, } if !exists { - return "", nil, errorutils.CheckError(errors.New("no config file was found! Before running the npm command on a project for the first time, the project should be configured using the npm-config command")) + return "", nil, errorutils.CheckErrorf("no config file was found! Before running the npm command on a project for the first time, the project should be configured using the npm-config command") } _, args = getCommandName(c.Args()) return @@ -914,7 +914,7 @@ func terraformCmd(c *cli.Context) error { case "publish", "p": return terraformPublishCmd(configFilePath, filteredArgs, c) default: - return errorutils.CheckError(errors.New("Terraform command:\"" + cmdName + "\" is not supported. " + cliutils.GetDocumentationMessage())) + return errorutils.CheckErrorf("Terraform command:\"" + cmdName + "\" is not supported. " + cliutils.GetDocumentationMessage()) } }