> 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 # Use cases > Step-by-step workflows for common Docusign CLI scenarios: first-time Agreement Manager setup, bulk configuration updates, and deploying configurations across multiple accounts. This page describes the recommended workflows for common Docusign CLI implementation scenarios. Each of these use cases presents high-level steps with the relevant CLI commands and links to detailed documentation: * [Use case 1: First-time customization](/docusign-cli/use-cases#use-case-1-first-time-customization) * [Use case 2: Bulk modify a production configuration](/docusign-cli/use-cases#use-case-2-bulk-modify-a-production-configuration) * [Use case 3: Move a configuration between accounts](/docusign-cli/use-cases#use-case-3-move-a-configuration-between-accounts) * [Use case 4: Bulk ingest agreements with metadata](/docusign-cli/use-cases#use-case-4-bulk-ingest-agreements-with-metadata) ## Use case 1: First-time customization This workflow describes the recommended steps for configuring Agreement Manager for the first time using the Docusign CLI, from installation through deploying a validated configuration to production and ingesting agreements. | Step | Action | Command or location | More information | | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | 1 | Install the Docusign CLI globally. | `npm i -g @docusign/agreement-cli` | [Get started with the Docusign CLI](/docusign-cli/get-started) | | 2 | Verify that the CLI installation was successful. | `ds` | [Get started with the Docusign CLI](/docusign-cli/get-started) | | 3 | Create a structured workspace and project directory. | `ds scaffold -w my-docusign-workspace -p my-project -f agreement-manager` | [Get started with the Docusign CLI](/docusign-cli/get-started) | | 4 | Connect the CLI to your developer account. | `ds auth login` | [Authenticate](/docusign-cli/authenticate) | | 5 | Retrieve the current Agreement Manager configuration to generate the catalogs. The standard catalog contains existing standard types and fields. The custom catalog may be empty in a new account. | `ds agm get catalog` | [Retrieve standard and custom catalogs](/docusign-cli/configure-agreement-types-and-fields/retrieve-standard-and-custom-catalogs) | | 6 | Define custom fields, custom agreement types, and extensions to standard agreement types in the manifest file. | `{workspace}/{project}/agreement-manager/configs/agreement-manager-manifest.json` | [Manifest reference](/docusign-cli/configure-agreement-types-and-fields/manifest-reference) | | 7 | Add training agreements for custom agreement types where `customExtractionEnabled` is set to true. | `{workspace}/{project}/agreement-manager/files/train/` | [Create a package](/docusign-cli/configure-agreement-types-and-fields/create-package) | | 8 | Upload the package to configure Agreement Manager and start AI training. | `ds agm upload` | [Upload a package](/docusign-cli/configure-agreement-types-and-fields/upload-package) | | 9 | Run the `catalog` command again to verify that fields, types, and mappings were created successfully. | `ds agm get catalog` | [Retrieve standard and custom catalogs](/docusign-cli/configure-agreement-types-and-fields/retrieve-standard-and-custom-catalogs) | | 10 | Add a diverse set of actual agreements (up to 400) to validate AI extraction accuracy. | `{workspace}/{project}/agreement-manager/files/test/` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 11 | Upload the test agreements to Agreement Manager. | `ds agm test --setup` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 12 | Generate the testing template CSV. | `ds agm test --generate-test-template` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 13 | Enter the ground truth values for each agreement and every relevant field in the testing file. | `{workspace}/{project}/agreement-manager/tests/testing.csv` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 14 | Run the test to compare AI-extracted values with ground truth values. | `ds agm test --run` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 15 | Review result files and identify fields or agreement types where accuracy is below the desired threshold. | `{workspace}/{project}/agreement-manager/tests/` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 16 | Update the field descriptions, training examples, or custom agreement type descriptions to improve extraction accuracy. **Note:** Only custom extractions can be improved at this time. | `{workspace}/{project}/agreement-manager/configs/agreement-manager-manifest.json` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 17 | Upload the updated configuration. | `ds agm upload` | [Upload a package](/docusign-cli/configure-agreement-types-and-fields/upload-package) | | 18 | Reprocess the updated configuration and test agreements. | `ds agm test --setup` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 19 | If you added test agreements, update the testing template CSV. | `ds agm test --generate-test-template` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 20 | If you added test agreements, update the ground truth values in the CSV file. | `{workspace}/{project}/agreement-manager/tests/testing.csv` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 21 | Run the test again to measure the updated accuracy. | `ds agm test --run` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 22 | Once the desired accuracy threshold is achieved, connect the CLI to the production account. | `ds auth login -e production` | [Authenticate](/docusign-cli/authenticate) | | 23 | Upload the finalized Agreement Manager package to the production account. | `ds agm upload` | [Deploy agreement customizations](/docusign-cli/deploy-agreement-customizations) | | 24 | *(Optional)* Repeat steps 10-17 in production to perform a sanity check of extraction accuracy. | | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 25 | Place your actual production agreements in a directory for ingestion. | | [Bulk ingest agreements in production](/docusign-cli/bulk-ingest-agreements) | | 26 | Run the bulk ingest command to upload all agreements into Agreement Manager. | `ds agm ingest ` | [Bulk ingest agreements in production](/docusign-cli/bulk-ingest-agreements) | ## Use case 2: Bulk modify a production configuration This workflow describes how to update or extend an existing Agreement Manager configuration in production. This is useful to: * Add new custom fields * Introduce new agreement types * Update extraction descriptions * Extend existing mappings in bulk The recommended approach is: 1. Retrieve the current configuration from production 2. Update it locally 3. Deploy and validate the changes in a fresh developer account 4. Deploy the finalized configuration back to production 5. Reprocess to apply the configuration changes to previously ingested agreements | Step | Action | Command or location | More information | | ---- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | 1 | Connect the CLI to the production account. | `ds auth login -e production` | [Authenticate](/docusign-cli/authenticate) | | 2 | Retrieve the current Agreement Manager configuration to generate the latest catalogs. | `ds agm get catalog` | [Retrieve standard and custom catalogs](/docusign-cli/configure-agreement-types-and-fields/retrieve-standard-and-custom-catalogs) | | 3 | Review the standard catalog and custom catalog to understand the current configuration. | `{workspace}/{project}/agreement-manager/configs/` | [Retrieve standard and custom catalogs](/docusign-cli/configure-agreement-types-and-fields/retrieve-standard-and-custom-catalogs) | | 4 | Update the manifest with the required changes, such as new fields, agreement types, and mappings, or improved descriptions and examples. | `{workspace}/{project}/agreement-manager/configs/agreement-manager-manifest.json` | [Manifest reference](/docusign-cli/configure-agreement-types-and-fields/manifest-reference) | | 5 | Connect the CLI to a fresh developer account for safe testing. | `ds auth login` | [Authenticate](/docusign-cli/authenticate) | | 6 | Upload the updated Agreement Manager package to the developer account. | `ds agm upload` | [Upload a package](/docusign-cli/configure-agreement-types-and-fields/upload-package) | | 7 | Add training agreements for custom agreement types where `customExtractionEnabled` is set to `true`. | `{workspace}/{project}/agreement-manager/files/train/` | [Create a package](/docusign-cli/configure-agreement-types-and-fields/create-package) | | 8 | Add a diverse set of agreements (up to 400) to test extraction accuracy. | `{workspace}/{project}/agreement-manager/files/test/` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 9 | Upload the test agreements to Agreement Manager. | `ds agm test --setup` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 10 | Generate the testing template CSV. | `ds agm test --generate-test-template` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 11 | Enter the ground truth values for the relevant fields. | `{workspace}/{project}/agreement-manager/tests/testing.csv` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 12 | Run the test to compare AI-extracted values with ground truth values. | `ds agm test --run` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 13 | Review the results and identify fields or agreement types where accuracy is below the desired threshold. | `{workspace}/{project}/agreement-manager/tests/` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 14 | Refine field descriptions, examples, or agreement type definitions in the manifest to improve extraction accuracy. | `{workspace}/{project}/agreement-manager/configs/agreement-manager-manifest.json` | [Manifest reference](/docusign-cli/configure-agreement-types-and-fields/manifest-reference) | | 15 | Upload the updated configuration. | `ds agm upload` | [Upload a package](/docusign-cli/configure-agreement-types-and-fields/upload-package) | | 16 | Reprocess the updated configuration and test agreements. | `ds agm test --setup` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 17 | If you added test agreements, update the testing template CSV. | `ds agm test --generate-test-template` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 18 | If you added test agreements, update the ground truth values in the CSV file. | `{workspace}/{project}/agreement-manager/tests/testing.csv` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 19 | Run the test again to validate improvements. | `ds agm test --run` | [Test agreement customizations](/docusign-cli/test-agreement-customizations) | | 20 | Once the desired accuracy threshold is achieved, reconnect the CLI to the production account. | `ds auth login -e production` | [Authenticate](/docusign-cli/authenticate) | | 21 | Upload the finalized Agreement Manager package to production. | `ds agm upload` | [Deploy agreement customizations](/docusign-cli/deploy-agreement-customizations) | | 22 | Reprocess to update agreement classifications and extracted data for previously ingested agreements. | `ds agm reprocess [options]` | [Reprocess agreements](/docusign-cli/reprocess-agreements) | ## Use case 3: Move a configuration between accounts This workflow describes how to move an Agreement Manager configuration from one account to another without modification or retesting. This is useful when you want to replicate the same Agreement Manager setup across multiple accounts or customers, such as deploying a proven configuration from one production account to another. Since the configuration has already been validated, no additional training or testing is required. | Step | Action | Command or location | More information | | ---- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | | 1 | Connect the CLI to the source production account containing the configuration you want to move. | `ds auth login -e production` | [Authenticate](/docusign-cli/authenticate) | | 2 | Fetch the whole Agreement Manager configuration. | `ds agm catalog-to-manifest --all` | [Retrieve standard and custom catalogs](/docusign-cli/configure-agreement-types-and-fields/retrieve-standard-and-custom-catalogs) | | 3 | Copy the manifest JSON and training files from the export folder into the main manifest and train folders. | Export folder: `{workspace}/{project}/agreement-manager/export` Manifest folder: `{workspace}/{project}/agreement-manager/configs` Train folder: `{workspace}/{project}/agreement-manager/files/train` | [Create a package](/docusign-cli/configure-agreement-types-and-fields/create-package) | | 4 | Ensure that the manifest reflects the configuration you want to move. | `{workspace}/{project}/agreement-manager/configs/agreement-manager-manifest.json` | [Manifest reference](/docusign-cli/configure-agreement-types-and-fields/manifest-reference) | | 5 | Connect the CLI to the target account where the configuration should be deployed. | `ds auth login -e production` | [Authenticate](/docusign-cli/authenticate) | | 6 | Upload the Agreement Manager package to apply the configuration in the target account. | `ds agm upload` | [Deploy agreement customizations](/docusign-cli/deploy-agreement-customizations) | | 7 | Verify that the fields, agreement types, and mappings were successfully created in the target account. | `ds agm get catalog` | [Retrieve standard and custom catalogs](/docusign-cli/configure-agreement-types-and-fields/retrieve-standard-and-custom-catalogs) | | 8 | Reprocess to update agreement classifications and extracted data for previously ingested agreements. | `ds agm reprocess [options]` | [Reprocess agreements](/docusign-cli/reprocess-agreements) | ## Use case 4: Bulk ingest agreements with metadata This workflow uploads agreements, along with a metadata file that supplies missing or corrected information for the agreement fields. This use case assumes that you have already completed the deployment of your configuration, including all standard and custom fields that will be populated with metadata. See [Bulk ingest agreements with metadata](/docusign-cli/bulk-ingest-agreements#bulk-ingest-agreements-with-metadata) for additional prerequisites. Docusign recommends testing with a subset of documents in your developer account before uploading the full set with metadata in production. The steps below reflect this process. | Step | Action | Command or location | More information | | ---- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | 1 | Connect the CLI to your developer account. | `ds auth login` | [Authenticate](/docusign-cli/authenticate) | | 2 | Place a subset of your production agreements in a directory for ingestion. | | [Bulk ingest agreements in production](/docusign-cli/bulk-ingest-agreements) | | 3 | Generate a template CSV file for the metadata. | `ds agm ingest --directory --generate-metadata-template` | [Bulk ingest agreements in production](/docusign-cli/bulk-ingest-agreements) | | 4 | Populate the CSV file with metadata values for the files to be ingested. | `{workspace}/{project}/agreement-manager/metadata/metadata.csv` | [Bulk ingest agreements in production](/docusign-cli/bulk-ingest-agreements) | | 5 | Ingest the agreements with the metadata. | `ds agm ingest --directory --with-metadata` | [Bulk ingest agreements in production](/docusign-cli/bulk-ingest-agreements) | | 6 | Spot check in the Agreement Manager UI that the metadata you supplied appears as expected. | | [Agreement Preview Page](https://support.docusign.com/s/document-item?bundleId=pqz1702943441912\&topicId=mut1702945643401.html) | | 7 | Connect the CLI to the production account. | `ds auth login -e production` | [Authenticate](/docusign-cli/authenticate) | | 8 | Repeat steps 2-5 in production with the full set of agreements. | | | ## Frequently asked questions ### Do I need to retest my configuration when deploying to a new production account? Not necessarily. If you are replicating a configuration that has already been validated (use case 3), no additional training or testing is required. If you are modifying an existing configuration before deploying to production (use case 2), the recommended approach is to validate the updated configuration in a fresh developer account before deploying to production. ### Can I skip the accuracy validation steps and upload directly to production? The CLI does not prevent you from uploading directly to production, but the recommended practice is to validate configurations in the developer environment first. Deploying an untested configuration to production can result in incorrect AI extraction for live agreements. ### What should I do if extraction accuracy is still low after refining the manifest? Common improvements include adding more diverse training examples (three to five minimum per field, five to 10 per custom agreement type), improving AI definition descriptions so the model clearly understands what each field represents, and ensuring that training documents represent realistic production agreements rather than edge cases. See [Test agreement customizations](/docusign-cli/test-agreement-customizations) for detailed guidance on improving accuracy results. ### How many agreements can I ingest in a single bulk ingest run? The CLI does not limit the number of files per ingest run. The `ingest` command supports targeting individual files or entire directories, including recursive scanning of subdirectories. Duplicate detection is built in. Files that have already been ingested are automatically skipped. ### 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 * [Authenticate](/docusign-cli/authenticate) the Docusign CLI with your Docusign account. * Learn how to [define custom agreements and fields](/docusign-cli/configure-agreement-types-and-fields). * Review the process to [test agreement customizations](/docusign-cli/test-agreement-customizations).