Using File Specs

JFrog Integrations Documentation

Content Type

File Specs can be used to specify a list of files, which can be then uploaded or downloaded to or from Artifactory. They are specified in JSON format and are currently supported in JFrog CLI, Jenkins Artifactory Plug-in, TeamCity Artifactory Plug-in, and Bamboo Artifactory Plug-in.

This article describes the File Specs structure used in Jenkins, TeamCity, and the Bamboo Artifactory plugins .You can read about JFrog CLI with File Specs.

The download spec schema offers the option of using AQL or wildcard patterns according to the JSON element you specify:Artifactory Query Language

  "files": [
      "pattern" or "aql": "[Mandatory]",
      "target": "[Optional, Default: ./]",
      "props": "[Optional]",
      "recursive": "[Optional, Default: true]",
      "flat": "[Optional, Default: false]",
      "build": "[Optional]",
          "explode": "[Optional, Default: false]",
          "excludePatterns": ["[Optional]"],
          "sortBy" : ["[Optional]"],
      "sortOrder": "[Optional, Default: 'asc']",
      "limit": [Optional],
      "offset": [Optional]





[Mandatory if 'aql' is not specified]

Specifies the source path in Artifactory, from which the artifacts should be downloaded, in the following format: [repository name]/[repository path]. You can use wildcards to specify multiple artifacts.



Specifies the local file system path to which artifacts which should be downloaded.

For flexibility in specifying the target path, you can include placeholders in the form of {1}, {2}, {3}...which are replaced by corresponding tokens in the pattern property that are enclosed in parenthesis. For more details, please refer to Using Placeholders.


[Mandatory if 'pattern' is not specified]

An AQL query that specified the artifacts to be downloaded.



List of "key=value" pairs separated by a semi-colon. (For example, "key1=value1;key2=value2;key3=value3). Only artifacts with all of the specified properties and values will be downloaded.


[Default: false]

If true, artifacts are downloaded to the exact target path specified and their hierarchy in the source repository is ignored.

If false, artifacts are downloaded to the target path in the file system while maintaining their hierarchy in the source repository.


[Default: true]

If true, artifacts are also downloaded from sub-paths under the specified path in the source repository.

If false, only artifacts in the specified source path directory are downloaded.



If specified, only artifacts of the specified build are downloaded. The 'pattern' property is still taken into account when 'build' is specified.

The property format is build-name/build-number.

If the build number is not specified, or the keyword LATEST is used for the build number, then the latest published build number is used.


[Default: false]

If true, the downloaded archive file is extracted after the download. The archived file itself is deleted locally. The supported archive types are: zip, tar; tar.gz; and tgz


[Optional. Applicable only when 'pattern' is specified]

An array (enclosed with square brackets) of patterns to be excluded from downloading. Unlike the "pattern" property, "excludePatterns" must NOT include the repository as part of the pattern's path. You can use wildcards to specify multiple artifacts.

For example: ["*.sha1","*.md5"]



A list of semicolon-separated fields to sort by. The fields must be part of the 'items' AQL domain. For more information read the AQL documentation.Artifactory Query Language


[Default: asc]

The order by which fields in the sortBy option should be sorted. Accepts asc or desc.



The maximum number of items to fetch. Usually used with the sortBy option.



The offset from which to fetch items (i.e. how many items should be skipped). Usually used with the sortBy option.


Currently sortBy, sortOrder, limit and offset are not supported in TeamCity.