librechat-balances/LibreChat-Balance-Commands.md

LibreChat Balance Management Commands

All commands run from /opt/LibreChat on the dev server.

---

View Balances

List all user balances

docker compose exec api npm run list-balances

Check a specific user's balance

docker compose exec mongodb mongosh --eval '
  const user = db.getSiblingDB("LibreChat").getCollection("users").findOne({ email: "USER_EMAIL" });
  if (user) {
    const balance = db.getSiblingDB("LibreChat").getCollection("balances").findOne({ user: user._id });
    print(JSON.stringify(balance, null, 2));
  } else {
    print("User not found");
  }
'

---

Add Tokens

Add tokens to a specific user (increments existing balance)

docker compose exec mongodb mongosh --eval '
  const user = db.getSiblingDB("LibreChat").getCollection("users").findOne({ email: "USER_EMAIL" });
  if (user) {
    db.getSiblingDB("LibreChat").getCollection("balances").updateOne(
      { user: user._id },
      { $inc: { tokenCredits: AMOUNT } },
      { upsert: true }
    );
    print("Added AMOUNT tokens for " + user.email);
  } else {
    print("User not found");
  }
'

Add tokens to ALL users

docker compose exec mongodb mongosh --eval '
  const result = db.getSiblingDB("LibreChat").getCollection("balances").updateMany(
    {},
    { $inc: { tokenCredits: AMOUNT } }
  );
  print("Updated " + result.modifiedCount + " users");
'

Create balances for all users who don't have one yet

docker compose exec mongodb mongosh --eval '
  const users = db.getSiblingDB("LibreChat").getCollection("users").find({}, {_id: 1, email: 1}).toArray();
  const ops = users.map(u => ({
    updateOne: {
      filter: { user: u._id },
      update: { $setOnInsert: { tokenCredits: AMOUNT } },
      upsert: true
    }
  }));
  if (ops.length > 0) {
    const result = db.getSiblingDB("LibreChat").getCollection("balances").bulkWrite(ops);
    print("Processed " + ops.length + " users, inserted " + result.upsertedCount + " new balances");
  }
'

---

Set Balance

Set a specific user's balance to an exact amount (overwrites)

docker compose exec mongodb mongosh --eval '
  const user = db.getSiblingDB("LibreChat").getCollection("users").findOne({ email: "USER_EMAIL" });
  if (user) {
    db.getSiblingDB("LibreChat").getCollection("balances").updateOne(
      { user: user._id },
      { $set: { tokenCredits: AMOUNT } },
      { upsert: true }
    );
    print("Set balance to AMOUNT for " + user.email);
  } else {
    print("User not found");
  }
'

Set ALL users to an exact balance

docker compose exec mongodb mongosh --eval '
  const result = db.getSiblingDB("LibreChat").getCollection("balances").updateMany(
    {},
    { $set: { tokenCredits: AMOUNT } }
  );
  print("Set balance for " + result.modifiedCount + " users");
'

---

Built-in CLI Commands (alternative)

# Add to existing balance
docker compose exec api npm run add-balance USER_EMAIL AMOUNT

# Set exact balance
docker compose exec api npm run set-balance USER_EMAIL AMOUNT

# List all balances
docker compose exec api npm run list-balances

---

Quick Reference

Action	Replace
User email	USER_EMAIL with the actual email
Token amount	AMOUNT with a number (e.g. 1000000 = 1M tokens)

Balance Config (librechat.yaml)

balance:
  enabled: true
  startBalance: 20000          # tokens for new users
  autoRefillEnabled: false
  refillIntervalValue: 30
  refillIntervalUnit: "days"
  refillAmount: 10000

After editing librechat.yaml, restart: docker compose down && docker compose up -d