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.
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.
Sandbox mode uses your locally compiled code and needs no 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. The first sandbox run after you add a skill registers it on the server and may answer without it (Skipping skill <name> - no skillId found in lua.skill.yaml); run the command again. 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