Commands and Permissions

Command Lists

Engine v2

List command names

Returns active command names for the channel without the leading exclamation mark.

List command namesAdvanced Script

const commandNames = commands.names();
const text = commandNames.map((name) => `!${name}`).join(", ");

async.messages.send(`Commands: ${text}`);

API reference

commands.names

commands.names()

Input

This helper does not take input parameters.

Output

string[]

Active command names without the leading exclamation mark.

Example output

[
  "discord",
  "uptime",
  "points"
]

List commands

Returns active command objects for the channel.

List command detailsAdvanced Script

const commandsList = commands.list();
const commandSummaries = commandsList.map((command) => {
  const permissions = command.permissions.join("/");
  return `!${command.command} (${permissions})`;
});

async.messages.send(commandSummaries.join(", "));

API reference

commands.list

commands.list()

Input

This helper does not take input parameters.

Output

object[]

Active command objects.

id

number

Internal command ID.

command

string

Command name without the leading exclamation mark.

active

boolean

Whether the command is active.

aliases

string[]

Alternative command names without the leading exclamation mark.

permissions

string[]

Required permission names.

globalPeriod

number

Global cooldown/period in milliseconds.

userPeriod

number

Per-viewer cooldown/period in milliseconds.

costs

number

Point cost.

usage

string

Usage mode configured for the command.

asResponse

boolean

Whether command output replies to the triggering chat message.

type

string

Command type.

Example output

[
  {
    "id": 1,
    "command": "discord",
    "active": true,
    "aliases": [
      "dc"
    ],
    "permissions": [
      "EVERYONE"
    ],
    "globalPeriod": 0,
    "userPeriod": 0,
    "costs": 0,
    "usage": "online",
    "asResponse": true,
    "type": "custom"
  }
]

List command names for permissions

Returns active command names available to at least one supplied permission, without the leading exclamation mark.

List moderator command namesAdvanced Script

const commandNames = commands.namesForPermissions(["moderator", "broadcaster"]);
const text = commandNames.map((name) => `!${name}`).join(", ");

async.messages.send(`Mod commands: ${text}`);

API reference

commands.namesForPermissions

commands.namesForPermissions(permissions)

Input

permissions

string[]

Permission or role names to filter by.

Output

string[]

Command names available for those permissions, without the leading exclamation mark.

Example output

[
  "mod",
  "timeout"
]

List commands for permissions

Returns active command objects available to at least one supplied permission.

API reference

commands.listForPermissions

commands.listForPermissions(permissions)

Input

permissions

string[]

Permission or role names to filter by.

Output

object[]

Command objects available for those permissions.

id

number

Internal command ID.

command

string

Command name without the leading exclamation mark.

active

boolean

Whether the command is active.

aliases

string[]

Alternative command names without the leading exclamation mark.

permissions

string[]

Required permission names.

globalPeriod

number

Global cooldown/period in milliseconds.

userPeriod

number

Per-viewer cooldown/period in milliseconds.

costs

number

Point cost.

usage

string

Usage mode configured for the command.

asResponse

boolean

Whether command output replies to the triggering chat message.

type

string

Command type.

Example output

[
  {
    "id": 3,
    "command": "mod",
    "active": true,
    "aliases": [],
    "permissions": [
      "MODERATOR",
      "BROADCASTER"
    ],
    "globalPeriod": 0,
    "userPeriod": 0,
    "costs": 0,
    "usage": "all",
    "asResponse": true,
    "type": "custom"
  }
]

Async command list wrappers

Async wrapper for commands.list().

API reference

async.commands.list

async.commands.list()

Input

This helper does not take input parameters.

Output

object[]

Active command objects.

id

number

Internal command ID.

command

string

Command name without the leading exclamation mark.

active

boolean

Whether the command is active.

aliases

string[]

Alternative command names without the leading exclamation mark.

permissions

string[]

Required permission names.

globalPeriod

number

Global cooldown/period in milliseconds.

userPeriod

number

Per-viewer cooldown/period in milliseconds.

costs

number

Point cost.

usage

string

Usage mode configured for the command.

asResponse

boolean

Whether command output replies to the triggering chat message.

type

string

Command type.

Example output

[
  {
    "id": 1,
    "command": "discord",
    "active": true,
    "aliases": [
      "dc"
    ],
    "permissions": [
      "EVERYONE"
    ],
    "globalPeriod": 0,
    "userPeriod": 0,
    "costs": 0,
    "usage": "online",
    "asResponse": true,
    "type": "custom"
  }
]

Async wrapper for commands.names().

API reference

async.commands.names

async.commands.names()

Input

This helper does not take input parameters.

Output

string[]

Active command names without the leading exclamation mark.

Example output

[
  "discord",
  "uptime",
  "points"
]

Async wrapper for commands.listForPermissions(permissions).

API reference

async.commands.listForPermissions

async.commands.listForPermissions(permissions)

Input

permissions

string[]

Permission or role names to filter by.

Output

object[]

Command objects available for those permissions.

id

number

