Release Lifecycle Management CLI

This page describes how to use the JFrog CLI with Release Lifecycle Management.

Syntax

When used with JFrog Release Lifecycle Management, JFrog CLI uses the following syntax:

$ jf command-name global-options command-options arguments

Create a Release Bundle v2

Use the create command to create a Release Bundle v2 using File Specs. The File Spec can be based on one or more of the following sources:

• Published build info:

  JSON

  {
    "files": [
      {
        "build": "<build-name>/<build-number>",
        "includeDeps": "[true/false]",
        "project": "<project-key>"
      },
      ...
    ]
  }

  <build-number>is optional; the latest build will be used if empty .includeDeps is optional, false by default .project is optional; the default project will be used if empty.

• Existing Release Bundles:

  JSON

  {
    "files": [
      {
        "bundle": "<bundle-name>/<bundle-version>",
        "project": "<project-key>"
      },
      ...
    ]
  }

  project is optional; the default project will be used if empty.

• A pattern of artifacts in Artifactory:

  JSON

  {
    "files": [
      {
        "pattern": "repo/path/*",
        "exclusions": ["excluded",...],
        "props": "key1=value1;key2=value2;key3=value3",
        "excludeArtifacts": "key1=value1;key2=value2;key3=value3",
        "recursive": "[true/false]"
      },
      ...
    ]
  }

  Only pattern is mandatory .recursive is true by default. The path can include local, Federated, and remote repositories.

• AQL query:

  JSON

  {
    "files": [
      {
        "aql": {
          "items.find": {
            "repo": "<repo>",
            "path": "<path>",
            "name": "<file>"
          }
        }
      }
    ]
  }

  Only a single AQL query may be provided.

• Specified package:

  The Release Bundle can contain packages of multiple types (for example, Docker, Maven, PyPI, and so on).

{
    "files": [
            {
               "package": "catalina",
               "version":"1.0.0",
               "type": "maven",
               "repoKey": "catalina-dev-maven-local"
           },
   ]
}

• A Release Bundle created from multiple sources:

  The Release Bundle can include any number of builds, artifacts (using a pattern), packages, and Release Bundles. However, it can include only one AQL query.

{
    "files": [
          {
            "build": "Commons-Build/1.0.0",
            "includeDeps":"true",
            "project": "default"
          },
           {
            "bundle": "rb1/1.0.0",
            "project": "default"
          },
          {
            "bundle": "rb4/1.0.0",
            "project": "default"
          },
           {
            "pattern": "catalina-dev-maven-local/*.jar"
          },
           {
            "package": "commons",
            "version":"1.0.1",
            "type": "maven",
            "repoKey": "commons-dev-maven-local"
          },
          {
            "package": "catalina",
            "version":"1.0.0",
            "type": "maven",
            "repoKey": "catalina-dev-maven-local"
          },
          {
            "aql": {
             "items.find": {
              "repo":{"$eq":"catalina-dev-maven-local"},
              "$and":[
                {"name": {"$match":"*1.0.0.pom"}}
              ]
        }
      }
          }
    ]
}

Command Params

The following table describes the create command parameters.

Update a Release Bundle v2

Use the update command to add sources to an existing draft Release Bundle. The --add flag is mandatory to specify the type of operation.

Command Params

The following table describes the update command parameters.

Update a Release Bundle v2 Examples

Update a Release Bundle v2 Example 1

Add sources from a File Spec to a draft Release Bundle.

jf rbu --add --spec=/path/to/spec.json myApp 1.0.0

Update a Release Bundle v2 Example 2

Add builds to a draft Release Bundle.

jf rbu --add --source-type-builds "name=Commons-Build, id=1.0.0, include-deps=true" myApp 1.0.0

Update a Release Bundle v2 Example 3

Add existing Release Bundles to a draft Release Bundle.

jf rbu --add --source-type-release-bundles "name=rb1, version=1.0.0; name=rb2, version=1.0.0" myApp 1.0.0

