Try JFrog
Guides
Contact SupportTry JFrog
  1. Integrations
  2. JFrog CLI
  3. General Commands

Store Symbolic Links in JFrog Artifactory

Store and retrieve symbolic links in JFrog Artifactory without JFrog CLI resolving them to files.

JFrog CLI can upload and download symbolic links (soft links) between your machine and JFrog Artifactory on Linux and macOS, storing them as metadata-backed zero-byte artifacts instead of resolving to the target file by default.

📘

Note

A JFrog server must be configured with jf config add, and the target repository must exist before you run these commands. For more information, see Configuring the CLI.

📘

Note

The --symlinks and --validate-symlinks options are supported only on Linux and macOS. These flags have no effect on Windows.

Symlinks are stored in Artifactory as zero-byte files with the following properties:

  • symlink.dest: The path on the original file system to which the symlink points.
  • symlink.destsha1: The SHA1 checksum of the contents of the file that symlink.dest points to. Used by --validate-symlinks during download to detect if the target file has been modified or replaced. This property is only populated when the symlink target is a regular file. If the target is a directory or does not exist at upload time, symlink.destsha1 will not be set.

Upload Symbolic Links

Upload a local symlink to Artifactory so JFrog CLI stores it as a symlink instead of resolving it to the target file's contents.

To upload a symlink as a symlink (not as the resolved file):

  1. Use jf rt upload with --symlinks=true.
📘

Note

By default, --symlinks is false. When you omit this flag, the CLI uploads the file the symlink points to, not the symlink itself.

📘

Note

When you upload with an absolute source path, the CLI preserves the full directory structure inside the target repository path. Use --flat=true to upload only the file without the intermediate directories.

  1. Run:
jf rt upload <LOCAL_SYMLINK_PATH> <REPOSITORY_KEY>/<PATH>/ --symlinks=true --flat=true

Where:

  • <LOCAL_SYMLINK_PATH>: Path to the symlink on your machine.
  • <REPOSITORY_KEY>: Target JFrog Artifactory repository key.
  • <PATH>: Path inside the repository.

Example:

jf rt upload "/home/build/app/link.so" my-generic-repo/releases/ --symlinks=true --flat=true

Expected output:

{
  "status": "success",
  "totals": {
    "success": 1,
    "failure": 0
  }
}

Download Symbolic Links with Validation

Download a symlink from Artifactory and confirm its target file still matches the checksum recorded at upload time.

To download symlinks and validate that targets match recorded checksums:

  1. Use jf rt download with --validate-symlinks=true so the CLI checks that each symlink target still exists and matches symlink.destsha1.
📘

Note

Symlink validation applies to files only, not directories.

📘

Note

The --validate-symlinks option is supported only on Linux and macOS. This flag has no effect on Windows.

📘

Note

By default, the CLI reproduces the repository sub-path structure inside the local destination directory. When you download my-repository/path/symlink into /local/path/, the file is placed at /local/path/path/symlink. Use --flat=true to place the file directly in the destination folder without intermediate directories.

  1. Run:
jf rt download <REPOSITORY_KEY>/<ARTIFACT_PATH> <LOCAL_DESTINATION>/ --validate-symlinks=true --flat=true

Where:

  • <REPOSITORY_KEY>/<ARTIFACT_PATH>: Repository key and path to the symlink artifact in JFrog Artifactory.
  • <LOCAL_DESTINATION>: Directory on your machine to receive the download.

Example:

jf rt download my-generic-repo/releases/link.so /tmp/restore/ --validate-symlinks=true --flat=true

Expected output:

{
  "status": "success",
  "totals": {
    "success": 1,
    "failure": 0
  }
}

If validation fails (for example, the target file no longer exists or has been modified), the symlink is excluded from the download. The CLI logs an [Error] message for each skipped symlink and exits with a non-zero exit code. No JSON summary is produced when validation fails. Use the exit code to detect failure in scripts and continuous integration (CI) pipelines.

Example failure output:

[Error] symlink validation failed for target: /path/to/target-file
[Error] download finished with errors, please review the logs
📘

Note

On failure, the CLI also outputs a Trace ID, such as [Info] Trace ID for JFrog Platform logs: <id>. You can share this value with JFrog Support to correlate server-side logs.

Frequently Asked Questions

This section provides answers to frequently asked questions.

plusFAQs
Q: How do I upload a symlink to Artifactory without JFrog CLI resolving it to the target file?

A: Run jf rt upload with --symlinks=true. See Upload Symbolic Links for the full command.

Q: What is the difference between symlink.dest and symlink.destsha1?

A: symlink.dest stores the path the symlink points to. symlink.destsha1 stores the SHA1 checksum of the target file's contents, which --validate-symlinks uses to confirm the target hasn't changed.

Q: What do I need before uploading or downloading symlinks?

A: A JFrog server configured with jf config add, and a target repository that already exists. See Configuring the CLI.

Q: What happens if a downloaded symlink fails validation?

A: JFrog CLI excludes that symlink from the download, logs an [Error] message, and exits with a non-zero exit code. See Download Symbolic Links with Validation.

Q: Does symlink support work on Windows?

A: No. The --symlinks and --validate-symlinks options only take effect on Linux and macOS. These flags have no effect on Windows.

Related Topics

Updated 2 days ago

Did this page help you?