Internal command ID.

command

string

Command name without the leading exclamation mark.

active

boolean

Whether the command is active.

aliases

string[]

Alternative command names without the leading exclamation mark.

permissions

string[]

Required permission names.

globalPeriod

number

Global cooldown/period in milliseconds.

userPeriod

number

Per-viewer cooldown/period in milliseconds.

costs

number

Point cost.

usage

string

Usage mode configured for the command.

asResponse

boolean

Whether command output replies to the triggering chat message.

type

string

Command type.

Example output

[
  {
    "id": 3,
    "command": "mod",
    "active": true,
    "aliases": [],
    "permissions": [
      "MODERATOR",
      "BROADCASTER"
    ],
    "globalPeriod": 0,
    "userPeriod": 0,
    "costs": 0,
    "usage": "all",
    "asResponse": true,
    "type": "custom"
  }
]

Async wrapper for commands.namesForPermissions(permissions).

API reference

async.commands.namesForPermissions

async.commands.namesForPermissions(permissions)

Input

permissions

string[]

Permission or role names to filter by.

Output

string[]

Command names available for those permissions, without the leading exclamation mark.

Example output

[
  "mod",
  "timeout"
]

Engine v1

Here are the commands available: {{kicklet.Commands}}
You can use: {{kicklet.CommandsWithPermission}}

Permission Checks

Use permission helpers when script code should branch based on the current sender or a provided viewer object.

Engine v2

Check viewer permission

Checks whether the current sender or provided viewer has a permission.

Moderator onlyAdvanced Script

if (!permissions.has("moderator")) {
  async.messages.send("Only moderators can use this.");
} else {
  async.messages.send("Moderator action started.");
}

API reference

permissions.has

permissions.has(permission, viewer?)

Input

permission

string

Permission or role name.

vieweroptional

objectstring

Viewer object or username. Defaults to the current sender.

Output

boolean

True when the viewer has the permission.

Check any permission

Returns true when the viewer has at least one supplied permission.

Any permissionAdvanced Script

if (permissions.any(["moderator", "broadcaster"])) {
  async.messages.send("Staff access granted.");
}

API reference

permissions.any

permissions.any(permissions, viewer?)

Input

permissions

string[]

Permissions to check.

vieweroptional

object

Viewer object. Defaults to sender.

Output

boolean

Whether any permission matches.

Check all permissions

Returns true when the viewer has every supplied permission.

API reference

permissions.all

permissions.all(permissions, viewer?)

Input

permissions

string[]

Permissions to check.

vieweroptional

object

Viewer object. Defaults to sender.

Output

boolean

Whether all permissions match.

Check moderator

Returns true when the current sender or provided viewer has the moderator permission or badge.

API reference

permissions.isModerator

permissions.isModerator(viewer?)

Input

vieweroptional

object

Viewer object. Defaults to sender.

Output

boolean

Whether the viewer is a moderator.

Check subscriber

Returns true when the current sender or provided viewer has the subscriber permission or badge.

API reference

permissions.isSubscriber

permissions.isSubscriber(viewer?)

Input

vieweroptional

object

Viewer object. Defaults to sender.

Output

boolean

Whether the viewer is a subscriber.

Check broadcaster

Returns true when the current sender or provided viewer has the broadcaster permission or badge.

API reference

permissions.isBroadcaster

permissions.isBroadcaster(viewer?)

Input

vieweroptional

object

Viewer object. Defaults to sender.

Output

boolean

Whether the viewer is the broadcaster.

Engine v1

Use command permission settings whenever possible.

Command Stats

Command stats show how often commands were used in a time range.

Command Execution Counts

Engine v2

Command execution count

Returns how often one command was used in a time range.

One command execution countAdvanced Script

const rouletteExecutions = stats.commandExecutions("roulette", 60);
async.messages.send(`Roulette in the last hour: ${rouletteExecutions}`);

API reference

stats.commandExecutions

stats.commandExecutions(command, minutes)

Input

command

string

Command name without the leading exclamation mark.

minutes

number

Time range in minutes.

Output

number

Execution count for the selected command and time range.

All command execution count

Returns how often all commands were used in a time range.

All command execution countAdvanced Script

const allExecutions = stats.commandsExecutions(60);
async.messages.send(`All commands in the last hour: ${allExecutions}`);

API reference

stats.commandsExecutions

stats.commandsExecutions(minutes)

Input

minutes

number

Time range in minutes.

Output

number

Execution count for all commands in the selected time range.

Async wrapper for stats.commandExecutions(command, minutes).

API reference

async.stats.commandExecutions

async.stats.commandExecutions(command, minutes)

Input

command

string

Command name without the leading exclamation mark.

minutes

number

Time range in minutes.

Output

number

Execution count for the selected command and time range.

Async wrapper for stats.commandsExecutions(minutes).

API reference

async.stats.commandsExecutions

async.stats.commandsExecutions(minutes)

Input

minutes

number

Time range in minutes.

Output

number

Execution count for all commands in the selected time range.

