Introducing the Docusign CLI: Configure, Test, and Deploy Agreement Manager

Key takeaways

• The Docusign CLI lets you define, test, and deploy Agreement Manager configurations as code instead of repeating setup in the UI.

• You manage custom agreement types, fields, mappings, and AI training documents through an agreement-manager-manifest.json file.

• You can test extraction accuracy against up to 400 agreements, refine the configuration, and rerun the tests until the results meet your requirements.

• After validation, you can reuse the same configuration across accounts, run repeatable test workflows, and bulk ingest existing agreements.

Configuring Docusign Agreement Manager once is straightforward. Repeating the same configuration across multiple accounts or environments is harder. 

Custom agreement types, extraction fields, training documents, and test results all need to stay consistent from development through production. The Docusign CLI turns that setup into a configuration-as-code workflow that can be versioned, reviewed, tested, and reused. 

In this tutorial, you’ll define an Agreement Manager configuration in JSON, test extraction accuracy against real agreements, refine the configuration, and upload the validated package to production. 

The Docusign CLI is currently in Open Beta and is available via npm as @docusign/docusign-cli.

Prerequisites

Before you begin, make sure you have: 

• A Docusign developer account with Agreement Manager admin permissions. All developer accounts include this by default.

• Node.js and npm installed.

• A code editor

How the configuration and testing workflow works 

The local workspace is the source of truth for your Agreement Manager configuration. It contains:

• An agreement-manager-manifest.json file that defines your agreement types and fields

• A train/ directory containing documents used to train custom extractions

• A test/ directory containing agreements used to measure extraction accuracy

You first upload the workspace to a developer account and test the configuration against expected values from your own agreements. If the results fall below your target, update the manifest or training documents, upload the changes, and run the tests again.

Once the configuration meets your requirements, authenticate to the production account and upload the same validated package. See this resource for getting started with the CLI. 

The first-time workflow is:

1. Install the CLI and create a workspace.

2. Authenticate to your developer account.

3. Retrieve the account’s existing catalog.

4. Define custom agreement types and fields in the manifest.

5. Add training documents and upload the configuration.

6. Test extractions against expected values.

7. Update the manifest and retest as needed.

8. Upload the validated configuration to production.

Bulk ingest your existing agreements.

Step 1: Install the CLI and create a workspace

Install the Docusign CLI globally:

npm i -g @docusign/agreement-cli

Confirm the installation succeeded by running the root command:

ds

If the CLI is installed, you will see help output listing the available commands. 

Next, scaffold a workspace for the Agreement Manager configuration:

ds scaffold -w my-docusign-workspace -p my-project -f agreement-manager

This creates a workspace at ./my-docusign-workspace/ with the following structure:

./my-docusign-workspace/
  .env
  my-project/
    agreement-manager/
      configs/
        agreement-manager-manifest.json
      tests/
      files/
        train/
        test/
      README.md

By default, the scaffold command also installs AI tools that let you work with an LLM to drive your Agreement Manager implementation. If you want to skip this, use the --no-ai-skills option.

To check available scaffold options:

ds scaffold --help

Step 2: Connect the CLI to your Docusign account 

Before running Agreement Manager commands, authenticate the CLI against your developer account using OAuth PKCE:

ds auth login                      # demo (default)

The CLI opens a browser-based login page, retrieves an OAuth token, and stores your credentials locally. Authentication remains valid for eight hours.

To switch accounts or environments, run ds auth login again.

To authenticate against production instead of the default developer environment, run:

ds auth login -e production        # production

For now, authenticate to your developer account so you can build and validate the configuration before uploading it to production. 

Step 3: Define and upload the configuration 

Retrieve the current catalog

Before editing the manifest, retrieve the account’s current catalog so you can see which standard and custom agreement types and fields already exist:

ds agm get catalog

Agreement Manager includes a standard catalog with dozens of agreement types and fields that you can extend with your own custom types and fields.

Edit the manifest

Define your customizations in the generated manifest at: {workspace}/{project}/agreement-manager/configs/agreement-manager-manifest.json

The manifest defines:

• Custom fields: New extraction fields with an aiDefinition that tells the model what to extract, along with examples

