> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# Upload a package

> Learn how to upload your Agreement Manager package using the Docusign CLI. Includes command syntax, options, post-upload results, and validation error guidance.

The `upload` command deploys your package to Agreement Manager, configuring custom fields, custom agreement types, and field mappings, and providing AI extraction training. You run this command after [creating your package](/docusign-cli/configure-agreement-types-and-fields/create-package),  [creating a manifest](/docusign-cli/configure-agreement-types-and-fields/manifest-reference) with your customizations, and [supplying training documents](/docusign-cli/configure-agreement-types-and-fields/create-package#training-documents).

The `upload` command is safe to run multiple times. Each time you run it, the CLI validates your manifest and applies any changes defined in it to the existing Agreement Manager configuration.

> **Note**
>
> After you deploy an updated package to an environment where agreements have already been ingested, you must  [reprocess](/docusign-cli/reprocess-agreements) to apply the configuration changes to previously ingested agreements. A reprocess updates agreement type classifications and extracted field data to reflect the definitions in the newly deployed package.

For a walkthrough of the upload process, see this video:

## Prerequisites

Before uploading a package, ensure that:

* Your manifest file exists at `{workspaceName}/{projectName}/agreement-manager/configs/agreement-manager-manifest.json`.
* For each custom agreement type where `customExtractionEnabled` is set to `true`, training agreement files are present in `{workspaceName}/{projectName}/agreement-manager/files/train/` and are referenced in the `docs` property of the agreement type definition in the manifest. See the [manifest reference](/docusign-cli/configure-agreement-types-and-fields/manifest-reference) for details on the `docs` property.
* You are authenticated to the target Docusign environment (developer or production). See [Authenticate](/docusign-cli/authenticate) for instructions.

## Upload command

To upload your Agreement Manager IAM package, run the `upload` command from your workspace directory.

#### Command syntax

`ds agm upload [options]`

#### Options

| Option       | Description                                                                                                                      | Default |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `--bypass`   | Skips the confirmation prompt before uploading.                                                                                  | `false` |
| `-y`         | Alias for `--bypass`. Skips the confirmation prompt before uploading.                                                            | `false` |
| `--dry-run`  | Displays manifest additions, updates, and deletions that would be included in the upload without actually uploading the package. | N/A     |
| `-h, --help` | Displays help information for the command.                                                                                       | N/A     |

#### Example

Upload the package, skipping the confirmation prompt:

`ds agm upload --bypass`

## What happens after a successful upload

After a successful upload, Agreement Manager is updated with the configuration defined in your manifest:

* Custom fields defined in the manifest are created in Agreement Manager. If a custom field already exists, its properties-such as the description, category, extraction settings, and training examples-are overwritten with the values in the manifest.
* Custom agreement types defined in the manifest are created in Agreement Manager. If a custom agreement type already exists, it is updated and its field mappings are applied as defined in the manifest.
* Additional standard and custom fields are mapped to the specified standard and custom agreement types.
* If you have removed fields that you previously added to standard or custom agreement types, Docusign unmaps those fields from the agreement types. See [Field removal from custom agreement types](/docusign-cli/configure-agreement-types-and-fields/manifest-reference#field-removal-from-custom-agreement-types) and [Field removal from standard agreement types](/docusign-cli/configure-agreement-types-and-fields/manifest-reference#field-removal-from-standard-agreement-types) for additional information.
* For custom agreement types where `customExtractionEnabled` is set to `true`, example agreements referenced in the `docs` property are uploaded to train the AI. If training documents were previously uploaded, the CLI reuses them and does not upload duplicates.
* AI extraction is enabled in Agreement Manager for custom agreement types and custom fields where `customExtractionEnabled` is set to `true`.

To verify that your fields, agreement types, and mappings were created or updated correctly, run the [get catalog](/docusign-cli/configure-agreement-types-and-fields/retrieve-standard-and-custom-catalogs#retrieve-current-configuration) command after the upload completes.

## Upload validation errors

Before uploading your package to Agreement Manager, the CLI validates your manifest. If the manifest is misconfigured, the upload is blocked and an error message is returned. See [Manifest validation errors](/docusign-cli/troubleshooting#manifest-validation-errors) for information about error causes and resolutions.

## Frequently asked questions

### What happens if I run the upload command multiple times?

The `upload` command is safe to run multiple times. If there are no changes in the manifest, the CLI does not upload anything. If updates are present, the CLI updates the existing configuration in Agreement Manager and applies the changes defined in the manifest.

### Can I use the upload command to remove custom fields or custom agreement types?

No. The `upload` command creates and updates configuration - it does not delete custom fields or custom agreement types. Once a custom field or custom agreement type is added to an Agreement Manager account, it cannot be removed using the CLI.

### Can I use the upload command to remove additional fields from an agreement type?

Yes. To remove additional fields from an agreement type, delete the corresponding field labels from the `additionalStandardFields` or `customFields` arrays for that agreement type in the manifest, then run the `upload` command again. The default standard fields mapped to each agreement type cannot be changed or removed.

### What should I do if the upload fails with a validation error?

Review the error message returned by the CLI, correct the identified issue in your manifest or training file directory, and run the `upload` command again. The validation error table on this page describes the cause and resolution for each error. If multiple errors are returned, resolve them all before re-running the command.

### How do I verify that the upload was successful?

Run the [get catalog](/docusign-cli/configure-agreement-types-and-fields/retrieve-standard-and-custom-catalogs#retrieve-current-configuration) command after the upload completes to retrieve the updated Agreement Manager configuration. Review the output to confirm that your custom fields, custom agreement types, and field mappings were created or updated as expected.

### Does Docusign re-extract data automatically for existing agreements when I deploy an updated configuration?

No. If you deploy an updated package to an environment where agreements have already been ingested, you must [reprocess](/docusign-cli/reprocess-agreements) to update agreement type classifications and re-extract field data based on the definitions in the newly deployed package.

## Next steps

* [Test agreement customizations](/docusign-cli/test-agreement-customizations) to validate AI extraction accuracy before deploying to production.
* [Deploy agreement customizations](/docusign-cli/deploy-agreement-customizations) to a production account or to multiple accounts.
* Learn about [bulk ingesting agreements in production](/docusign-cli/bulk-ingest-agreements), including supported file types and how duplicate detection works.