# 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](/sdk/compatibility#nodejs) (`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.

```bash group="install" tab="npm (global)"
npm install -g @dcupl/cli
```

```bash group="install" tab="npx (no install)"
npx @dcupl/cli <command>
# e.g. npx @dcupl/cli version
```

## Verify

Confirm the install and inspect the resolved package versions:

```bash
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.

> **Note:** Credentials aren't needed to install or scaffold a project. You configure them later with `dcupl config set` — see [Cloud Sync](/cli/cloud-sync).

## 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](#node-version-too-old).
- **Bundled SDK:** the CLI now runs `@dcupl/core` 2.1 (1.3 ran 1.8). The [migration guide](/sdk/guides/migration) 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`](/cli/commands#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](/cli/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`.

```bash
# 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:

```bash
npx @dcupl/cli version
```

### Node version too old

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

```text title="dcupl on an older Node.js"
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:

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

## Next steps

- [Quickstart](/cli) — Build your first project end to end
- [How the CLI works](/cli/how-it-works) — How the CLI bridges your workspace, daemon, and the cloud