• Custom agreement types: New agreement categories with an aiDefinition and training documents

• Extensions to standard types: Custom or additional standard fields added to existing agreement types

Place training documents for any custom agreement type with AI extraction enabled in:

{workspace}/{project}/agreement-manager/files/train/

Training documents help configure custom agreement-type extraction. Test agreements are stored separately and are used later to measure accuracy against expected values.

The following example adds a custom Master Services Agreement type, two custom fields, and a Governing Law field to the standard NDA type. Update the namespace, field keys, display names, and document names to match your implementation.

In this example:

• customAgreementTypes defines the new Master Services Agreement category.

• aiDefinition describes what an agreement type or field represents.

• docs points to the training documents associated with the custom agreement type.

• customFields associates custom extraction fields with an agreement type.

• examples provides representative agreement text and the expected extracted value. 

{
  "version": "1.0.0",
  "defaultLocale": "en",
  "namespace": "com.acme.legal@1.0.0",
  "standardAgreementTypes": [
    {
      "key": "NdaDocumentData",
      "displayName": "Non-Disclosure Agreement",
      "fields": {
        "additionalStandardFields": ["ExpirationDate"],
        "customFields": ["Governing Law"]
      }
    }
  ],
  "customAgreementTypes": [
    {
      "key": "C_MasterServicesAgreement",
      "displayName": "Master Services Agreement",
      "description": "Umbrella agreement governing ongoing service engagements",
      "category": "BusinessServices",
      "customExtractionEnabled": true,
      "aiDefinition": "A master services agreement that defines the overarching terms under which individual statements of work or service orders are executed between a service provider and client",
      "fields": {
        "additionalStandardFields": ["ExpirationDate"],
        "customFields": ["Auto-Renewal Clause", "Liability Cap"]
      },
      "docs": ["msa-sample-1.pdf", "msa-sample-2.pdf"]
    }
  ],
  "fields": [
    {
      "key": "C_AutoRenewalClause",
      "displayName": "Auto-Renewal Clause",
      "category": "LifecycleCategory",
      "fieldType": "Boolean",
      "customExtractionEnabled": true,
      "aiDefinition": "Whether the agreement automatically renews for successive terms unless one party provides written notice of termination before the renewal date",
      "examples": {
        "en": [
          {
            "exampleText": "This Agreement shall automatically renew for successive one-year terms unless either party provides 30 days written notice of non-renewal.",
            "confirmedValue": "true"
          },
          {
            "exampleText": "The term of this Agreement shall expire on the End Date with no automatic renewal.",
            "confirmedValue": "false"
          },
          {
            "exampleText": "Unless terminated pursuant to Section 8, this Agreement renews annually on the anniversary date.",
            "confirmedValue": "true"
          }
        ]
      }
    },
    {
      "key": "C_LiabilityCap",
      "displayName": "Liability Cap",
      "category": "FinancialCategory",
      "fieldType": "String",
      "customExtractionEnabled": true,
      "aiDefinition": "The maximum aggregate liability amount or formula that limits one or both parties' total financial exposure under the agreement",
      "examples": {
        "en": [
          {
            "exampleText": "Neither party's aggregate liability shall exceed the total fees paid in the preceding 12 months.",
            "confirmedValue": "Total fees paid in preceding 12 months"
          },
          {
            "exampleText": "Liability is capped at $2,000,000 USD.",
            "confirmedValue": "$2,000,000"
          }
        ]
      }
    },
    {
      "key": "C_GoverningLaw",
      "displayName": "Governing Law",
      "category": "LegalAndComplianceCategory",
      "fieldType": "String",
      "customExtractionEnabled": true,
      "aiDefinition": "The state or jurisdiction whose laws govern the interpretation and enforcement of the agreement",
      "examples": {
        "en": [
          {
            "exampleText": "This Agreement shall be governed by and construed in accordance with the laws of the State of Delaware.",
            "confirmedValue": "Delaware"
          },
          {
            "exampleText": "The governing law for this contract is England and Wales.",
            "confirmedValue": "England and Wales"
          }
        ]
      }
    }
  ]
}

