> For the complete documentation index, see [llms.txt](https://docs.rumi.systems/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rumi.systems/rumi-management/reference/controller/script-commands.md).

# Script Commands

This page provides a reference for all commands available in Rumi Controller deployment scripts.

{% hint style="info" %}
The `xvm` and `xvms` keywords are still accepted as aliases for `container` and `containers` in all script commands for backward compatibility.
{% endhint %}

## Command Overview

| Command     | Description                                         |
| ----------- | --------------------------------------------------- |
| `provision` | Prepare containers on target hosts                  |
| `launch`    | Start container JVM processes                       |
| `start`     | Start microservices within containers               |
| `stop`      | Gracefully stop microservices                       |
| `shutdown`  | Terminate container JVM processes                   |
| `configure` | Apply runtime configuration changes                 |
| `deploy`    | Install application modules into running containers |
| `collect`   | Gather runtime statistics from containers           |
| `instruct`  | Send control messages to applications               |
| `validate`  | Verify system state                                 |
| `wait`      | Pause execution for synchronization                 |
| `cleanup`   | Remove provisioned files from target hosts          |

## Command Reference

### provision

Copies the Rumi distribution and configuration files to the target host and sets up the provisioning directory structure.

**Syntax:**

```
provision all containers
provision the <containerName> container
```

**Targets:** All containers or a specific container by name.

**Actions:**

1. Copies the Rumi distribution to the target host via SCP.
2. Creates the provisioning directory (`.rumi/provisioning/<system>/<container>/`).
3. Localizes configuration files (DDL, JVM parameters, XCS, environment).
4. Executes the `rucprep` preparation script on the target host.

### launch

Starts a container JVM process on the target host.

**Syntax:**

```
launch the <containerName> container
launch the <containerName> container on numa node <n>
```

**Targets:** A specific container by name.

**Options:**

* NUMA node — Optionally bind the container to a specific NUMA node for CPU pinning.

**Actions:**

1. Executes the `ruclaunch` script on the target host via SSH.
2. Starts the JVM with the container's configured parameters.
3. Waits for the container to become available (subject to launch timeout).

### start

Starts the microservices within a running container.

**Syntax:**

```
start the <containerName> container
```

**Targets:** A specific container by name.

**Actions:**

1. Sends a start command to the container over Rumi messaging.
2. The container's AEP engines begin processing messages.

### stop

Gracefully stops the microservices within a container.

**Syntax:**

```
stop the <containerName> container
```

**Targets:** A specific container by name.

**Actions:**

1. Sends a stop command to the container over Rumi messaging.
2. The container's AEP engines stop processing messages.

### shutdown

Terminates a container JVM process.

**Syntax:**

```
shutdown the <containerName> container
```

**Targets:** A specific container by name.

**Actions:**

1. Sends a shutdown signal to the container.
2. The JVM process is terminated.

### configure

Applies runtime configuration changes to a system or container.

**Syntax:**

```
configure the <containerName> container
```

**Targets:** System-level or specific container.

**Actions:**

1. Modifies the specified configuration parameters.
2. Configuration changes may take effect immediately or require a restart depending on the parameter.

### deploy

Installs application modules into running containers.

**Syntax:**

```
deploy the <containerName> container
```

**Targets:** A specific container by name.

**Actions:**

1. Deploys the specified application module to the container.

### collect

Gathers runtime statistics from containers.

**Syntax:**

```
collect the <containerName> container
```

**Targets:** A specific container by name.

**Actions:**

1. Records application and container metrics.

### instruct

Sends control messages to applications.

**Syntax:**

```
instruct the <appName> app in the <containerName> container
```

**Targets:** A specific application in a specific container.

**Actions:**

1. Delivers the specified command to the target application.

### validate

Verifies that the system state meets expected conditions.

**Targets:** System-level or specific container.

**Actions:**

1. Checks the current state against the specified expected state.
2. Returns success or failure based on the validation result.

### wait

Pauses script execution for synchronization purposes.

**Actions:**

1. Waits for the specified condition or duration.

### cleanup

Removes provisioned files from target hosts.

**Syntax:**

```
cleanup all containers
cleanup the <containerName> container
```

**Targets:** All containers or a specific container by name.

**Actions:**

1. Removes the provisioning directory and files from the target host.