Update a Release Bundle v2 Example 4

Add sources to a draft Release Bundle in a specific project.

jf rbu --add --project=myproject --spec=/path/to/spec.json myApp 1.0.0

Finalize a Release Bundle v2

Use the finalize command to lock a draft Release Bundle. Once finalized, the Release Bundle can no longer be updated and is ready for promotion or distribution.

Command Params

The following table describes the finalize command parameters.

Finalize a Release Bundle v2 Examples

Finalize a Release Bundle v2 Example 1

Finalize a draft Release Bundle.

jf rbf myApp 1.0.0

Finalize a Release Bundle v2 Example 2

Finalize a draft Release Bundle with a specific signing key.

jf rbf --signing-key=myKeyPair myApp 1.0.0

Finalize a Release Bundle v2 Example 3

Finalize a draft Release Bundle asynchronously.

jf rbf --sync=false myApp 1.0.0

Finalize a Release Bundle v2 Example 4

Finalize a draft Release Bundle in a specific project.

jf rbf --project=myproject myApp 1.0.0

Draft Release Bundle Workflow

The draft Release Bundle workflow allows you to create a Release Bundle incrementally before finalizing it:

1. Create a draft Release Bundle: Use jf rbc --draft to create a Release Bundle in draft state.
2. Update the draft (optional): Use jf rbu --add to add additional sources to the draft Release Bundle.
3. Finalize the Release Bundle: Use jf rbf to lock the draft and prepare it for promotion or distribution.

Draft Release Bundle Workflow Example

# Step 1: Create a draft Release Bundle
jf rbc --draft --spec=/path/to/initial-spec.json myApp 1.0.0

# Step 2: Add more sources to the draft
jf rbu --add --source-type-builds "name=Additional-Build, id=2.0.0" myApp 1.0.0

# Step 3: Finalize the Release Bundle
jf rbf --signing-key=myKeyPair myApp 1.0.0

# Step 4: Now the Release Bundle can be promoted
jf rbp --signing-key=myKeyPair myApp 1.0.0 PROD

Search Release Bundles v2

Use these commands to search Release Bundle names and versions. For more on viewing and managing versions in the JFrog Platform UI, see Manage Release Bundle v2 Versions.

Command group: release-bundle-search (rbs)

jf rbs names

Return Release Bundle names.

Syntax

jf rbs names [command-options]

Command Options

The following table describes the jf rbs names command options.

Examples

# List names that start with "myApp", newest first
jf rbs names --filter-by myApp --order-by created

# Paginate through results (second page of 50)
jf rbs names --limit 50 --offset 50

jf rbs versions

Return Release Bundle versions (per bundle), with optional additional details.

Syntax

jf rbs versions [command-options]

Command Options

The following table describes the jf rbs versions command options.

Examples

# List versions for bundles beginning with "myApp"
jf rbs versions --filter-by myApp

# Include creation messages and sort oldest first
jf rbs versions --includes messages --order-asc --order-by created

Create a Release Bundle v2 Examples

Create a Release Bundle v2 Example 1

Create a Release Bundle using file spec variables.

jf rbc --spec=/path/to/spec.json --spec-vars="key1=value1" --signing-key=myKeyPair myApp 1.0.0

Create a Release Bundle v2 Example 2

Create a Release Bundle synchronously, in project "project0".

jf rbc --spec=/path/to/spec.json --signing-key=myKeyPair --sync=true --project=project0 myApp 1.0.0

Create a Release Bundle v2 Example 3

Create a Release Bundle from a single build using the build name and build number variables.

jf rbc --build-name=Common-builds --build-number=1.0.0 myApp 1.0.0

Create a Release Bundle v2 Example 4

Create a Release Bundle from multiple builds.

jf rbc rb3 1.0.0 --source-type-builds "name=Commons-Build, id=1.0.0, include-deps=true; name=Commons-Build, id=1.0.1"