Upload and verify the configuration

After updating the manifest and adding the training documents, upload the package:

ds agm upload

The upload command sends the manifest and training documents to Agreement Manager and starts AI training.

After the upload completes, retrieve the catalog again:

ds agm get catalog

Confirm that the new agreement types, fields, and mappings appear in the account before continuing to the test workflow.

Step 4: Test extractions against expected values

Before uploading the configuration to production, compare the extracted values with a set of values you know to be correct from your own agreements.

The test workflow has four main stages:

1. Ingest or reprocess test agreements

2. Generate a test template from a set of agreements.

3. Enter the expected values in the generated CSV file.

4. Run the test and review the results.

Add test agreements

Place up to 400 real agreements in:

{workspace}/{project}/agreement-manager/files/test/

Supported file formats include PDF, DOC/DOCX, RTF, XLS/XLSX, PPT/PPTX, HTML, and common image formats.

Ingest or reprocess test agreements

Setup the test by running the setup command to ingest new test agreements or reprocess existing ones:

ds agm test --setup

If all of your test agreements in the /test folder are new and have not been uploaded to Agreement Mmanager yet, this command will ingest all of those agreements. If a subset of your test agreements in the /test folder are already ingested, this command will reprocess those agreements so that you get up-to-date AI extracted values. 

Generate the test template

Generate the testing template:

ds agm test --generate-test-template

The command uploads the test agreements to Agreement Manager for extraction and generates a testing.csv file.

Each row in the CSV corresponds to one test agreement. Each column represents a field.

To prepopulate the CSV with the AI’s current extracted values, add the --prefill-extractions option:

ds agm test --generate-test-template --prefill-extractions

Important: Review every prefilled value before running the test. If a prefilled value is left unchanged, the test compares the extracted value with that same value and reports 100% accuracy for the cell. 

Enter the expected values 

Open testing.csv and enter the correct values for each relevant field in each agreement. You do not need to fill in every cell. Blank cells are skipped during the test run.

These expected values act as the ground truth against which the CLI compares the AI-extracted values.

Run the test

Run the extraction test: 

ds agm test --run

The CLI displays a field-level accuracy summary and generates two result files in the tests directory:

• field-test-results.csv: Per-field accuracy for each test agreement

• agreement-type-test-results.csv: Per-agreement accuracy for agreement-type classification

Review the field-level results to identify which custom definitions, examples, or training documents may need improvement.

Refine the configuration and retest

If accuracy falls below your target, update the configuration and rerun the same test cycle.

For custom fields:

• Improve the aiDefinition.

• Add more training examples. Three to five examples are recommended.

For custom agreement types:

• Add more diverse training documents. Five to 10 documents are recommended.

Improving extraction accuracy for standard fields is not supported.

Upload the updated package before running the test again:

ds agm upload
ds agm test --run

Continue refining and retesting until the results meet your requirements. 

Here’s what a test run looks like in the CLI, including the field-level accuracy summary you’ll see after ds agm test --run completes:

Step 5: Upload the validated configuration to production

Once the configuration meets your accuracy requirements in the developer account, authenticate to production: 

ds auth login -e production
ds agm upload

The same configuration you tested in the developer account is now uploaded to production. 

Reuse the configuration across accounts 

If you are a system integrator deploying an existing configuration to multiple customer accounts, use catalog-to-manifest to export the configuration from one account into a portable manifest: 

ds agm catalog-to-manifest --all

Copy the exported manifest and training files into your workspace, authenticate to the target account, and upload the package.

You can reuse the configuration without rebuilding it. Depending on the agreements in the target account, you may still want to rerun the extraction tests before production use. 

Step 6: Bulk ingest agreements

After configuring and deploying Agreement Manager, ingest your existing agreement corpus: 

ds agm ingest --<directory path>

The ingest command scans the specified directory, detects and skips duplicates, and uploads new files to Agreement Manager.

It supports local directories and network drives accessible through a file path. After the run completes, the CLI displays a summary that includes:

• Total files scanned

• Duplicate files skipped

• New files uploaded

• Final job status

Ingest agreements with metadata

To provide known field values alongside the agreements, first generate a metadata template:

