Node-RED Admin CLI
raw JSON → 4.1.5 verified Sat Apr 25 auth: no javascript
The `node-red-admin` package provides a command-line interface for remote administration of Node-RED instances. It enables users to perform various management tasks such as listing, enabling, disabling, installing, and removing Node-RED nodes, setting target Node-RED instances, authenticating users, and generating hashed passwords for `adminAuth` configuration. The current stable version is 4.1.5, with frequent patch and minor releases, and major versions typically update Node.js compatibility and introduce core changes. It can be installed globally as a standalone tool or is bundled and available when `node-red` itself is installed. Its primary differentiator is offering a robust, scriptable interface for managing Node-RED environments without needing direct access to the Node-RED editor UI, making it invaluable for automation and deployment workflows.
Common errors
error EACCES: permission denied, mkdir '/usr/local/lib/node_modules/node-red-admin' ↓
cause Insufficient permissions to write to the global npm packages directory.
fix
Run
npm install -g node-red-admin with elevated privileges using sudo (e.g., sudo npm install -g node-red-admin) or configure npm to use a user-owned directory. error node-red-admin: command not found ↓
cause The `node-red-admin` executable is not in your system's PATH, or the global npm installation directory is not properly configured.
fix
Ensure
npm install -g node-red-admin completed successfully. Verify that your npm global binaries directory is included in your system's PATH environment variable (e.g., ~/.npm-global/bin or /usr/local/bin). error Error: Node.js vXX.YY.Z is not supported. Node.js >=18 is required. ↓
cause Attempting to run `node-red-admin` with an incompatible Node.js version, as the package requires Node.js 18 or newer.
fix
Update your Node.js runtime to version 18 or higher. Consider using a Node.js version manager like
nvm (nvm install 18 && nvm use 18) or fnm. error Failed to connect to Node-RED admin API at http://localhost:1880/auth/login : connect ECONNREFUSED 127.0.0.1:1880 ↓
cause The Node-RED instance is not running or is not accessible at the specified target URL and port.
fix
Ensure your Node-RED instance is running. Verify that
node-red-admin target <your-node-red-url> is correctly set and that there are no firewall or network issues blocking access to the Node-RED admin API port. Warnings
breaking Node-RED Admin CLI requires Node.js version 18 or higher. Version 3.0.0 dropped support for Node.js 12, and later versions incrementally increased the minimum requirement. Ensure your Node.js environment meets this prerequisite before upgrading or installing. ↓
fix Upgrade your Node.js installation to version 18 or newer. Use `nvm` or `fnm` for managing multiple Node.js versions: `nvm install 18 && nvm use 18`.
gotcha When installing `node-red-admin` globally using `npm install -g`, users may encounter 'EACCES: permission denied' errors on Unix-like systems due to insufficient permissions. This is a common npm permission issue. ↓
fix Use `sudo npm install -g node-red-admin` (for macOS/Linux) or `npm install -g node-red-admin --unsafe-perm` if `sudo` is not desired or causes issues. Alternatively, configure npm to install packages in a user-owned directory.
breaking The 3.0.0 release of `node-red-admin` introduced changes to accommodate Node-RED V3, specifically regarding `httpStatic` and the addition of `httpStaticRoot`. Deployments relying on older configurations or specific `httpStatic` settings may require review. ↓
fix Review Node-RED V3 migration guides for any `httpStatic` or related configuration changes. Ensure your Node-RED instance is compatible with the version administered by `node-red-admin`.
security The `node-red-admin` package frequently updates its internal dependencies, particularly `axios`, to address critical security vulnerabilities (e.g., GHSA-43fc-jf86-j433 fixed in 4.1.3). Running outdated versions can expose your system to known exploits. ↓
fix Regularly update `node-red-admin` to the latest stable version to ensure all security patches are applied: `npm install -g node-red-admin@latest`.
gotcha The CLI tool stores its configuration in `~/.node-red/.cli-config.json` by default. If you need to manage different Node-RED environments or require a portable configuration, this default location may not be suitable. ↓
fix Use the `--userDir DIR` argument with any `node-red-admin` command to specify an alternative directory for the configuration file, allowing for isolated or custom configurations.
Install
npm install node-red-admin yarn add node-red-admin pnpm add node-red-admin Quickstart
/*
The node-red-admin tool is used via shell commands. Below are examples of how to install and use it.
These commands should be executed in your terminal.
*/
// Install node-red-admin globally using npm:
console.log('npm install -g node-red-admin');
// Get general help for the command-line tool:
console.log('node-red-admin --help');
// Set the target Node-RED instance (replace with your Node-RED server URL):
console.log('node-red-admin target http://localhost:1880');
// Log in to the target Node-RED instance (you will be prompted for credentials):
console.log('node-red-admin login');
// List all installed nodes on the targeted Node-RED instance:
console.log('node-red-admin list');
// Generate a hashed password for use in Node-RED's adminAuth settings:
console.log('node-red-admin hash-pw "your_secure_password_here"');
// Install a new Node-RED module from npm:
console.log('node-red-admin install node-red-contrib-example');
// List nodes and output in JSON format for scripting:
console.log('node-red-admin list --json');