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
```bash
docker compose exec api npm run list-balances
```

### Check a specific user's balance
```bash
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)
```bash
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
```bash
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
```bash
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)
```bash
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
```bash
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)

```bash
# 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)

```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`