--- updatedAt: 2026-08-20T11:58:34.000Z agentTools: siteIndex: https://docs.jfrog.com/llms.txt projectIndex: https://docs.jfrog.com/governance/llms.txt --- # Promote Application Version CLI Promote an application version to a target lifecycle stage using the JFrog CLI. **Description**: Promotes the [application version](/docs/application-version-management) to the desired stage, with options for including or excluding repositories, running conditions, and adding comments. There is also a path mapping option, so that you can change the directory structure or path names in the target environment. **Command**: ``` jf apptrust version-promote [command options] ``` **Alias command**: `jf at vp` ## Command Options
Option Required/Optional Type Description
`` required string The application key of the application for which the version is being promoted.
`` required string The version to promote.
`` required string The stage to which the application version should be promoted (for example, DEV, QA, STG).
`--sync ` optional boolean Determines whether to perform the promotion synchronously or asynchronously. Default is `true` (synchronous). Pass `--sync=false` to return as soon as the request is accepted, without waiting for the operation to complete.
`--promotion-type` optional string The type of promotion to perform: Specifies the promotion type: - `copy`: Copies the application version to the target stage, preserving the source artifacts. This is the default. **Note** No physical copy occurs if the source and target repositories are identical. - `move`: Moves the application version to the target stage, transferring the source. - `keep`: Promotes without copying or moving artifacts.
`--props "=[,,...]"` optional object Defines a semicolon-separated list of properties to be added to each artifact in the application version. The format is: `'key1=value1;key2=value2;...'`
`--dry-run` optional boolean When set to `true`, simulates the promotion without actually performing it. The default value is `false`.
`--exclude-repos` optional array:string A list of semicolon-separated (;) repositories to exclude from the promotion.
`--include-repos` optional array:string A list of semicolon-separated (;) repositories to include in the promotion. If this property is not defined, all repositories (except those explicitly excluded) are included in the promotion. If one or more repositories are specifically included, all other repositories are excluded.
`--overwrite-strategy` optional string Determines whether artifacts can be overwritten during promotion. This is a strategy for handling target artifacts with the same path but different checksums and is an exception to the general immutability of artifacts. If omitted, the platform determines the applicable strategy. Policy options: - `latest`: Overwrite is permitted only if the artifact tag is `latest`. This option is intended primarily for artifacts that make use of the latest tag. - `all`: Overwriting of artifacts of any path is permitted. - `disabled`: No overwriting is permitted. This is the strongest option for preserving immutability during promotion. If you chose `keep` as the `promotion-type`, the `overwrite-strategy` parameter will be ignored.
`--path-mapping` optional array:string Changes the relative path structure or path names of artifacts in the target environment. A list of semicolon-separated (;) mapping rules in the form `'input=, output=[, package-type=]'`. Fields are: - `input`: A standard regex pattern executed against the source relative paths to capture components via grouping.  - `output`: The target path string using placeholder variables, for example, $1, $2, to reconstruct the destination layout. - `package-type`: A regular expression string used to target specific artifact types, for example, docker, npm, or .\* to match all types.  Quote the value to prevent shell expansion of `$1`. See [Example 4](#example-4-path-mappings).
## Example 1: Promote an application version This command promotes an application version to the QA stage. ``` jfrog apptrust version-promote APP001 1.0.0 QA ``` **Output (error)**: ``` { "message": "Failed to promote version.", "error": "" } ``` ## Example 2: Promote an application version with optional flags This command performs a copy promotion in synchronous mode, while excluding repoA and repoB from the promotion. ``` jfrog apptrust version-promote APP001 1.0.0 DEV --sync=true --exclude-repos "repoA;repoB" --promotion-type copy ``` ## Example 3: Perform a dry-run promotion This command simulates a promotion to the QA stage: ``` jfrog apptrust version-promote APP001 1.0.0 QA --dry-run=true ``` ## Example 4: Path mappings This command applies a regex rule during a version promotion via the CLI, so that specific file extensions are automatically moved into designated subdirectories at the target destination. The example includes multiple mappings. ``` jf at version-promote my-app 1.5.0 PROD --path-mapping="input=(.*), output=stable-release/\$1, package-type=.*; input=(.*\.jar), output=jars/\$1, package-type=maven" ``` ## Frequently Asked Questions Common questions about promoting an application version. ##### Q: How do I promote an application version to a new stage using the JFrog CLI? **A:** Run `jf apptrust version-promote `. See [Example 1](#example-1-promote-an-application-version). ##### Q: What is the difference between the copy, move, and keep promotion types? **A:** `copy` preserves the source artifacts and copies them to the target stage, `move` transfers the source artifacts to the target stage, and `keep` promotes the version without copying or moving any artifacts. ##### Q: What happens if I promote with an overwrite-strategy of disabled? **A:** No overwriting is permitted. This is the strongest option for preserving artifact immutability, and it's ignored if you also choose `keep` as the promotion type. ##### Q: Can I change artifact paths when promoting to a target environment? **A:** Yes. Use `--path-mapping` with regex `input` and `output` rules to restructure paths or names in the target environment. See [Example 4](#example-4-path-mappings). ##### Q: Can I preview a promotion before running it? **A:** Yes. Pass `--dry-run=true` to simulate the promotion without actually performing it. See [Example 3](#example-3-perform-a-dry-run-promotion). ## Related Topics * [Application Version Management](/docs/application-version-management) * [Release Application Version CLI](/docs/release-application-version-cli) * [Roll Back Application Version Promotion CLI](/docs/roll-back-application-version-promotion-cli) * [Update Application Version CLI](/docs/update-application-version-cli)