Engine v1

Use duration strings such as 1h, 1d, or 30m.

This command in the last day: {{kicklet.CommandExecutions "roulette" "1d"}}
All commands in the last day: {{kicklet.CommandsExecutions "1d"}}

Command Execution Ranking

Engine v2

Command execution ranking

Returns the most-used commands for the selected time range.

Command execution rankingAdvanced Script

const ranking = stats
  .commandRanking(5, 60)
  .ranking.map((entry) => `${entry.command}: ${entry.count}`)
  .join("\n");

async.messages.send(ranking);

API reference

stats.commandRanking

stats.commandRanking(limit, minutes)

Input

limit

number

Maximum number of ranking entries.

minutes

number

Time range in minutes.

Output

object

Command execution ranking result.

ranking

object[]

Ranking entries sorted by execution count.

command

string

Command name without the leading exclamation mark.

count

number

Execution count.

Async wrapper for stats.commandRanking(limit, minutes).

API reference

async.stats.commandRanking

async.stats.commandRanking(limit, minutes)

Input

limit

number

Maximum number of ranking entries.

minutes

number

Time range in minutes.

Output

object

Command execution ranking result.

ranking

object[]

Ranking entries sorted by execution count.

command

string

Command name without the leading exclamation mark.

count

number

Execution count.

Engine v1

Use duration strings such as 1h, 1d, or 30m.

{{range $entry := kicklet.CommandsExecutionsRanking 5 "1d"}}
{{$entry.Command}}: {{$entry.Count}}
{{end}}

Permission Checks

Engine v2

Check viewer permission

Checks whether the current sender or provided viewer has a permission.

Check sender permissionAdvanced Script

if (permissions.has("broadcaster") || permissions.has("moderator")) {
  async.messages.send("You can use this.");
} else {
  async.messages.send("This is for moderators only.");
}

API reference

permissions.has

permissions.has(permission, viewer?)

Input

permission

string

Permission or role name.

vieweroptional

objectstring

Viewer object or username. Defaults to the current sender.

Output

boolean

True when the viewer has the permission.

Engine v1

{{if sender.HasPermission "broadcaster"}}
  You are a broadcaster!
{{else}}
  You are not a broadcaster.
{{end}}

Create or Edit Commands

Engine v2

Create or update command

Creates a simple command, or updates an existing command when overwrite is enabled.

Create commandAdvanced Script

commands.save("discord", "Join my Discord: discord.gg/example");
async.messages.send("Command created.");

Edit commandAdvanced Script

commands.save("discord", "New Discord link: discord.gg/example", { overwrite: true });
async.messages.send("Command updated.");

API reference

commands.save

commands.save(command, response, options?)

Input

command

string

Command name without the leading exclamation mark.

response

string

Command response text.

optionsoptional

object

Save options.

overwriteoptional

boolean

Update the command if it already exists.

Output

void

The command is saved as a side effect.

Async wrapper for commands.save(command, response, options?).

API reference

async.commands.save

async.commands.save(command, response, options?)

Input

command

string

Command name without the leading exclamation mark.

response

string

Command response text.

optionsoptional

object

Save options.

overwriteoptional

boolean

Update the command if it already exists.

Output

void

The command is saved as a side effect.

Engine v1

{{$resp := kicklet.CreateCommand "discord" "Join my Discord: discord.gg/example"}}
{{if eq $resp.Error 0}}Command created.{{end}}

{{$resp := kicklet.EditCommand "discord" "New Discord link: discord.gg/example"}}
{{if eq $resp.Error 0}}Command updated.{{end}}

Toggle Commands and Groups

Engine v2

Toggle command

Enables or disables one command.

Toggle commandAdvanced Script

commands.setActive("discord", true);
commands.setActive("oldcommand", false);
async.messages.send("Commands updated.");

API reference

commands.setActive

commands.setActive(command, active)

Input

command

string

Command name without the leading exclamation mark.

active

boolean

Whether the command should be active.

Output

void

The command active state is changed as a side effect.

Toggle command group

Enables or disables all commands in a command group.

Toggle command groupAdvanced Script

commands.setGroupActive("development", false);
async.messages.send("Command group disabled.");

API reference

commands.setGroupActive

commands.setGroupActive(group, active)

Input

group

string

Command group name.

active

boolean

Whether commands in the group should be active.

Output

void

The group active state is changed as a side effect.

Async wrapper for commands.setActive(command, active).

API reference

async.commands.setActive

async.commands.setActive(command, active)

Input

command

string

Command name without the leading exclamation mark.

active

boolean

Whether the command should be active.

Output

void

The command active state is changed as a side effect.

Async wrapper for commands.setGroupActive(group, active).

API reference

async.commands.setGroupActive

async.commands.setGroupActive(group, active)

Input

group

string

Command group name.

active

boolean

Whether commands in the group should be active.

Output

void

The group active state is changed as a side effect.

Engine v1

{{kicklet.ActivateCommand "discord" true}}
{{kicklet.ActivateCommandGroup "development" false}}