Create a Release Bundle v2 Example 5

Create a Release Bundle from multiple existing Release Bundles.

jf rbc rb3 1.0.0 --project catalina --source-type-release-bundles "name=rb1, version=1.0.0; name=rb2, version=1.0.0"

Create a Release Bundle v2 Example 6

Create a Release Bundle from existing Release Bundles and builds.

jf rbc rb3 1.0.0 --source-type-builds \
"name=Commons-Build, id=1.0.0, include-deps=true; name=Commons-Build, id=1.0.1" \
--source-type-release-bundles \
"name=rb1, version=1.0.0; name=rb2, version=1.0.0"

Create a Release Bundle v2 Example 7

Create a draft Release Bundle that can be updated before finalizing.

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

Create a Release Bundle v2 Example 8

Create a draft Release Bundle from builds.

jf rbc --draft --source-type-builds "name=Commons-Build, id=1.0.0" myApp 1.0.0

Promote a Release Bundle v2

This command allows promoting a Release Bundle to a target environment. For the UI-based approach, see Promote a Release Bundle v2 Version.

Command Params

The following table describes the promote command parameters.

Promote a Release Bundle v2 Examples

Promote a Release Bundle v2 Example 1

Promote a Release Bundle named "myApp" version "1.0.0" to environment "PROD". Use signing key pair "myKeyPair".

jf rbp --signing-key=myKeyPair myApp 1.0.0 PROD

Promote a Release Bundle v2 Example 2

Promote a Release Bundle synchronously to environment "PROD". The Release Bundle is named "myApp", version "1.0.0", of project "project0". Use signing key pair "myKeyPair".

jf rbp --signing-key=myKeyPair --project=project0 --sync=true myApp 1.0.0 PROD

Promote a Release Bundle v2 Example 3

Promote a Release Bundle while including certain repositories.

jf rbp --signing-key=myKeyPair --include-repos="generic-local;my-repo" myApp 1.0.0 PROD

Promote a Release Bundle v2 Example 4

Promote a Release Bundle while excluding certain repositories.

jf rbp --signing-key=myKeyPair --exclude-repos="generic-local;my-repo" myApp 1.0.0 PROD

Promote a Release Bundle v2 Example 5

Promote a Release Bundle, using the --promotion-type flag.

jf rbp --signing-key=myKeyPair --promotion-type="move" myApp 1.0.0 PROD

Annotate a Release Bundle v2

This command enables you to add a single tag to a Release Bundle v2 version and/or define one or more properties. The tag will appear in the Release Lifecycle kanban board. For example, if you tag all your release candidates as release-candidate, you can filter the kanban board to display only those Release Bundle versions. Properties are user-customizable fields that can contain any string and have any value. For the UI-based approach, see Tag a Release Bundle v2 Version.

Command Params

The following table describes the annotate command parameters.

Annotate a Release Bundle v2 Examples

Annotate a Release Bundle v2 Example 1

Add or modify a tag or property.

jf rba mybundle 1.0.0 --tag=release --properties "environment=production;buildNumber=1234"

Annotate a Release Bundle v2 Example 2

Whenever you use the --tag command option, the value you define replaces the current value.

jf rba mybundle 1.0.0 --tag=rejected

In the example above, the tag that was defined previously (release) is replaced with the new tag rejected.

Annotate a Release Bundle v2 Example 3

Whenever you use the --properties command option with an existing key, the values that you define replace the current values.

jf rba mybundle 1.0.0 --properties "environment=DEV,PROD,QA"

In the example above, the value for environment that was defined previously (production) is replaced by the values DEV , PROD , and QA.

Remove Tags and Properties Examples

Remove Tags and Properties Example 1

To remove the tag, set it to null or leave empty.

jf rba mybundle 1.0.0 --tag=""

Remove Tags and Properties Example 2

