Get started with the Docusign CLI | Docusign

The Docusign CLI provides a command-line interface for implementing Docusign Agreement Manager programmatically. This page covers the prerequisites for using the CLI, how to install it, how to check and update your installed version, and how to set up a workspace for your first project.

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

Prerequisites

Before installing the CLI, make sure that you have met the following prerequisites:

Created a developer account
Installed Node.js and npm
Access to a code editor

See the next sections for details.

Docusign account

You need at least one Docusign account with Agreement Manager admin permissions, which all developer accounts have by default. You can fill out a form to create a free developer account. Agreement Manager availability in production depends on your account plan.

Start with a developer account before working in production.

Node.js and npm

The CLI requires Node.js and npm to be installed on your machine. Install them using the appropriate method for your operating system:

OS	Method	Instructions
macOS	Official installer	Download the long-term support (LTS) version from nodejs.org and run the installer.
	Homebrew	Install Homebrew if needed. Then run `brew install node`
Windows	Official installer	Download the LTS version from nodejs.org and run the installer.
Linux	Package manager	Follow the instructions at nodejs.org.

Verify installation

Run these commands to verify the Node.js and npm installation:

node --version
npm --version

Both commands should return a version number. If either command is not recognized, restart your terminal and try again.

Code editor

You need a code editor to create and modify Docusign CLI package files. Docusign recommends using Visual Studio Code.

Download links:

Install or update the CLI

See the instructions below for a first-time CLI installation or a version upgrade.

First-time installation

Install the Docusign CLI globally using npm:

npm i -g @docusign/cli

If you are not an administrator on your machine, use this command instead:

sudo npm i -g @docusign/cli

After installation, confirm that the CLI is installed and accessible by running the root command:

ds

If the installation succeeded, the CLI help output is displayed, listing all available commands. If the output is not displayed immediately, restart the console and run the ds command again.

Update to a new version

To check the version of the CLI currently installed on your machine, run:

ds --version

The CLI will notify you if a newer version is available. To update to the latest version, run:

ds update

Keeping the CLI up to date ensures that you have the latest features, bug fixes, and improvements.

If your currently installed version of the CLI package has been deprecated, you will be notified when you run ds update. To switch your installation to the new CLI package, run:

install npm i -g @docusign/cli

This will unlink the previous installation and target all ds commands to the new binary. Any existing catalogs, manifests, training and testing documents in your local workspace will not be affected.

Set up your workspace

Before using the Docusign CLI features, set up a structured workspace using the docusign scaffold command. The workspace is a directory structure that organizes your Agreement Manager configurations, training files, test files, and results. The scaffold command creates the workspace directory at the location from which you run the command.

Note: By default, the scaffold command installs Docusign CLI AI tools, which enable you to work with an LLM on your Agreement Manager implementation. You can opt out of this with the --no-ai-skills command option.

Command usage

ds scaffold [options]

The following options are available:

Option	Description	Default value
`-w --workspace <name>`	The name of the root directory for your project files.	`docusign-workspace`
`-p --project <name>`	The name of the specific project within the workspace.	Auto-increments (for example, `project-1`)
`-f --features <features>`	A comma-separated list of subdirectories to create under the project, used to group related configurations and assets.	`agreement-manager`
`--dry-run`	Shows the directory structure that would be created without actually creating it.	N/A
`-h --help`	Displays help for the command.	N/A
`--no-ai-skills`	Creates a workspace without adding AI skills. See AI tools for more information.	N/A

Example

The following command creates a workspace named my-docusign-workspace, a project named fontara, and a feature directory for Agreement Manager:

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

Workspace structure

Based on the example scaffold command, the CLI would create this directory structure:

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

The directories and files in this structure serve the following purposes:

Directory/file	Description
`my-docusign-workspace/`	Top-level workspace directory, containing all projects.
`.env`	Environment file for setting local variables such as API keys and environment URLs specific to this workspace.
`fontara/`	Project directory.
`fontara/README.md`	General description and instructions for the project.
`fontara/agreement-manager/`	Feature directory for grouping related Agreement Manager configurations and assets.
`configs/`	Directory for storing configuration files, including the JSON manifest.
`tests/`	Directory for storing expected test data in a CSV file.
`files/`	Directory containing agreements used for testing extraction accuracy and training custom agreement types.
`files/train/`	Place training agreements here for custom agreement types with AI extraction enabled.
`files/test/`	Place test agreements here for validating AI extraction accuracy.

Command prefixes

The Docusign CLI supports the following command prefixes:

docusign agreement-manager
docusign agm
ds agreement-manager
ds agm

The convention in this documentation is to use the command prefix short form, ds agm, for syntax and examples, but any of the above variations will work as well.

Frequently asked questions

Can I have multiple projects in the same workspace?

Yes. The scaffold command supports multiple projects in the same workspace. If you do not specify a project name with the -p option, the CLI auto-increments the project name (for example, project-1). You can also run the scaffold command multiple times in the same workspace directory to add new projects.

Can I preview the workspace structure before creating it?

The --dry-run option shows the directory structure that the scaffold command would create, without actually creating files or directories. Use it to preview the workspace layout before committing to a directory name or structure.

How do I know if a newer version of the CLI is available?

If a newer version is available, the CLI displays this information after it finishes executing any command. You can also check your installed version at any time by running ds --version. To update to the latest version, run docusign update.

Do I need a separate workspace for the developer and production environments?

No. A single workspace can be used for both the developer and production environments. Authentication is handled separately at the CLI level using the ds auth login command, which lets you specify the target environment. The workspace directory structure remains the same regardless of which environment you are connected to.

Next steps

Authenticate the CLI with your Docusign account.
Explore common CLI use cases.
Implement custom configurations easily with our AI tools.