Creating or Updating Descriptor Files Using the CLI | MuleSoft Documentation
# Creating or Updating Descriptor Files Using the CLI
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:
Flag | Description  
---|---  
-d, --file=file |  Default: `catalog.yaml` The name and location in which to save the generated catalog descriptor file  
Generates an `exchange.json` file for each API described in the descriptor file and adds a reference to each of those in the descriptor file using the `ref` tag in the `projects` section  
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](muleyLogo.png)
[Read all the Use Cases](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:
Flag | Description  
---|---  
-d, --descriptor-file=descriptor-file |  Default: `catalog.yaml` The name and location in which to save the updated catalog descriptor file information  
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
  * Publishing Assets Using API Catalog CLI
  * Creating or Updating Descriptor Files Manually