> For the complete documentation index, see [llms.txt](https://airdevelopment.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://airdevelopment.gitbook.io/docs/global-features/commands.md).

# Commands

## Shortcuts

Shortcuts register an additional command that redirects to an existing command string. They're useful for giving players quick aliases (`/gmc`, `/bid`) without writing separate command logic — the shortcut just runs the mapped command on the player's behalf, appending any arguments they typed.

{% hint style="warning" %}
Shortcuts are registered at startup, so adding, renaming, or removing one requires a server restart.
{% endhint %}

### Fields

| Field     | Description                                                                                                                      |
| --------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `runs`    | The command string executed when the shortcut is used. Any arguments the player supplies are appended to the end of this string. |
| `aliases` | Additional names that also trigger this shortcut. Leave as `[]` for none.                                                        |

The shortcut itself doesn't require a separate permission — whatever permission the mapped command enforces still applies, since the shortcut simply runs that command as the player.

## Tab-complete

Tab-complete is defined per argument position, starting at `1`. Each position maps to one or more entries that determine what suggestions are shown. See examples below.

{% tabs %}
{% tab title="Simple list" %}
The most concise form - a flat list of static values.

```yaml
tab-complete:
  1: [100, 500, 1000, 5000]
  2: [1, hello1, hello2, 64]
```

{% endtab %}

{% tab title="Single entry" %}
When a position needs `sources`, `requires`, `conditions`, or `suffix-mode`, use a section block.

```yaml
tab-complete:
  1:
    sources: [ONLINE_PLAYERS:20, Player1]
    requires: plugin.command.example
```

{% endtab %}

{% tab title="Multiple entries" %}
A position can have multiple entries as a list. Each is evaluated independently; all passing results are merged.

```yaml
tab-complete:
  1:
    - sources: [ONLINE_PLAYERS:20]
    - sources: [ACTIONS]
      requires: plugin.command.example
```

{% endtab %}

{% tab title="Conditional entries" %}
Tab entry that include a `conditions` list. If any condition fails, that entry's suggestions are hidden entirely.

```yaml
tab-complete:
  1:
    - sources: [100, 500, 1000]
      conditions:
        - "%vault_eco_balance% > 100"
        - "OR %player_gamemode% == CREATIVE %player_gamemode% == ADVENTURE"
    - sources: [tab1, tab2]  # No conditions required
  2:
    sources: [example]
    requires: plugin.command.example
```

{% endtab %}

{% tab title="Copy entries" %}
A position can copy its entries from another position instead of repeating them, optionally filtering sources out and appending new ones. `copy-arg` cannot point to another `copy-arg` position.

```yaml
tab-complete:
  1:
    - sources: [ACTIONS]
    - sources: [test1, test2]
    - sources: [ONLINE_PLAYERS:20]
      requires: plugin.command.example
    - sources: [1, 2, 3, 4, 5]
  2:
    copy-arg: 1
    exclude-sources: [ACTIONS, test1, test2]
    append-sources:
      - sources: [hello, hello2]
        requires: plugin.command.example
```

Position 2 copies position 1's entries, then drops any source matching `ACTIONS`, `test1` and `test2`.

`append-sources` entries are added after the filtered copy, in the same shape as a `Single entry`/`Multiple entries` block.
{% endtab %}
{% endtabs %}

### Fields

| Field             | Description                                                                                                                                     |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `sources`         | What values to suggest (see [Sources](#sources))                                                                                                |
| `requires`        | Permission node required to see these suggestions. Supports `%arg_<n>%` placeholders.                                                           |
| `conditions`      | Conditions that must pass for these suggestions to appear (see [Conditions](/docs/global-features.md#conditions))                               |
| `suffix-mode`     | If `true`, appends each source to the current input instead of replacing it.                                                                    |
| `copy-arg`        | Copies entries from another position.                                                                                                           |
| `exclude-sources` | Source tokens to drop from the copied entries (matched ignoring any `:cap`). An entry left with no sources after exclusion is dropped entirely. |
| `append-sources`  | Extra entries - same shape as `Single entry`/`Multiple entries` - appended after the filtered copy.                                             |

### Argument placeholders

Inside `conditions` and `requires`, `%arg_<n>%` resolves to the value the player typed at argument position `n`. This makes it possible to branch suggestions, or scope permissions, based on earlier input.

| Placeholder      | Resolves to                        |
| ---------------- | ---------------------------------- |
| `%arg_1%`        | Value typed at position 1          |
| `%arg_2%`        | Value typed at position 2          |
| `%arg_<number>%` | Value typed at a specific position |

Out-of-range positions resolve to an empty string - in `conditions` this evaluates as `false`; in `requires` it produces a permission node no player will have, hiding the entry.

```yaml
eco:
  enabled: true
  name: "eco"
  aliases: [economy]
  usage: "/%label% <action> <player> [amount]"
  actions:
    give: "give"
    take: "take"
    set: "set"
    reset: "reset"
  tab-complete:
    1: [ACTIONS]
    2: [ONLINE_PLAYERS:20]
    3:
      sources: [100, 500, 1000, 5000, 10000]
      conditions:
        - "%arg_1% != reset"
```

### Sources

Sources define what values appear in tab-complete. They can be static literals or dynamic tokens resolved at runtime.

| Source           | Description                                                                                   | Example                      |
| ---------------- | --------------------------------------------------------------------------------------------- | ---------------------------- |
| Static literal   | Any value that does not match a recognized token is added as-is.                              | `[1, 2, hello]`              |
| `ONLINE_PLAYERS` | Returns the names of currently online players, with an optional cap.                          | `[ONLINE_PLAYERS:20]`        |
| `DURATION_UNITS` | Offers the units defined in `duration-units`., with an optional list of units allowed.        | `[DURATION_UNITS:<s, m, h>]` |
| `ACTIONS`        | Returns the display names of all entries defined in the subcommand's `actions` map if exists. | `[ACTIONS]`                  |

{% hint style="warning" %}
Additional source tokens may be available depending on the plugin. Refer to the specific plugin's documentation for the full list.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://airdevelopment.gitbook.io/docs/global-features/commands.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.