{"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,"search_vec":"'3.0.5':53 'access':124 'activ':109 'albeit':131 'allow':25 'alter':75 'appear':108 'append':44 'autom':94 'badg':114 'behavior':78 'cli':2,7,14 'client':3,8,61 'connect':28,64 'constraint':136 'content':23,47,130 'continu':112 'core':119 'critic':55 'current':49 'decis':57 'design':56 'develop':26,117 'differenti':120 'editor':104 'environ':86 'etherpad':1,6,22,31,65,76,129 'etherpad-cli-cli':5 'fledg':103 'full':102 'full-fledg':101 'function':105 'fundament':74 'indic':115 'instanc':32 'integr':97,113 'interact':20 'interfac':15 'javascript':137 'limit':88 'listen':36 'loadtest':71,134 'maintain':110 'messag':41 'mode':72,135 'node.js':12 'ongo':116 'packag':9 'pad':34 'prefix':46 'product':85 'programmat':43,123 'project':107 'provid':10 'rather':99 'real':18,39,127 'real-tim':17,38,126 'requir':62 'run':69 'scenario':98 'server':66 'special':96 'specif':92 'stabl':50 'stream':33 'suitabl':82 'test':93 'text':35 'time':19,40,128 'typic':84 'use':90 'version':51","created_at":"2026-04-23T17:47:07.701722+00:00","updated_at":"2026-04-23T17:47:07.701722+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"etherpad-cli-client","cli_version":null,"type":"library","homepage":"https://etherpad.org","github":"https://github.com/johnmclear/etherpad-cli-client","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/etherpad-cli-client","openapi_spec":null,"status_page":null,"smithery":null,"categories":["communication"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-22","install_tag":null}}