> ## 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.

# Devices Command

> Manage connected IoT and physical devices — enable, disable, test commands, and fire triggers

## Overview

`lua devices` manages the registered devices your agent can command and receive triggers from — IoT sensors, label printers, smart-home gear, kiosks, etc. The command lets you list, enable, disable, remove, and test devices and their triggers without writing any code.

```bash theme={null}
lua devices                              # Interactive management
lua devices list                         # List all devices
lua devices status --device-name label-printer
lua devices test --device-name label-printer
```

<Note>
  For defining devices in code, see the [Devices](/devices/overview) tab. For building your own device client, see [Build Your Own](/devices/build-your-own).
</Note>

## Subcommands

| Action         | What it does                                                               |
| -------------- | -------------------------------------------------------------------------- |
| `list`         | List all registered devices (optionally filter by `--group`).              |
| `status`       | Print online/offline/disabled state and last-seen time for a device.       |
| `enable`       | Re-enable a previously disabled device.                                    |
| `disable`      | Stop the agent from issuing commands to a device (offline mode).           |
| `remove`       | Unregister a device. Use `--force` to skip the confirmation.               |
| `test`         | Send a test command to a device. Prompts interactively or use `--payload`. |
| `test-trigger` | Fire a test trigger as if it came from the device.                         |

## Options

| Option                 | Description                                               |
| ---------------------- | --------------------------------------------------------- |
| `--device-name <name>` | Device name. Required for most non-interactive actions.   |
| `--group <name>`       | Filter device list by group (use with `list`).            |
| `--payload <json>`     | JSON payload for `test` / `test-trigger` (default: `{}`). |
| `--timeout <ms>`       | Command timeout in milliseconds (default: `30000`).       |
| `--force`              | Skip confirmation prompts (used with `remove`).           |

## Examples

```bash theme={null}
# Interactive picker
lua devices

# List all devices
lua devices list

# Filter list by group
lua devices list --group printers

# Inspect device state
lua devices status --device-name label-printer

# Enable / disable
lua devices enable  --device-name label-printer
lua devices disable --device-name label-printer

# Remove (confirms before deleting)
lua devices remove --device-name label-printer
lua devices remove --device-name label-printer --force

# Test a command (interactive payload)
lua devices test --device-name label-printer

# Test with a specific payload
lua devices test --device-name label-printer \
  --payload '{"command":"print","data":{"label":"order-1234"}}'

# Fire a test trigger
lua devices test-trigger --device-name label-printer \
  --payload '{"event":"button_pressed","data":{"button":"red"}}'
```

## Test Command vs Test Trigger

| Command        | Direction      | When to use                                                                   |
| -------------- | -------------- | ----------------------------------------------------------------------------- |
| `test`         | Agent → device | Verify your agent can send commands to a device and that the device responds. |
| `test-trigger` | Device → agent | Verify your agent reacts correctly when a trigger fires from a device.        |

## Common Workflow

After registering a new device:

```bash theme={null}
lua devices list                                       # Confirm registration
lua devices status --device-name new-device            # Check it's online
lua devices test --device-name new-device              # Verify command path
lua devices test-trigger --device-name new-device      # Verify trigger path
lua logs --type device --name new-device --limit 10    # Inspect logs
lua logs --type device-trigger --name new-device       # Inspect triggers
```

## Related

* [Devices Overview](/devices/overview)
* [Self-Describing Commands](/devices/self-describing-commands)
* [Device Triggers](/devices/triggers)
* [Agent Tools for Devices](/devices/agent-tools)
* [Logs Command](/cli/logs-command) — filter by `--type device` or `--type device-trigger`