CLI for JFrog Distribution

Overview

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

Read more about JFrog CLI here.

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 commands creates and updates an unsigned Release Bundle on JFrog Distribution.


Note

This commands require version 2.0 or higher ofJFrog Distribution.


Commands Params

Command-name

release-bundle-create / release-bundle-update

Abbreviation

rbc / rbu

Command options:

--server-id

[Optional] Artifactory Server ID configured using the 'jf config' command.

--spec

[Optional] Path to a file spec. For more details, please refer to Using File Specs.

--spec-vars

[Optional] List of semicolon-separated(;) 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.

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

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.

Example 1

Create a release bundle with 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 with 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 sign 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 with 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 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.

jf ds rbu myApp 1.0.0 "my-local-repo/zips/*.zip" --target my-target-repo/target-zips/

Example 6

This example uses placeholders. 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"

Example 7

This example creates a release bundle and applies "pathMapping" to the artifact paths after distributing the release bundle.

All occurrences of the "a1.in" file are fetched and mapped to the "froggy" repository at the edges.

  1. Fetch all artifacts retrieved by the AQL query.

  2. Create the release bundle with the artifacts and apply the path mappings at the edges after distribution.

The "pathMapping" option is provided, allowing users to control the destination of the release bundle artifacts at the edges.

To learn more, visit the Create Release Bundle v1 Version documentation.

Note: The "target" option is designed to work for most use cases. The "pathMapping" option is intended for specific use cases, such as including a list.manifest.json file inside the release bundle.

In that scenario, the distribution server dynamically includes all the manifest.json and their layers and assigns the given path mapping, whereas "target" doesn't achieve this.

jf ds rbc --spec=/path/to/rb-spec.json myApp 1.0.0

Spec file content:

{
  "files": [
    {
      "aql": {
        "items.find": {
          "repo": "my-local-repo",
          "$and": [
            {
              "name": {
                "$match": "a1.in"
              }
            },
            {
              "$or": [
                {
                  "path": {
                    "$match": "."
                  }
                },
                {
                  "path": {
                    "$match": "*"
                  }
                }
              ]
            }
          ]
        }
      },
      "pathMapping": {
        "input": "my-local-repo/(.*)",
        "output": "froggy/$1"
      }
    }
  ]
}

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 ofJFrog Distribution.


Commands Params

Command-name

release-bundle-sign

Abbreviation

rbs

Command options:

--server-id

[Optional] Artifactory Server ID configured using the 'jf 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.

Example

GPG sign the release bundle with name myApp and version 1.0.0.

jf ds rbs --passphrase="&lt;passphrase&gt;" myApp 1.0.0 

Distributing a Release Bundle

This command distributes a release bundle to the Edge Nodes.


Note

These commands require version 2.0 or higher ofJFrog Distribution.


Commands Params

Command-name

release-bundle-distribute

Abbreviation

rbd

Command options:

--server-id

[Optional] Artifactory Server ID configured using the 'jf 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.

Example 1

Distribute the release bundle with 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 from the Edge Nodes and optionally from Distribution as well.


Note

These commands require version 2.0 or higher of JFrog Distribution.


Commands Params

Command-name

release-bundle-delete

Abbreviation

rbdel

Command options:

--server-id

[Optional] Artifactory Server ID configured using the 'jf 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 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.

Example 1

Delete the release bundle with 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 with 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

Last updated

© 2024 JFrog Ltd All Rights Reserved