Store symlinks in Artifactory

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

📘

Prerequisite

A JFrog server must be configured with jf config add and the target repository must exist before running these commands. See Configuring the CLI.

📘

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

Uploading Symlinks

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. Omitting this flag uploads the file the symlink points to, not the symlink itself.

📘

Note

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

2. Run:

jf rt upload <local-symlink-path> <repo>/<path>/ --symlinks=true --flat=true

Where:

• <local-symlink-path> — Path to the symlink on your machine.
• <repo> — Target 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
  }
}

Downloading Symlinks with Validation

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.

📘

Platform 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. For example, downloading my-repo/path/symlink into /local/path/ places the file at /local/path/path/symlink. Use --flat=true to place the file directly in the destination folder without intermediate directories.

2. Run:

jf rt download <repo>/<artifact-path> <local-destination>/ --validate-symlinks=true --flat=true

Where:

• <repo>/<artifact-path> — Repository key and path to the symlink artifact in 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 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 (for example, [Info] Trace ID for JFrog Platform logs: <id>). This can be shared with JFrog Support to correlate server-side logs.