Kharat Bot Docs

Getting started About 2 min read

Your first custom command

Create, compile and activate a working custom command in a few minutes — and learn the KAL v2 shape every script follows.

Custom commands are small programs written in KAL v2 (the Kharat Automation Language). This guide walks through one complete example; the KAL v2 category documents the language in depth.

Open the builder#

  1. Sign in at /dashboard and pick your server.
  2. Go to Custom commands, then Open builder.

The builder has two modes. Code mode is what you will actually use — write KAL v2 source directly. (The visual mode currently generates an older dialect that the compiler rejects, so prefer code mode until that is fixed; see Custom Command Builder for the details.)

Paste a working command#

Replace the editor contents with this complete KAL v2 program:

kal
KAL VERSION 2.0;
AUTOMATION hello_command {

    WHEN COMMAND hello (name AS STRING) {
        REPLY "Hello, " + name + "! Welcome to " + guild.name + ".";
    }
}

Every line here is required and means something:

LinePurpose
KAL VERSION 2.0;Mandatory first line. Without it the compiler refuses the script with E001_MALFORMED_VERSION_HEADER.
AUTOMATION hello_command { … }Wraps the whole program; the name is your script's identity.
WHEN COMMAND hello (name AS STRING) { … }Declares a command named hello that takes one string option.
REPLY …Sends a channel reply to whoever ran the command.

Validate and simulate#

Use the builder's Check syntax first — it compiles your source without executing anything and reports errors with line, column and a hint. Then Run simulation to dry-run the command against a mock user; the recorded actions are shown without touching your real server.

Save and activate#

  • Save draft keeps the script stored but inactive — drafts may even contain compile errors.
  • Save & publish compiles the script; a compile error blocks the save, and a successful save immediately registers the command on your server.

Run /hello name:Sam (or ,hello Sam) in your server to see the reply.

Make it configurable#

Real commands usually need settings. The CONFIG block adds fields that appear in the command's configuration page on the dashboard:

kal
KAL VERSION 2.0;
AUTOMATION announce_command {

    CONFIG {
        target: CHANNEL [
            label: "Announcement channel",
            description: "Where announcements are posted",
            required: true
        ];
    }

    WHEN COMMAND announce (text AS STRING) [permission: "ManageMessages"] {
        SEND MESSAGE text TO config.target;
    }
}

config.target is chosen per server from the dashboard, and the [permission: …] clause restricts who may run the command.

Where to next#