Installation

Install the dcupl CLI once and run it from any directory, or invoke it on demand with npx. This page covers both approaches, the Node.js requirement, and how to confirm everything works.

Prerequisites

• A supported Node.js version, see Compatibility (node -v to check)
• A package manager (npm or pnpm)

Install

Install globally to make the dcupl binary available everywhere, or use npx to run the CLI without installing it. Both get the current stable release, CLI 2.0, which these docs describe. The package is published on npm under the ISC license.

npm install -g @dcupl/cli

npx @dcupl/cli <command>
# e.g. npx @dcupl/cli version

Verify

Confirm the install and inspect the resolved package versions:

dcupl version

dcupl version prints the CLI version (2.0.x) along with the resolved @dcupl/* package versions it bundles (@dcupl/core, @dcupl/common, @dcupl/common-internal, and @dcupl/loader), plus an update notice when npm has a newer CLI version. This is the quickest way to confirm the binary is on your PATH and to check exactly which engine versions you are running.

Upgrading from 1.3

CLI 2.0 is the next stable release after 1.3.2. Update with the same command you installed with, for example npm install -g @dcupl/cli. Check these points before you upgrade scripts or CI jobs:

• Node.js: 2.0 needs Node.js 20.19+ or 22.12+ (1.3 declared no Node.js requirement). See Node version too old.
• Bundled SDK: the CLI now runs @dcupl/core 2.1 (1.3 ran 1.8). The migration guide lists what changed in the SDK.
• dcupl test is removed. It did nothing. dcupl generate test, test-setup and test-config still scaffold their files.
• dcupl serve listens on 127.0.0.1 only. Pass --host to let other machines or containers connect, see serve. Editing files through it needs the token it prints at startup, except from the dcupl Console or an --allow-origin origin on this machine. It no longer reads skipWelcomeScreen from dcupl.config.json; set "openBrowser": false instead.
• files:push, files:pull, files:copy and files:versions are deprecated. Use dcupl files push, dcupl files pull, dcupl files versions copy and dcupl files versions list, see Cloud Sync. The old commands still work, but files:copy now needs --from and --to.
• Unknown flags and commands fail with exit code 1 instead of being ignored.
• dcupl --version prints @dcupl/cli <version> and the bundled @dcupl/* versions. Use dcupl --version --json in scripts.
• dcupl generate json-schema types float properties as number (1.3 used integer, which rejects decimals).

New since 1.3: dcupl app, dcupl workflow, dcupl config, dcupl files status and list, dcupl schemas, dcupl validate, dcupl version, dcupl serve list and stop, and dcupl generate workflow and api.

Troubleshooting

dcupl: command not found

After a global install, your shell may not find the binary because npm's global bin directory isn't on your PATH.

# Show where global packages are installed
npm config get prefix
# Ensure <prefix>/bin is on your PATH, then restart your shell

As a workaround, run the CLI without installing:

npx @dcupl/cli version

Node version too old

The CLI requires a supported Node.js version. On an older version the install still succeeds (npm prints at most EBADENGINE warnings for some dependencies), but every command then fails on startup:

Error [ERR_REQUIRE_ESM]: require() of ES Module …/node_modules/yargs/helpers/helpers.mjs from …/dist/index.js not supported.

Check your version and upgrade if needed:

node -v
# If below 20.19 (or a 22.x below 22.12), install a newer Node.js (e.g. via nvm or fnm)