CLI Documentation

npx calabasas login

# Output:
# Opening browser for authentication...
# Waiting for authentication (timeout: 5 minutes)...
# ✓ Authenticated as developer@example.com
# API key saved to ~/.calabasas/config.json

npx calabasas logout

# Output:
# ✓ Logged out successfully

npx calabasas init

# Creates convex/calabasas.config.ts with:
import { defineCalabasas } from "calabasas";

export default defineCalabasas({
  // Sync Discord data to Convex tables
  sync: {
    guilds: true,
    channels: true,
    roles: true,
    members: false, // Requires privileged intent
  },

  // Events to handle
  events: {
    messageCreate: true,
    interactionCreate: true,
    guildMemberAdd: true,
  },
});

# Interactive mode
npx calabasas bot add

# Non-interactive mode (all required flags)
npx calabasas bot add \
  -n "my-bot" \
  -a 123456789012345678 \
  -t "BOT_TOKEN"

# ✓ Bot registered successfully
# Saved to .env.local:
#   CALABASAS_BOT_ID=abc123

npx calabasas bot list

# Real-time view (default):
# calabasas v0.2.3 · 2 bots · Press q to quit
#
# my-awesome-bot    ● connected    123456789012345678  2m ago
# test-bot          ● error        987654321098765432  5h ago
#                   Token expired

# Static output:
npx calabasas bot list --once

# Update bot name
npx calabasas bot edit abc123 --name "production-bot"

# Update Convex URL
npx calabasas bot edit abc123 --url "https://new-project.convex.cloud"

# Update multiple properties
npx calabasas bot edit abc123 -n "new-name" -u "https://new.convex.cloud"

npx calabasas bot remove abc123
# Alias: calabasas bot rm abc123

# Skip confirmation (for scripts):
npx calabasas bot remove abc123 --yes

npx calabasas status
# Alias: calabasas dashboard

# Full-screen dashboard with:
# - Bot list with live status indicators
# - Stats panel (total events, success/failure counts, avg latency)
# - Live event log for the selected bot
#
# Navigation:
#   j/k or ↑/↓  Select bot
#   q            Quit

# With .env.local set, no flags needed:
npx calabasas logs

# Live output:
# Event Log (live · 12 events)
# 14:32:05  ✓  messageCreate      12ms
# 14:32:04  ✓  interactionCreate  45ms
# 14:31:58  ✗  guildMemberAdd     102ms  Handler timeout

npx calabasas generate

# Output:
# ✓ Generated convex/discord.generated.ts
#   → 12 event handlers
#   → 47 type definitions
#   → 4 sync table schemas
#   → 1 handleDiscordEvent wrapper

# Usage in your code:
import { handleDiscordEvent } from "./discord.generated";

export const receive = handleDiscordEvent({
  messageCreate: async (ctx, event) => {
    // Full TypeScript autocomplete!
    console.log(event.content);
    console.log(event.author.id);
  },
});

# With .env.local set, no flags needed:
npx calabasas push

# Or specify explicitly:
npx calabasas push -b abc123

# ✓ Configuration pushed successfully

# Interactive mode
npx calabasas config

# List current config
npx calabasas config --list

# Add events via flags
npx calabasas config --add-event messageCreate presenceUpdate

# Enable sync properties
npx calabasas config --add-sync presence members

# Combine flags
npx calabasas config --add-event messageCreate --add-sync presence

// convex/calabasas.config.ts
import { defineCalabasas } from "calabasas";

export default defineCalabasas({
  events: { interactionCreate: true },
  commands: {
    ping: {
      description: "Check bot latency",
    },
    ban: {
      description: "Ban a user",
      options: [
        { name: "user", type: "user", description: "User to ban", required: true },
        { name: "reason", type: "string", description: "Ban reason" },
      ],
    },
    settings: {
      description: "Bot settings",
      subcommands: {
        view: { description: "View current settings" },
        set: {
          description: "Update a setting",
          options: [
            { name: "key", type: "string", description: "Setting name", required: true },
            { name: "value", type: "string", description: "New value", required: true },
          ],
        },
      },
    },
  },
});

// convex/discord.ts
import { handleDiscordEvent } from "./discord.generated";

export const receive = handleDiscordEvent({
  interactionCreate: async (ctx, event) => {
    if (event.data?.name === "ping") {
      return { content: "Pong!" };
    }

    if (event.data?.name === "ban") {
      const userId = event.data.options?.find(
        (o: any) => o.name === "user"
      )?.value as string;

      // Schedule a Convex action for Discord API calls
      await ctx.scheduler.runAfter(0, internal.discordActions.banUser, {
        guildId: event.guildId!, userId,
      });

      return { content: `Banned <@${userId}>`, ephemeral: true };
    }
  },
});

// convex/discordActions.ts
import { discord } from "./discord.actions.generated";
import { internalAction } from "./_generated/server";
import { v } from "convex/values";

export const banUser = internalAction({
  args: { guildId: v.string(), userId: v.string() },
  handler: async (ctx, { guildId, userId }) => {
    await discord.ban(guildId, userId, { reason: "Violated rules" });
  },
});

export const welcome = internalAction({
  args: { channelId: v.string(), userId: v.string() },
  handler: async (ctx, { channelId, userId }) => {
    await discord.sendMessage(channelId, {
      content: `Welcome <@${userId}>!`,
    });
  },
});