> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aboutcapy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Spyglass slash commands and monitor setup.

Everything lives in two files: `config.yml` for settings and commands, `messages.yml` for text. Run `/spyglass reload` after editing either one.

## Custom Discord Commands

The config key is the command. It doubles as the ID and the signature, so this is the whole setup for a working `/ban`:

```
commands:
"ban {username}":
discord-command-description: "Used to ban members"
minecraft-command: "/ban {username}"
```

That registers `/ban` in Discord with a `username` option. Whatever the user types is substituted wherever `{username}` appears in the mapped command.

Quoting the key always works, so the examples do it. A bare `ban {username}:` parses too, because YAML only treats `{` as special at the start of a value. Quotes become required once a key starts with a brace or contains a colon.

## Longer Arguments

Add three dots to the last option when it should swallow a whole sentence, such as a ban reason:

```
"kick {username} {reason...}":
discord-command-description: "Kick a player off the server"
minecraft-command: "/kick {username} {reason}"
arguments:
username:
suggest-online-players: true
reason:
required: false
```

`suggest-online-players` makes Discord autocomplete that option from the live player list.

## Per Command Options

| Option | Default | Description |
| - | - | - |
| discord-command-description | auto | Text shown next to the command in Discord. |
| minecraft-command | required | One command, or a list of commands run in order. |
| enabled | true | Turn one command off without deleting it. |
| run-as | console | Run as console or as a player. |
| run-as-player | none | Which player to run as. Required when run-as is player. |
| cooldown | 0 | Seconds between uses, counted per Discord user. |
| ephemeral | false | Only the person who ran the command sees the reply. |
| log | true | Send this command to the monitor channel. |
| response | none | Custom reply text, overrides the one in messages.yml. |
| allowed-roles | global | Roles that may use this command, by name or ID. |
| allowed-users | global | Users that may use this command, by name or ID. |
| allowed-channels | global | Channels the command may be used in. |
| arguments | none | Per option description, type, choices, and autocomplete. |

Argument types are `string`, `integer`, `number`, `boolean`, `user`, `channel`, and `role`. String options can also take a fixed list of `choices`.

## Command Monitor

Mirrors every command run in game into a Discord channel.

```
command-monitor:
enabled: true
channel-id: "1234567890123456789"
format: "{username}: {command}"
```

Any placeholder works in `format`. Some alternatives:

```
format: "`{time}` **{username}** ran `{command}`"
format: "[{world}] {username} ({x}, {y}, {z}) ran {command}"
format: "{source} | {username} | {command}"
```

### Filters

* `ignored-commands` skips commands by name, by full prefix, or with a trailing wildcard such as `co*`. Login and private message commands are ignored by default so passwords never reach Discord.

* `only-commands` flips it around. If that list is not empty, only those commands are relayed and the ignore list is skipped.

* `ignored-players` hides specific names.

* `include-players`, `include-console`, `include-discord-commands`, and `include-cancelled` toggle each source.

### Batching

Lines are grouped into one Discord message every few seconds, which is what keeps a busy server under Discord's rate limit. Leave it on unless you need each command to arrive instantly.

```
batching:
enabled: true
interval-seconds: 3
max-lines-per-message: 20
```

## Message Formatting

Messages in `messages.yml` use MiniMessage, so gradients, hover tooltips, and clickable commands are all config rather than code:

```
prefix: "Spyglass » "
```

Legacy `&a` and `&#RRGGBB` codes still work. If a line contains one, that whole line is read the old way, so an older `messages.yml` keeps working after an upgrade.

Placeholder values are always inserted as plain text. A player named \`\` shows up as those five characters, so nobody can recolour your staff channel or slip a clickable command into a message through a name or a ban reason.

## Placeholders

Around 85 placeholders are available. The complete list with descriptions is in the comments at the bottom of `config.yml`. The common ones:

| Group | Placeholders |
| - | - |
| Server | {server}, {online}, {max_players}, {tps}, {uptime}, {platform}, {minecraft_version}, {date}, {time}, {datetime} |
| Player | {username}, {displayname}, {uuid}, {ip}, {ping}, {gamemode}, {health}, {world}, {x}, {y}, {z}, {location}, {biome} |
| Command | {command}, {command_name}, {command_args}, {source}, {cancelled}, {command_id} |
| Discord | {discord_user}, {discord_user_id}, {discord_nickname}, {discord_roles}, {discord_channel}, {executed_command}, {result}, {latency} |
| Your own | Every {name} in a command key becomes a placeholder of that name. |

Anything Spyglass does not recognise is left visible, so a typo shows up in the message instead of quietly turning into an empty string.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.