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

# lua devices

> List device definitions, check a device's connection state, enable or disable it, and send it test commands

`lua devices` manages the [devices](/concepts/devices) an agent can command: it lists the pushed device definitions, reports whether a device is connected, enables or disables it, removes it, and sends a command or a test trigger to a connected device. `disable` and `remove` change what the agent can do for every end user immediately.

*Verified against lua-cli 3.33.0.*

## Synopsis

```bash theme={null}
lua devices [list|status|enable|disable|remove|test|test-trigger] [--device-name <name>] [--group <group>] [--payload <json>] [--timeout <ms>] [--force]
```

## Description

With no action the command opens a menu covering every action. Every action except `list` needs a device name; without `--device-name` it prompts you to pick one.

`list` prints the device definitions pushed to the agent, with ID, group, and description, filtered by `--group` if given. It reads definitions, not live connections: a device that only connects with a self-describing client and was never pushed is not listed. Use `status` for connection state.

`status` prints `online` when the device is connected, otherwise its stored state: `offline`, `registered` (enabled, not connected), or `disabled`.

`enable` and `disable` set that stored state. A disabled device is refused with `DEVICE_DISABLED` the next time it connects; `enable` sets it back to `registered`.

`remove` deletes the device definition and its versions after a confirmation prompt, or immediately with `--force`.

`test` sends a command to the connected device and prints the response and the round-trip latency. The command name is always prompted for; `--payload` supplies the JSON body and `--timeout` the wait. An offline device or a timed-out command is reported on screen with exit `0`.

`test-trigger` relays a command named `__test_trigger__<trigger>` to the connected device with `--payload`. The trigger name is always prompted for. The platform runs no trigger handler for it, so use it as a connectivity check; to exercise a handler end to end, fire the trigger from the device client and read [`lua logs --type device-trigger`](/reference/cli/logs).

Because `test` and `test-trigger` have no flag for the command or trigger name, both need an interactive terminal; under `--ci` they exit `1` at the prompt.

Devices are not a [`lua deploy`](/reference/cli/deploy) type. A device defined with [`defineDevice`](/reference/sdk/device-definition) is pushed with [`lua push device --name <device>`](/reference/cli/push), a standalone handler defined with `defineDeviceTrigger` with `lua push device-trigger --name <trigger>`. Each push uploads a version and then asks whether to publish it (default No); `--auto-deploy` publishes without asking, and `--force` alone skips the question and leaves the new version unpublished. A pushed `defineDevice` declaration reaches the runtime on the agent's next turn whether or not you publish it; `--auto-deploy` only records it as the active version. A standalone `defineDeviceTrigger` runs only after its pushed version is published, with `--auto-deploy` or the push prompt. Self-describing devices need no push: their commands become tools while the device is connected.

## Arguments

| Argument | Values                                                                  | Description               |
| -------- | ----------------------------------------------------------------------- | ------------------------- |
| `action` | `list`, `status`, `enable`, `disable`, `remove`, `test`, `test-trigger` | Omit it to open the menu. |

Accepted spellings: `ls`, `l` → `list`; `info`, `show` → `status`; `on`, `activate` → `enable`; `off`, `deactivate` → `disable`; `rm`, `delete`, `del` → `remove`; `run`, `exec` → `test`; `test_trigger` → `test-trigger`.

## Options

| Option                 | Description                                                                | Default |
| ---------------------- | -------------------------------------------------------------------------- | ------- |
| `--device-name <name>` | Device to act on. Prompted for when omitted, except for `list`.            | —       |
| `--group <group>`      | Show only devices in this group. `list` only.                              | —       |
| `--payload <json>`     | JSON object sent with `test` or `test-trigger`. Invalid JSON exits `1`.    | `{}`    |
| `--timeout <ms>`       | How long `test` and `test-trigger` wait for the device.                    | `30000` |
| `--force`              | Skip the `remove` confirmation.                                            | off     |
| `--ci`                 | Global flag. Refuse any prompt with exit `1` instead of waiting for input. | off     |

## Examples

List the pushed device definitions.

```bash theme={null}
lua devices list
```

```text Output theme={null}
  Devices (1):

  📡 gate-controller [gates]
     ID: e03268b3-39f0-4f24-8bb0-30e15bb9cb00
     Yard gate controller
```

Check whether a device is connected.

```bash theme={null}
lua devices status --device-name gate-controller --ci
```

```text Output theme={null}
🔴 Device 'gate-controller' is offline
```

Send a command with a payload; the command name is prompted for.

```bash theme={null}
lua devices test --device-name gate-controller --payload '{"gate":"north"}' --timeout 10000
```

Disable a device so it is refused on its next connection, then re-enable it.

```bash theme={null}
lua devices disable --device-name gate-controller --ci
lua devices enable --device-name gate-controller --ci
```

Remove a device definition from CI without the confirmation prompt.

```bash theme={null}
lua devices remove --device-name gate-controller --force --ci
```

## Exit codes

| Code | Meaning     | When                                                                                                                                            |
| ---- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`  | OK          | The action completed, including a cancelled `remove` and a `test` whose device was offline or timed out.                                        |
| `1`  | Error       | No devices are registered when a name is needed, the platform refused the action, `--payload` is not JSON, or a prompt was needed under `--ci`. |
| `2`  | Usage       | Unknown action.                                                                                                                                 |
| `9`  | Auth        | No valid credential.                                                                                                                            |
| `10` | Forbidden   | The credential cannot manage this agent.                                                                                                        |
| `11` | Unavailable | Network error or a server 5xx.                                                                                                                  |

The full table is in [Errors and exit codes](/reference/cli/errors-and-exit-codes).

## See also

* [`defineDevice` and `defineDeviceTrigger`](/reference/sdk/device-definition)
* [Connect your first device](/devices/quickstart)
* [Device triggers](/devices/triggers) — handlers and how to fire them from the device
* [Node client](/devices/node-client) and [Python client](/devices/python-client)
* [`lua logs`](/reference/cli/logs) — `--type device` and `--type device-trigger`