{"id":18047,"library":"node-red-admin","title":"Node-RED Admin CLI","description":"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.","status":"active","version":"4.1.5","language":"javascript","source_language":"en","source_url":"https://github.com/node-red/node-red-admin","tags":["javascript"],"install":[{"cmd":"npm install node-red-admin","lang":"bash","label":"npm"},{"cmd":"yarn add node-red-admin","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-red-admin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime environment requirement for the CLI tool.","package":"node","optional":false}],"imports":[],"quickstart":{"code":"/*\n  The node-red-admin tool is used via shell commands. Below are examples of how to install and use it.\n  These commands should be executed in your terminal.\n*/\n\n// Install node-red-admin globally using npm:\nconsole.log('npm install -g node-red-admin');\n\n// Get general help for the command-line tool:\nconsole.log('node-red-admin --help');\n\n// Set the target Node-RED instance (replace with your Node-RED server URL):\nconsole.log('node-red-admin target http://localhost:1880');\n\n// Log in to the target Node-RED instance (you will be prompted for credentials):\nconsole.log('node-red-admin login');\n\n// List all installed nodes on the targeted Node-RED instance:\nconsole.log('node-red-admin list');\n\n// Generate a hashed password for use in Node-RED's adminAuth settings:\nconsole.log('node-red-admin hash-pw \"your_secure_password_here\"');\n\n// Install a new Node-RED module from npm:\nconsole.log('node-red-admin install node-red-contrib-example');\n\n// List nodes and output in JSON format for scripting:\nconsole.log('node-red-admin list --json');","lang":"javascript","description":"Demonstrates global installation and common command-line usages of the Node-RED Admin CLI, including setting targets, logging in, listing nodes, and hashing passwords."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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`.","message":"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.","severity":"security","affected_versions":"<4.1.3"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"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.","cause":"Insufficient permissions to write to the global npm packages directory.","error":"EACCES: permission denied, mkdir '/usr/local/lib/node_modules/node-red-admin'"},{"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`).","cause":"The `node-red-admin` executable is not in your system's PATH, or the global npm installation directory is not properly configured.","error":"node-red-admin: command not found"},{"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`.","cause":"Attempting to run `node-red-admin` with an incompatible Node.js version, as the package requires Node.js 18 or newer.","error":"Error: Node.js vXX.YY.Z is not supported. Node.js >=18 is required."},{"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.","cause":"The Node-RED instance is not running or is not accessible at the specified target URL and port.","error":"Failed to connect to Node-RED admin API at http://localhost:1880/auth/login : connect ECONNREFUSED 127.0.0.1:1880"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}