lua devices manages the devices an agent can command: it lists the devices the agent has declared or seen connect, reports whether a device is online, enables, disables, or removes it, sends a command to a connected device, fires a trigger through the live handler pipeline, and issues the device credential a board or script connects with. disable and remove change what the agent can do for every end user immediately.
Verified against lua-cli 3.45.0.
Synopsis
Description
With no action the command opens a menu covering every action. Every action exceptlist needs a device name; without --device-name it prompts you to pick one of the agent’s devices (or, for credential, to type one).
list prints every device the agent knows about: the devices declared with defineDevice and pushed, and the devices that have connected, including self-describing devices that send their own command list. Each line shows the status (online, offline, or disabled), the group in brackets, and a declared tag for a device that has a defineDevice declaration, followed by the description and, for a device that isn’t online, when it was last seen. --group keeps one group.
status prints one line: online; disabled, with the command that enables it; offline for a device the agent has declared or seen before; or has never connected to this agent for a name it has neither declared nor seen, which usually means a typo or a device that connected with a different name.
disable disconnects the device at once and refuses it until you run enable. enable allows it back; the device stays offline until its client connects again, which the device clients do on their own retry, so restart a client that has stopped retrying.
remove deletes the device’s defineDevice declaration and its versions, and the record of a device that has connected, after a confirmation prompt or immediately with --force. A name the agent doesn’t know is refused with not_found (exit 3). A device that is still connected when you remove it reappears the next time its client connects; disable it to keep it out.
test sends one command to the connected device and prints the reply and the round-trip latency. Pass the command with --command, or it is prompted for; --payload supplies the JSON body and --timeout the wait. Any failure exits 1 with a message that says which it was: the device is offline, the device is disabled, no reply arrived within the timeout (usually a command the device doesn’t declare), or the device’s own error, for example Device 'bench-sensor' returned an error (41ms): Unknown command: nope.
test-trigger fires a trigger as if the device had sent it, through the same live pipeline: the matching handler runs on the platform, and you read its run with lua logs --type device-trigger. Pass the trigger with --trigger, or it is prompted for, and the payload with --payload. The device itself receives nothing and doesn’t need to be connected, but a disabled device is refused. The 1 MB payload cap and the limit of 10 triggers per second per agent apply as they do to a trigger sent from the device. A trigger with no live handler is logged as skipped.
credential issues a device credential bound to this project’s agent and one device name, for the operations in --operations: commands, triggers, and assets.upload, default commands,triggers. It needs an email sign-in. An API-key sign-in is refused with a hint to run lua auth configure and choose Email, and so is any run while LUA_API_KEY is set in the environment or in a .env in the current directory, because that key takes precedence over a stored session. With --out <file> it writes LUA_AGENT_ID, LUA_DEVICE_NAME, and LUA_DEVICE_CREDENTIAL to the file with mode 600 and refuses to overwrite an existing file unless --force is given; without --out it prints the secret once. The secret is never shown again, so issue a new credential if you lose it.
Devices are not a lua deploy type. A device defined with defineDevice is pushed with lua push device --name <device>, 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
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; credentials, key → credential.
Options
Examples
Issue a credential for a board and save it next to the device code, outside the agent project. The folder must exist.Output
Output
Output
Exit codes
The full table is in Errors and exit codes.
See also
- Build your first device
- Create a device credential
defineDeviceanddefineDeviceTrigger- Device triggers — handlers and how to fire them from the device
- Node client and Python client
lua logs—--type deviceand--type device-trigger