ds agm ingest --directory <directory path> --generate-metadata-template

Populate the generated CSV, then run the ingest command with metadata:

ds agm ingest --directory <directory path> --with-metadata

Optional: Run extraction tests as a repeatable job

The CLI commands are scriptable, so you can use them in a recurring test job or a partially automated CI workflow. However, the current OAuth flow still requires a user to authenticate. Fully unattended CI without a human sign-in step is not yet supported.

A typical repeatable test workflow is:

1. Authenticate to the developer environment or use a stored token.

2. Upload the current manifest version.

3. Run ds agm test --generate-test-template to upload the test agreements and generate the CSV.

4. Populate the CSV with expected values, or use a ground-truth file already stored in the repository.

5. Run ds agm test --run.

6. Parse the output CSV files and compare the field-level results with your accuracy threshold.

7. Fail the job if accuracy falls below the threshold.

For headless environments such as SSH sessions or containers, authenticate with:

ds auth login --no-browser

The CLI prints a login URL that you can open on another device. After signing in, paste the redirected URL back into the CLI so it can exchange the authorization code for a token.

This supports test runs from a headless environment after a user authenticates, but it does not remove the human login step.

Optional: Let a coding agent work with the CLI

The Docusign CLI installs AI tools by default when you scaffold a workspace.

The workspace includes an agent skill definition in SKILL.md format. This file gives an LLM the context it needs to help with the Agreement Manager workflow through natural-language prompts.

A coding agent such as Claude Code or Gemini CLI can use the skill definition to help:

• Scaffold the workspace

• Configure the manifest

• Run extraction tests

• Upload the configuration

• Generate and validate manifests programmatically

To scaffold a workspace without the AI tools, use the --no-ai-skills option.

FAQ

Can the Docusign CLI run in a fully automated CI pipeline?

The upload and testing commands are scriptable, but authentication currently requires a user to complete the OAuth flow. For a headless environment, use ds auth login --no-browser and complete sign-in from another device. Fully unattended CI without a human authentication step is not yet supported.

Can I reuse a validated configuration across multiple customer accounts?

Yes. Use:

ds agm catalog-to-manifest --all

This exports an existing account configuration as a portable manifest. Copy the exported manifest and training files into your workspace, authenticate to the target account, and upload the package.

Depending on the agreements in the target account, you may still want to rerun the extraction tests before production use.

Which extraction results can I improve through the manifest?

You can improve extraction accuracy for custom fields and custom agreement types where customExtractionEnabled is set to true.

For custom fields, improve the aiDefinition and add more representative examples. For custom agreement types, add more diverse training documents.

Standard field extraction accuracy cannot be configured through the CLI.

What should I do if extraction accuracy is still low?

Add more representative training examples, improve the aiDefinition descriptions, and make sure the training documents resemble the agreements you expect to process in production.

Three to five examples are recommended for each custom field, and five to 10 training documents are recommended for each custom agreement type.

After each change, upload the revised package and rerun the same test set so you can compare the results.

What if I want to make a change to a configuration that I already uploaded?

You can make several updates to a configuration that you have already uploaded via the CLI. 

For custom agreement types, you can update an existing custom types’ description, category, aiDefinition, docs, customExtractionEnabled and add or remove mapped standard and custom fields. 

For custom fields, you can update an existing custom fields’ description, category, aiDefinition, customExtractionEnabled and AI examples. 

For standard agreement types, you can add or remove mapped additional standard fields and custom fields. 

Next steps and resources

You now have an Agreement Manager configuration that can be reviewed in source control, tested against your own agreements, and reused across accounts. As you update custom agreement types, fields, or training documents, rerun the same test set before uploading the configuration to production. 

• Join the Docusign CLI Open Beta

• Docusign CLI overview

• Get started with the CLI

• Review common use cases

• Explore the manifest reference

• Agreement Manager API documentation

• Get a free Docusign developer account

• Ask questions or get feedback in the Docusign Developer Community

Acknowledgments

Special thanks to Harsha Rahul Boggaram, Andrey Novichkov, and Sebastian Gwozdz for their contributions to the Docusign CLI’s development.