---
schema_version: "1"
id: 3730ac9d0f1338af3518f7aabcb955f7a017d4f24ed687a1210b05e85000f419
title: Publishing Assets Using API Catalog CLI
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/exchange/apicat-publish-using-api-catalog-cli.md
canonical_url: https://docs.mulesoft.com/exchange/apicat-publish-using-api-catalog-cli
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 85414a7351e918ede88b235e9e79aa8863af209535c2a5ce836891aeec7830ff
description: MuleSoft Documentation Site
latest: true
---
---
product: Exchange
---

# Publishing Assets Using API Catalog CLI

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can use the `api-catalog publish-asset` command to publish your API definitions to Exchange.
Embed this command in your automation tools, such as a CI/CD pipeline or custom scripts, to
automatically trigger the cataloging of your API assets. The command publishes your API definitions
using the information in the file specified in the `--descriptor-file` option.

## Before You Begin

Create a descriptor file that describes the API definitions to publish and copy the file to the file
path where your API projects are stored. See
[Create a Descriptor File Using the CLI](https://docs.mulesoft.com/exchange/apicat-create-descriptor-file-cli#create-desc-file-cli).

To publish an API definition using the CLI:

- Run the `api-catalog publish-asset` command. The following example publishes API definitions
  described in the `catalog.yaml` file:

  \> api-catalog publish-asset -d catalog.yaml --host=anypoint.mulesoft.com
  --organization=1234abc-b34a-7cd3-4s32-12345abc2345 --username=myAnyPtAccount
  --password=myPwd@4!myacct

The following sections give example commands that show how several catalog flags are used:

- [Publish an Asset with Default Settings](#default-settings)

- [Perform a Dry Run to Validate the Descriptor File](#dry-run)

- [Publish an Asset Regardless of the Content](#force-publish)

- [Trigger the Publish Using Conditions](#trigger-conditions)

- [Set Version Strategy Using Conditions](#versionStrategyConditions)

- [Publish Using a Jenkins Script](#jenkins-script)

## api-catalog publish-asset

\> api-catalog publish-asset \[flags\]

This command accepts the
[general and authentication flags](https://docs.mulesoft.com/exchange/apicat-use-api-catalog-cli#common-options) in addition to the
following flags:

<table><colgroup><col> <col></colgroup><thead><tr><th>Flag</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>--async</p></div></div></td><td><div><div><p>Runs the publish job asynchronously.</p></div></div></td></tr><tr><td><div><div><p>-d, --descriptor-file=descriptor-file</p></div><div><p>or</p></div><div><p>ANYPOINT_DESCRIPTOR_FILE environment variable</p></div></div></td><td><div><div><p>Default: ./catalog.yaml</p></div><div><p>The name and location of the catalog descriptor file.</p></div><div><ul><li><p>If the file does not exist, no assets are cataloged.</p></li><li><p>If the file exists but is empty, the command creates and prints the catalog descriptor YAML results. It outputs cataloging information for all API definitions it finds in the full directory tree relative to the current working directory.</p></li><li><p>If a valid YAML file exists, the command catalogs the assets as specified.</p></li></ul></div><div><p>See <a href="https://docs.mulesoft.com/exchange/apicat-create-descriptor-file-cli#create-desc-file-cli">Create a Descriptor File Using the CLI</a>.</p></div></div></td></tr><tr><td><div><div><p>--dry-run</p></div></div></td><td><div><div><p>Runs the command to verify that the descriptor file is valid. No APIs are published.</p></div></div></td></tr><tr><td><div><div><p>--force-publish</p></div></div></td><td><div><div><p>Bypasses the comparison and creates a new version of the asset in Exchange regardless of the content.</p></div></div></td></tr><tr><td><div><div><p>--force-update-metadata</p></div></div></td><td><div><div><p>Updates the asset’s metadata, such as tags, in the latest version in Exchange regardless of the content. This does not republish the asset.</p></div></div></td></tr><tr><td><div><div><p>--json</p></div></div></td><td><div><div><p>Prints the execution result in JSON format.</p></div></div></td></tr><tr><td><div><div><p>-s, --silent</p></div></div></td><td><div><div><p>Enables silent logging.</p></div></div></td></tr><tr><td><div><div><p>-t, --trigger-criteria=&lt;descriptor-tag&gt;:&lt;value&gt; --trigger-criteria=&lt;descriptor-tag&gt;:value</p></div></div></td><td><div><div><p>This flag works in conjunction with the <code>triggerConditions</code> section in the descriptor file. For each run of the <code>api-catalog publish-asset</code> command, the trigger values are compared to trigger condition values in the descriptor file to determine whether to publish the APIs described in the descriptor file. To match multiple conditions, specify separate <code>--trigger-criteria</code> flags for each condition. For the APIs to be published, all trigger conditions set in the descriptor file must be matched by <code>--trigger-criteria</code> flag values.</p></div><div><p>Example:</p></div><div><p><code>--trigger-criteria=branch:main --trigger-criteria=anytag:release/ --trigger=user:admin</code></p></div><div><p>See <a href="https://docs.mulesoft.com/exchange/apicat-create-descriptor-file-manually#descriptor-yaml">Descriptor YAML Schema</a>.</p></div></div></td></tr><tr><td><div><div><p>-v, --verbose</p></div></div></td><td><div><div><p>Enables verbose logging.</p></div></div></td></tr><tr><td><div><div><p>--version-strategy-criteria=&lt;descriptor-tag&gt;:&lt;value&gt; --version-strategy-criteria=&lt;descriptor-tag&gt;:&lt;value&gt;</p></div></div></td><td><div><div><p>This flag works in conjunction with the <code>versionStrategyConditions</code> section in the descriptor file. The <code>api-catalog publish-asset</code> command compares the version strategy criteria values to version strategy condition values in the descriptor file to determine the version strategy to use to publish the APIs. To match multiple conditions, specify separate <code>--version-strategy-criteria</code> flags for each condition.</p></div><div><p>Example:</p></div><div><p><code>--version-strategy-criteria=branch:main --version-strategy-criteria=anytag:release/ --version-strategy-criteria=user:admin</code></p></div><div><p>See <a href="https://docs.mulesoft.com/exchange/apicat-create-descriptor-file-manually#descriptor-yaml">Descriptor YAML Schema</a>.</p></div></div></td></tr></tbody></table>

## Publish an Asset with Default Settings

The following example publishes the API to an organization in the US control plane for Anypoint
Platform. Defaults, credentials configuration file settings, or environment variable settings are
used for the unspecified flags.

\> api-catalog publish-asset --organization 1234abc-b34a-7cd3-4s32-12345abc2345

## Perform a Dry Run to Validate the Descriptor File

This example shows the `api-catalog publish-asset` command with the following flags:

- \--dry-run: Runs the command to verify that the descriptor file is valid but does not publish the
  APIs.

- \--verbose: Shows the maximum information in the results.

The example command sends the standard output to `mycatdryrun.log`.

\> api-catalog publish-asset --host=anypoint.mulesoft.com -d catalog.yaml
--organization=1234abc-b34a-7cd3-4s32-12345abc2345 --client\_id=1787c36ab544466698e380131040faad
--client\_secret=2dA616efca1E4181A2A77BBF046868BE --dry-run --verbose >> mycatdryrun.log

## Publish an Asset Regardless of the Content

To publish a new version of the asset in Exchange regardless of the content, use the
`--force-publish` flag.

This example shows the `api-catalog publish-asset` command with both of these flags. Defaults,
credentials configuration file settings, or environment variable settings are used for the
unspecified flags.

\> api-catalog publish-asset --host=anypoint.mulesoft.com --descriptor-file=mydescriptor.yaml
--organization=1234abc-b34a-7cd3-4s32-12345abc2345 --force-publish

## Trigger the Publish Using Conditions

Custom trigger conditions enable you to control whether APIs are published when the API Catalog
`publish-assets` runs as part of your CI/CD pipeline or scripts. This example shows how
`--trigger-criteria` flags correlate with descriptor file trigger conditions to control whether or
not to publish the described APIs. If a trigger condition is set at the API level, that setting
overrides conditions set at the global level.

### Example Trigger Conditions in a Descriptor file

Following is an example `triggerConditions` section in the `mydescriptor.yaml` descriptor file at
the global level:

---

triggerConditions: ref:

- main tags:
- migrate
- republish status:
- complete
- ready

---

### Example That Triggers the Publish

The following command triggers the API publish because the trigger option values match all of the
global trigger conditions in the `mydescriptor.yaml` descriptor file.

\> api-catalog publish-asset --host=anypoint.mulesoft.com -d mydescriptor.yaml
--organization=1234abc-b34a-7cd3-4s32-12345abc2345 --username=myAnyPtAccount
--password=myPwd@4!myacct --trigger-criteria=ref:main --trigger-criteria=tags:migrate
--trigger-criteria=status:complete

### Example That Does Not Trigger the Publish

The following command does not trigger the API publish because the trigger option value for `ref` is
`test`, not `main`. Because not all trigger values match the corresponding global trigger
conditions, no APIs are published.

\> api-catalog publish-asset --host=anypoint.mulesoft.com -d mydescriptor.yaml
--organization=1234abc-b34a-7cd3-4s32-12345abc2345 --username=myAnyPtAccount
--password=myPwd@4!myacct --trigger-criteria=ref:test --trigger-criteria=tags:migrate
--trigger-criteria=status:complete

## Set Version Strategy Using Conditions

Version strategy conditions enable you to set the version of assets when the API Catalog
`publish-asset` command runs as part of your CI/CD pipeline or scripts. This example shows how
`--version-strategy-criteria` flags correlate with descriptor file version strategy conditions to
set the version strategy for the described APIs. If a version strategy condition is set at the API
level, that setting overrides conditions set at the global level. If the value for a condition
matches more than one version strategy, the command gives an error.

### Example Version Strategy Conditions in a Descriptor File

Following is an example `versionStrategyConditions` section in the `mydescriptor.yaml` descriptor
file.

versionStrategyConditions: patchIncrease: branch: ‘main’ author: ‘admin’ snapshot: branch: ‘test’
‘Develop’

### Example That Sets the Version Strategy During the Publish

The following command sets multiple version strategies during the publish because the option values
match multiple conditions in the `mydescriptor.yaml` descriptor file.

\> api-catalog publish-asset --host=anypoint.mulesoft.com -d mydescriptor.yaml
--organization=1234abc-b34a-7cd3-4s32-12345abc2345 --username=myAnyPtAccount
--password=myPwd@4!myacct --version-strategy-criteria=branch:main
--version-strategy-criteria=author:admin --version-strategy-criteria=branch:test
--version-strategy-criteria=branch:Develop

The resulting version strategies are:

- Patch increase for APIs in the `main` branch with an author of `admin`.

- Snapshot for APIs in the `test` and `Develop` branches.

### Example That Does Not Set the Version Strategy During the Publish

The following command does not set the version strategy during the publish because none of the
values match the corresponding conditions. The version strategy defaults to `patchIncrease` if no
`versionStrategy` tags set other values in the descriptor file.

\> api-catalog publish-asset --host=anypoint.mulesoft.com -d mydescriptor.yaml
--organization=1234abc-b34a-7cd3-4s32-12345abc2345 -u myAnyPtAccount -p myPwd@4!myacct
----version-strategy-criteria=branch:abc ----version-strategy-criteria=author:dev
----version-strategy-criteria=branch:xyz ----version-strategy-criteria=branch:pop

For more information on version strategies and version strategy conditions, see
[Descriptor YAML Schema](https://docs.mulesoft.com/exchange/apicat-create-descriptor-file-manually).

## Publish Using a Jenkins Script

This example shows a Jenkins script that runs the `api-catalog publish-asset` command.

```java
pipeline {
    agent any
    environment {
        ANYPOINT_ORG_ID = '1234abc-b34a-7cd3-4s32-12345abc2345'
        CATALOG_DESCRIPTOR = './descriptor.yaml' (1)
     }
     stages {
        stage('git checkout') {
            steps {
                git url: 'git@github.com:mygitlocation/api-catalog-cli.git'
                // additional checkout tasks
            }
        }
        stage('Build Artifacts') {
            steps {
                 // building
            }
        }
        stage('API Cataloging') {
            steps {
                 withCredentials([
                    usernamePassword(credentialsId: 'my-anypoint-creds',
                    usernameVariable: 'ANYPOINT_USERNAME',
                    passwordVariable: 'ANYPOINT_PASSWORD')
                ]) {
                    sh 'api-catalog-cli publish-asset -d $CATALOG_DESCRIPTOR --organization=$ANYPOINT_ORG_ID --host=anypoint.mulesoft.com/ --trigger-criteria=branch:main' (2)
                }
            }
        }
         stage('Deploy') {
            steps {
                // Any deployment tasks to be performed, here.
            }
        }
    }
```

<table><tbody><tr><td><i data-value="1"></i><b>1</b></td><td>Defines the organization and descriptor file values</td></tr><tr><td><i data-value="2"></i><b>2</b></td><td>Runs the <code>api-catalog publish-asset</code> command to publish APIs found in the <code>main</code> Github branch</td></tr></tbody></table>

## See Also

- [General Use of Commands and Flags](https://docs.mulesoft.com/exchange/apicat-use-api-catalog-cli)

- [Creating or Updating Descriptor Files Using the CLI](https://docs.mulesoft.com/exchange/apicat-create-descriptor-file-cli)

- [Creating or Updating Descriptor Files Manually](https://docs.mulesoft.com/exchange/apicat-create-descriptor-file-manually)