Skip to content
WebsiteDocumentationDashboard ↗LibertyJS repo ↗npm package ↗GitHub organization ↗

LibertyTools / Docs

Run your own command bot

Reply to ;help, ;rules, and ;discord using LibertyJS and per-player cooldowns.

← All examples

Download project ZIP

What it does

Run your own ;help, ;rules, and ;discord commands using LibertyJS. Each sends a short private reply to the player. Edit the fixed messages in bot.mjs for your server.

What you need

  • Node.js 22 or newer.
  • An ERLC private server with API/webhook access and its server key.
  • A LibertyTools connection with its webhook URL configured in ERLC.
  • A separate Poll client in Outputs → Poll clients. Select CustomCommand events and include help, rules, and discord.
  • Any server-owner/public-app/IP authorization ERLC requires for your self-hosted bot. Dashboard authorization for hosted commands does not automatically authorize every other hosting location.

Do not share your server key or Poll token. Disable hosted rules for the same command while testing this bot so both handlers do not reply.

Setup

  1. Download and extract the project ZIP.
  2. Open a terminal in the extracted custom-commands folder.
  3. Copy .env.example to .env and fill it in using a text editor. Keep it out of Git; check it is not .env.txt.
  4. Install the SDK and start:
npm install
npm start

Keep the terminal open. Ctrl+C stops the bot.

Test it

Run ;help in your server. Expect one private reply. Try ;rules and ;discord too. The default Discord reply asks players to contact staff; edit it if appropriate.

Limits and behavior

Each command has a 15-second per-player cooldown. The SDK handles Poll and acknowledgements. Synthetic events and missing player IDs do not produce replies. Use private replies for short command information, not as a replacement for Roblox chat.

Rejected or uncertain reply results are logged without throwing to trigger a blind resend. A request might have succeeded even if its response was lost. Restarting loses the SDK's in-memory duplicate/cooldown history. Add durable deduplication for important actions.

Results appear in the bot's terminal. The dashboard's Recent command runs shows hosted commands, not every command sent by your SDK process.

Common problems

  • SDK missing: run npm install from the folder containing package.json.
  • No event: check Events, webhook setup, and Poll filters/token.
  • Event but no reply: check server key, ERLC authorization, player presence, cooldown, and terminal warnings.
  • Stops when the terminal closes: keep it on your host or use hosted commands.

See the Poll guide and LibertyJS reference.

View bot.mjs
import { pathToFileURL } from 'node:url';
export function registerCommands(erlc) {
  const messages = {
    help: 'Need help? Ask a staff member or run ;rules.',
    rules: 'Respect other players, follow staff instructions, and keep roleplay friendly.',
    discord: 'Ask a staff member for the server Discord link.'
  };
  for (const [name, message] of Object.entries(messages)) {
    erlc.commands.command(name, async context => {
      if (context.event.raw?.synthetic || !/^[1-9][0-9]{0,19}$/.test(context.userId)) return;
      const result = await context.reply(message);
      if ('error' in result || result.failures > 0) {
        // The send may have reached ERLC. Do not throw and blindly repeat it.
        console.error('Reply was not confirmed. Check the bot logs and ERLC permissions before retrying.');
      }
    }, { cooldown: 15000 });
  }
}
export async function main(env = process.env) {
  for (const name of ['ERLC_SERVER_KEY', 'POLL_SUBSCRIPTION_ID', 'POLL_TOKEN']) {
    if (!env[name]?.trim()) throw new Error(`Missing ${name}. Fill in .env first.`);
  }
  const { default: LibertyJS } = await import('@libertytools/libertyjs');
  const erlc = new LibertyJS({ SERVER_KEY: env.ERLC_SERVER_KEY, POLL_SUBSCRIPTION_ID: env.POLL_SUBSCRIPTION_ID, POLL_TOKEN: env.POLL_TOKEN });
  registerCommands(erlc);
  erlc.commands.on('pollError', () => console.error('Poll failed. Check credentials and the connection status.'));
  erlc.commands.on('commandError', () => console.error('A command failed. Check ERLC permissions before trying again.'));
  process.once('SIGINT', () => { void erlc.commands.stop(); });
  process.once('SIGTERM', () => { void erlc.commands.stop(); });
  console.log('Listening for ;help, ;rules, and ;discord. Keep this terminal open.');
  await erlc.commands.start();
}
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main().catch(() => {
  console.error('Command bot stopped. Check .env and that LibertyJS is installed.'); process.exitCode = 1;
});