lua chat sends messages to your agent the way an end user would and streams the reply. In the sandbox it runs your locally compiled code; in production it runs the live versions, so production messages reach the same agent your end users talk to and are stored in its conversation history.
Verified against lua-cli 3.33.0. The production log declaration described below is available from lua-cli 3.39.0.
Synopsis
Description
-e sandbox and -e production choose the environment; staging is accepted and means sandbox. Any other value exits 2 with Invalid environment: "<value>". Must be "sandbox", "staging", or "production". With -m or -b and no -e, the command defaults to sandbox and says so. With neither, it asks.
-e production also decides which environment the turn is logged as. A lua chat session reaches the platform over a development channel, and a development channel is recorded against the sandbox environment — so -e production, against the promoted agent, used to write log rows labelled sandbox. A log drain scoped to production, or a lua logs --environment production filter, then saw nothing at all from that testing, which looks exactly like a broken drain.A -e production session now declares environment: "production" on the chat request, its rows are labelled production, and a production-scoped drain receives them. It may not be enabled on your deployment yet — where it is not, -e production is recorded as sandbox, exactly as before. Three things hold either way:-e sandboxdeclares nothing. A development channel already gives it thesandboxlabel it should have.--agent-version <n>declares nothing either, even though a preview runs against production. It executes a snapshot that was never promoted, which is sandbox by every definition the platform uses.- The declaration only ever raises. A turn may declare
productionand neversandbox, so nothing a caller sends can move a real production turn out of a drain that selects it.
rag, skill, preprocessor, postprocessor and sandbox rows carry the declared environment; runtime rows, which the agent runtime writes from wherever it happens to log, stay sandbox. A drain selecting both environments sees the whole turn; one selecting production alone sees a real part of it, not all of it.lua push. The CLI compiles the project, registering any primitive the agent does not have yet, then uploads each skill’s compiled tools and each preprocessor and postprocessor as a <version>-sandbox version of that primitive. Every message is then sent with overrides that point the agent at those sandbox versions and at the persona in your local LuaAgent. The code runs on the platform, not in your terminal; the live versions and end users are untouched. lua chat -e sandbox uploads your .env values with each sandbox version and sandbox turns read them; production turns read the server-side variables set with lua env production. Webhooks, jobs, triggers, and workflows take no part in a sandbox chat. Production mode sends messages with no overrides. --ci does not stop the environment question, which appears when you pass neither -e nor -m; pass -e.
Every chat belongs to a thread. -t <id> scopes the conversation to that thread, -t with no value generates a fresh UUID and prints it, and omitting -t continues the default thread shared by all your earlier unscoped chats with this agent. For repeatable tests pass -t. --clear (alias --clear-thread) deletes history when the run ends: only that thread’s with -t, otherwise all of your history with the agent. --agent-version <n> previews a staged or superseded agent version in an isolated thread; it runs against production only and the version must exist.
-b sends several messages concurrently, each starting -d milliseconds after the previous one, and reports per message whether the agent responded, absorbed it into a batch, or errored. Each batched message is its own turn; for a scripted multi-turn conversation, call lua chat -m repeatedly with the same -t.
A message may attach files with @<path> tokens at the start or after whitespace: images, PDF and Office documents, and text files up to 10 MB each; tokens with unknown extensions stay in the text. After each turn the CLI counts the agent_error logs it produced and prints the lua logs command to inspect them; an empty reply prints debugging hints. LUA_NO_HINTS=1 silences both. There is no --json output.
lua chat clear deletes conversation history for the configured agent: yours by default, one thread with -t, or another end user’s with --user, which needs the org:manage permission. It asks for confirmation unless --force is passed.
Arguments
Options
Options of
lua chat clear:
Examples
Test local code in the sandbox, in a fresh thread that is cleared afterwards. The compile and upload progress goes to stderr; the thread line, the reply, and the clear confirmation go to stdout:Output
@./screenshot.png what does this error mean? at the prompt; press Ctrl+C to exit.
Preview agent version 4 before promoting it:
Exit codes
See also
- Test an agent before you release — sandbox chat, threads, and
lua testtogether - About environments
lua test— run one tool with no model involvedlua logs— read the errors a turn producedlua version— what--agent-versionpreviews- Ship logs to your stack — the drain a
-e productionturn can reach