---
schema_version: "1"
id: 391ba79dbdf849d38b1c449a993033c37adc0421760e2a4dc589338f8403ed9f
title: Creating or Updating Descriptor Files Using the CLI
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/exchange/apicat-create-descriptor-file-cli.md
canonical_url: https://docs.mulesoft.com/exchange/apicat-create-descriptor-file-cli
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 28683e9cfe4e7ea3c2b6a6a23a98313393a156a49c563f30987bf981a7aa2220
description: MuleSoft Documentation Site
latest: true
---
---
product: Exchange
---

# Creating or Updating Descriptor Files Using the CLI

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

Before you run the commands to publish your APIs, you must create a descriptor file that has the
information Exchange needs to catalog the APIs. Typically you create the file using the CLI and then
update the file manually to set more options to control how the assets are published.

The output descriptor information includes the following for each API:

- API definition file name

- Asset ID

- Asset version

- API version

## Create a Descriptor File

Use the `api-catalog create-descriptor` command to identify and output the API catalog descriptor
YAML results to a designated file. The command outputs cataloging information for all API
definitions it finds in the full directory tree relative to the current working directory.

### api-catalog create-descriptor

\> api-catalog create-descriptor \[flags\]

This command accepts the following flags:

<table><colgroup><col> <col></colgroup><thead><tr><th>Flag</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>-d, --file=file</p></div></div></td><td><div><div><p>Default: <code>catalog.yaml</code></p></div><div><p>The name and location in which to save the generated catalog descriptor file</p></div></div></td></tr><tr><td><div><div><p>--external</p></div></div></td><td><div><div><p>Generates an <code>exchange.json</code> file for each API described in the descriptor file and adds a reference to each of those in the descriptor file using the <code>ref</code> tag in the <code>projects</code> section</p></div></div></td></tr></tbody></table>

To create a descriptor file using the CLI:

1.  Navigate to the directory path that contains the APIs you want to catalog.

2.  Run the `api-catalog create-descriptor` command. The following example creates a descriptor file
    called `mydescriptor.yaml` in the current path:

    \> api-catalog create-descriptor -d mydescriptor.yaml

    Example output that is written to the descriptor file:

    #%Catalog Descriptor 1.0 projects:
    - main: async-spec.json assetId: async-api version: 2.0.0 apiVersion: v2
    - main: codat.json assetId: codat-api version: 1.0.0 apiVersion: v1
    - main: oas-3-spec.json assetId: oas-3-api version: 3.0.0 apiVersion: v3

    If you use the `--external` flag, an `exchange.json` file is generated for each of your APIs and
    the descriptor file has references to each of those as shown in the following example:

    \> api-catalog create-descriptor -d mydescriptor.yaml --external

    Example output that is written to the descriptor file:

    #%Catalog Descriptor 1.0 projects:
    - ref: api-spec/async-spec.exchange.json
    - ref: api-spec/codat.exchange.json
    - ref: api-spec/oas-3-spec.exchange.json

The presence and content of the designated descriptor file affects the result of the command as
follows:

- No file or empty file: The command discovers the APIs and writes the results to standard output
  and to a file named `catalog.yaml`.

- Existing file with content: The command fails and shows an error message that says the descriptor
  file already exists.

### Link Documentation Pages and Images through a Descriptor File

You can add documentation pages and images to your APIs by adding a Markdown file in the descriptor.
You can visualize the image in the documentation page created for the Exchange Asset.

Example descriptor file:

#%Catalog Descriptor 1.0 projects:

- main: sources/api.raml documentation:
  - Summary: Summary.md
  - Use Cases: Use\_Cases.md assetId: version-basic-api apiVersion: v4 version: 4.0.0

With the `Summary.md` file containing a link to an image (.png, .jpg) and a documentation Markdown
file:

This is a caching service that can be used to retrieve picklist values from publishers who wish to
provide a caching service for their picklist fields.

!\[muley logo\](https://docs.mulesoft.com/exchange/muleyLogo.png)

\[Read all the Use Cases\](https://docs.mulesoft.com/exchange/Use/_Cases.md)

The presence and content of the designated descriptor file affect the result of the command as
follows:

- No documentation entry for the referenced file in the descriptor catalog: the link to move between
  pages in the asset portal doesn’t work.

## Update a Descriptor File

Use the `api-catalog update-descriptor` command to update the API catalog descriptor YAML results in
a designated file. The command adds and updates cataloging information for all new and updated API
definitions it finds in the full directory tree relative to the current working directory.

This command cannot be used to update descriptor files created using the `--external` flag.

### api-catalog update-descriptor

\> api-catalog update-descriptor \[flags\]

This command accepts the following flag:

<table><colgroup><col> <col></colgroup><thead><tr><th>Flag</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>-d, --descriptor-file=descriptor-file</p></div></div></td><td><div><div><p>Default: <code>catalog.yaml</code></p></div><div><p>The name and location in which to save the updated catalog descriptor file information</p></div></div></td></tr></tbody></table>

To update a descriptor file using the CLI:

1.  Navigate to the directory path that contains the APIs you want to catalog.

2.  Run the `api-catalog update-descriptor` command. The following example updates a descriptor file
    called `mydescriptor.yaml` in the current path:

    \> api-catalog update-descriptor -d mydescriptor.yaml

The presence and content of the designated descriptor file affects the result of the command as
follows:

- No file or empty file: An error message is shown because the update requires that a valid
  descriptor file exists.

- Existing file with content: The command compares the APIs in the directory path to the list of
  APIs in the descriptor file and updates the descriptor file with new and updated API information.

- File with `ref` tags in the `projects` section: The command gives a parsing error, as the
  `update-descriptor` command does not support descriptor files with references to external
  `exchange.json` files.

## See Also

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

- [Publishing Assets Using API Catalog CLI](https://docs.mulesoft.com/exchange/apicat-publish-using-api-catalog-cli)

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