To remove the values from an existing key without removing the key, leave the value empty.

jf rba mybundle 1.0.0 --properties "build=''"

In the example above, all values defined for the build key are removed but the key is retained.

Remove Tags and Properties Example 3

To remove a key and its associated values, use the --del-prop command option.

jf rba mybundle 1.0.0 --del-prop "environment"

In the example above, the environment key and all its associated values are removed.

Distribute a Release Bundle v2

This command distributes a Release Bundle to an Edge node. For the UI-based approach, see Distributing Release Bundles v2.

Distribution Rules 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": ["*"]
    }
 ]
}

Distribute a Release Bundle v2 Examples

Distribute a Release Bundle v2 Example 1

Distribute the Release Bundle 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

Distribute a Release Bundle v2 Example 2

Distribute the Release Bundle 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

Distribute a Release Bundle v2 Example 3

Synchronously distribute a Release Bundle associated with project proj.

jf rbd --dist-rules=/path/to/dist-rules.json --sync --project="proj" myApp 1.0.0

Delete a Release Bundle v2 locally

This command allows deleting all Release Bundle promotions to a specified environment or deleting a Release Bundle locally altogether. Deleting locally means distributions of the Release Bundle will not be deleted.

Delete a Release Bundle v2 Locally Examples

Delete a Release Bundle v2 locally Example 1

Locally delete the Release Bundle named myApp with version 1.0.0.

jf rbdell myApp 1.0.0

Delete a Release Bundle v2 locally Example 2

Locally delete the Release Bundle named myApp with version 1.0.0. Run the command synchronously and skip the confirmation message.

jf rbdell --quiet --sync myApp 1.0.0

Delete a Release Bundle v2 locally Example 3

Delete all promotions of the specified Release Bundle version to environment PROD.

jf rbdell myApp 1.0.0 PROD

Delete a Release Bundle v2 remotely

This command will delete distributions of a Release Bundle from a distribution target, such as an Edge node.

Delete a Release Bundle v2 Remotely Examples

Delete a Release Bundle v2 remotely Example 1

Delete the distributions of version 1.0.0 of the Release Bundle named myApp from Edge nodes matching the provided distribution rules defined in the specified file.

jf rbdelr --dist-rules=/path/to/dist-rules.json myApp 1.0.0

Delete a Release Bundle v2 remotely Example 2

Delete the distributions of the Release Bundle associated with project proj from the provided Edge nodes. Run the command synchronously and skip the confirmation message.

jf rbdelr --dist-rules=/path/to/dist-rules.json --project="proj" --quiet --sync myApp 1.0.0

Export a Release Bundle v2 archive

Release Lifecycle Management supports distributing your Release Bundles to remote Edge nodes within an air-gapped environment. This use case is mainly intended for organizations that have two or more JFrog instances that have no network connection between them.

The following command allows exporting a Release Bundle as an archive to the filesystem that can be transferred to a different instance in an air-gapped environment.

Export a Release Bundle v2 archive Example

Export a Release Bundle v2 archive Example

Export version 1.0.0 of the Release Bundle named myApp:

jf rbe myApp 1.0.0

Export and Download a Release Bundle v2 archive Example

Download the file to a specific location:

jf rbe myApp 1.0.0 /user/mybundle/

Import a Release Bundle v2 archive

You can import a Release Bundle archive from the exported zip file.

This functionality only works on Edge nodes within an air-gapped environment.

Import a Release Bundle v2 archive Example

Import a Release Bundle v2 Archive Example

Import version 1.0.0 of a Release Bundle named myExportedApp:

jf rbi ./myExportedApp.zip

Download Release Bundle v2 Content

Use the following command to download the contents of a Release Bundle v2 version:

jf rt dl --bundle [release-bundle-name]/[release-bundle-version]

Frequently Asked Questions

Common questions about release lifecycle management.

Related Topics

• Creating Release Bundles (v2)
• Known Issues and Limitations