Distribution CLI

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

Read more about JFrog Distribution here.

Prerequisites

Before using JFrog Distribution commands, ensure:

1. JFrog CLI is installed: Run jf --version to verify installation
2. Server is configured: Run jf config add to configure your JFrog Platform, or pass --url and authentication flags with each command
3. Distribution is enabled: Your JFrog Platform must have Distribution enabled (version 2.0 or higher)
4. For signing: GPG key pair must be configured in JFrog Distribution
5. For distribution: At least one Edge Node must be configured and connected

Configuring Your Server

# Option 1: Configure server interactively (recommended)
jf config add

# Option 2: Configure with environment variables
export JFROG_URL="https://acme.jfrog.io"
export JFROG_ACCESS_TOKEN="your-access-token"

# Option 3: Pass credentials with each command
jf ds rbc --url="https://acme.jfrog.io/distribution" --access-token="token" ...

Overview

JFrog CLI provides a convenient interface for working with release bundles in JFrog Distribution. The Distribution commands are available under the jf ds namespace.

Syntax

jf ds command-name [global-options] [command-options] [arguments]

Commands Available

Common Options

The following options are available for all distribution commands:

Creating a Release Bundle

Create a new release bundle with artifacts from Artifactory.

Command

jf ds release-bundle-create <bundle-name> <bundle-version> [pattern]

Abbreviation: rbc

Arguments

Options

Examples

Example 1: Create a release bundle with a pattern

jf ds rbc myApp 1.0.0 "my-repo/builds/*.zip"

Example 2: Create a release bundle using a File Spec

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

Example 3: Create and automatically sign

jf ds rbc --sign --passphrase="my-gpg-passphrase" myApp 1.0.0 "my-repo/releases/*"

Example 4: Dry run to validate without executing

jf ds rbc --dry-run myApp 1.0.0 "my-repo/builds/*.zip"

Updating a Release Bundle

Update an existing unsigned release bundle version by adding or modifying artifacts.

Command

jf ds release-bundle-update <bundle-name> <bundle-version> [pattern]

Abbreviation: rbu

Arguments

Options

Same options as release-bundle-create (see above).

Note: You can only update release bundles that have not been signed. Once a release bundle is signed, it becomes immutable.

Examples

Example 1: Update with a pattern

jf ds rbu myApp 1.0.0 "my-repo/additional-files/*.jar"

Example 2: Update using a File Spec

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

Signing a Release Bundle

Sign a release bundle using the GPG key configured in JFrog Distribution. Signing makes the release bundle immutable and ready for distribution.

Command

jf ds release-bundle-sign <bundle-name> <bundle-version>

Abbreviation: rbs

Arguments

Options

Note: The --dry-run flag is not available for the sign command.

Examples

Example 1: Sign a release bundle

jf ds rbs myApp 1.0.0

Example 2: Sign with a passphrase

jf ds rbs --passphrase="<passphrase>" myApp 1.0.0

Distributing a Release Bundle

Distribute a signed release bundle to one or more Edge nodes.

Command

jf ds release-bundle-distribute <bundle-name> <bundle-version>

Abbreviation: rbd

Arguments

Options

Examples

Example 1: Distribute to all Edge nodes

jf ds rbd --site="*" myApp 1.0.0

Example 2: Distribute to specific sites

jf ds rbd --site="us-*" --city="New York" myApp 1.0.0

Example 3: Distribute using rules file

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

Example 4: Synchronous distribution with repository creation

jf ds rbd --sync --create-repo --site="*" myApp 1.0.0

Deleting a Release Bundle

Delete a release bundle from Edge nodes and optionally from JFrog Distribution itself.

Command

jf ds release-bundle-delete <bundle-name> <bundle-version>

Abbreviation: rbdel

Arguments

Options

Examples

Example 1: Delete from all Edge nodes

jf ds rbdel --site="*" myApp 1.0.0

Example 2: Delete from Edge nodes and Distribution

jf ds rbdel --site="*" --delete-from-dist myApp 1.0.0

Example 3: Delete silently (for CI/CD)

jf ds rbdel --quiet --sync --site="*" myApp 1.0.0

File Spec Schema

File Specs can be used with release-bundle-create and release-bundle-update commands to define which artifacts to include.

Using Patterns

{
  "files": [
    {
      "pattern": "my-local-repo/zips/*.zip"
    }
  ]
}

Using AQL Queries

{
  "files": [
    {
      "aql": {
        "items.find": {
          "repo": "my-local-repo",
          "$and": [
            {
              "name": { "$match": "*.jar" }
            },
            {
              "$or": [
                { "path": { "$match": "." } },
                { "path": { "$match": "*" } }
              ]
            }
          ]
        }
      }
    }
  ]
}

Using Path Mapping

Path mapping allows you to change the artifact path in the release bundle:

{
  "files": [
    {
      "pattern": "my-local-repo/(.*)",
      "pathMapping": {
        "input": "my-local-repo/(.*)",
        "output": "new-path/$1"
      }
    }
  ]
}

More about File Specs: See the File Spec documentation for complete syntax reference.

Distribution Rules Schema

Distribution rules define which Edge nodes receive the release bundle.

JSON Structure

{
  "distribution_rules": [
    {
      "site_name": "*",
      "city_name": "*",
      "country_codes": ["*"]
    }
  ]
}

Fields

Example: Multiple Rules

{
  "distribution_rules": [
    {
      "site_name": "us-*",
      "city_name": "*",
      "country_codes": ["US"]
    },
    {
      "site_name": "eu-*",
      "city_name": "*",
      "country_codes": ["DE", "FR", "GB"]
    }
  ]
}

Environment Variables

The following environment variables can be used with distribution commands:

Troubleshooting

Common Issues

Error: "no JFrog Distribution URL specified"

The CLI cannot find a configured server. Solutions:

1. Run jf config add to configure your server
2. Pass --url with the Distribution URL
3. Set the JFROG_URL environment variable

Error: "release bundle not found"

• Verify the bundle name and version are correct
• Check if the bundle was created on the expected server

Error: "signing failed"

• Verify GPG keys are configured in JFrog Distribution
• Check if the passphrase is correct
• Ensure you have permission to sign release bundles

Distribution stuck or slow

• Use --sync with --max-wait-minutes to control timeout
• Check Edge node connectivity in the JFrog Platform UI
• Verify network connectivity between Distribution and Edge nodes

Best Practices

1. Version your bundles semantically: Use semantic versioning (e.g., 1.0.0, 1.0.1) for release bundles
2. Always sign before distributing: Signed bundles are immutable and provide integrity verification
3. Use File Specs for complex selections: File Specs provide more flexibility than command-line patterns
4. Use --sync in CI/CD: Synchronous mode ensures the pipeline waits for distribution to complete
5. Set $CI in automated environments: This automatically enables --quiet mode