{"id":17599,"library":"etherpad-cli-client","title":"Etherpad CLI Client","description":"The `etherpad-cli-client` package provides a Node.js and CLI interface for real-time interaction with Etherpad content. It allows developers to connect to an Etherpad instance, stream pad text, listen for real-time messages, and programmatically append or prefix content. The current stable version is 3.0.5. A critical design decision is that this client *requires* the connected Etherpad server to be running in `loadTest` mode, which fundamentally alters Etherpad's behavior and is not suitable for typical production environments. This limits its use to specific testing, automation, or specialized integration scenarios rather than full-fledged editor functionality. The project appears actively maintained, with continuous integration badges indicating ongoing development. Its core differentiator is its programmatic access to real-time Etherpad content, albeit under the `loadTest` mode constraint.","status":"active","version":"3.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/johnmclear/etherpad-cli-client","tags":["javascript"],"install":[{"cmd":"npm install etherpad-cli-client","lang":"bash","label":"npm"},{"cmd":"yarn add etherpad-cli-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add etherpad-cli-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package's default export is the `Client` class. Use CommonJS `require` for direct import. While Node.js ESM interop might allow `import Client from 'etherpad-cli-client'` in a module context, `require` is the explicit and most reliable method as it's a CJS module.","wrong":"import Client from 'etherpad-cli-client';","symbol":"Client","correct":"const Client = require('etherpad-cli-client');"},{"note":"`connect` is a static method of the `Client` class, not a direct named export. You must access it via the imported `Client` object after importing the class itself.","wrong":"const { connect } = require('etherpad-cli-client');","symbol":"connect","correct":"const Client = require('etherpad-cli-client');\nconst pad = Client.connect('https://beta.etherpad.org/p/clitest');"},{"note":"While technically possible for the `connect` method, directly chaining `require().connect()` can obscure the fact that `Client` is a class and methods like `on`, `append`, etc., are instance methods of the object returned by `Client.connect()`.","wrong":"const pad = require('etherpad-cli-client').connect();","symbol":"pad instance methods","correct":"const Client = require('etherpad-cli-client');\nconst pad = Client.connect();\npad.on('connected', () => { /* ... */ });\npad.append('new content');"}],"quickstart":{"code":"const Client = require(\"etherpad-cli-client\");\n\n// IMPORTANT: Ensure your Etherpad instance is in loadTest mode (settings.json -> loadTest: true).\n// This example connects to a public beta instance that may or may not be in loadTest mode.\nconst pad = Client.connect(\"https://beta.etherpad.org/p/clitest\");\n\npad.on(\"connected\", function(padState){\n  console.log(`Connected to Etherpad at ${padState.host} with pad ID ${padState.padId}`);\n  // Start appending content once connected\n  let counter = 0;\n  const intervalId = setInterval(() => {\n    const textToAppend = `Hello from CLI Client! [${Date.now()}]\\n`;\n    console.log(`Appending: \"${textToAppend.trim()}\"`);\n    pad.append(textToAppend);\n    counter++;\n    if (counter >= 3) { // Append a few times then stop\n      clearInterval(intervalId);\n    }\n  }, 2000);\n});\n\npad.on(\"message\", function(message){\n  console.log(\"New message from Etherpad Server:\", message.type);\n  // You can inspect message.data for specific Etherpad protocol details\n});\n\npad.on(\"newContents\", function(atext){\n  console.log(\"\\n--- Pad Contents Updated ---\");\n  console.log(atext.text);\n  console.log(\"----------------------------\\n\");\n});\n\npad.on(\"disconnect\", function(e){\n  console.log(\"Disconnected from pad:\", e ? e.message : \"gracefully\");\n  process.exit(0);\n});\n\n// Keep the process alive for a reasonable duration to observe real-time events\nsetTimeout(() => {\n  console.log(\"Exiting after 30 seconds to prevent indefinite running.\");\n  process.exit(0);\n}, 30000);","lang":"javascript","description":"Demonstrates connecting to an Etherpad instance, listening for connection status, real-time messages, and updates to the pad's content, while also programmatically appending text. Requires the Etherpad server to be in `loadTest` mode for full functionality."},"warnings":[{"fix":"Modify your Etherpad server's `settings.json` to include `\"loadTest\": true` and restart the Etherpad server.","message":"This client requires the connected Etherpad server to be in `loadTest` mode. This is a non-standard configuration and will likely break normal Etherpad operations or prevent other clients from connecting correctly. Ensure `loadTest: true` is set in your Etherpad `settings.json`.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Upgrade your Node.js environment to version 18.0.0 or later. Use a version manager like `nvm` to easily switch Node.js versions (e.g., `nvm install 18 && nvm use 18`).","message":"The package explicitly requires Node.js version 18.0.0 or higher. Running on older Node.js versions may lead to unexpected errors or failures.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Understand the scope of this client. If you need full editor capabilities, consider alternative Etherpad API clients or direct browser-based interaction.","message":"The client offers limited functionality, primarily focusing on streaming, appending, and listening to pad content. It does not provide full editor feature parity, such as complex text manipulation, undo/redo, or user management that a standard Etherpad client offers.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Prefer `const Client = require('etherpad-cli-client');` for importing the module in CommonJS environments. If using in an ESM project, use `import Client from 'etherpad-cli-client';` leveraging Node.js's CJS-ESM interop, but be aware of potential quirks.","message":"This package is distributed as a CommonJS module. While Node.js 18+ supports ESM, direct `import` statements might require specific configuration (`type: \"module\"` in `package.json` or dynamic `import()`) or may not behave as expected without proper interop handling.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Edit your Etherpad server's `settings.json` file, add or set `\"loadTest\": true`, and restart the Etherpad server.","cause":"The Etherpad server you are trying to connect to is not configured with `loadTest: true` in its `settings.json`.","error":"Error: Client side Etherpad installation needs to be in loadTest mode (settings.json)"},{"fix":"Ensure you import the `Client` class correctly using `const Client = require('etherpad-cli-client');` and then call its static method: `Client.connect(url);`.","cause":"You are attempting to destructure `connect` directly from the module or calling it incorrectly, rather than as a static method of the imported `Client` class.","error":"TypeError: Client.connect is not a function"},{"fix":"If your project is configured with `\"type\": \"module\"` in `package.json`, use `import Client from 'etherpad-cli-client';` for CJS interoperability. Alternatively, switch your project to CommonJS by removing `\"type\": \"module\"`.","cause":"This error occurs in an ECMAScript Module (ESM) context when you try to use `require()` directly.","error":"ReferenceError: require is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}