Chat Command - Lua CLI

Overview

The lua chat command provides an interactive command-line interface for conversing with your Lua AI agent in both sandbox and production environments.

lua chat

Want to test on real channels? You can also test your agent on WhatsApp, Facebook, Instagram, Email, and Slack without setting up your own channels. See Quick Testing Channels for instant testing on any platform.

Features

Sandbox Mode

Test with local skill overrides and persona customizations

Production Mode

Chat with your live production agent

Interactive Loop

Continuous conversation until exit

Multi-Skill Support

All skills automatically included in sandbox

Prerequisites

Configure API Key

lua auth configure

Initialize Project

lua init

Ensures lua.skill.yaml exists

Deploy Skills

lua push

Required for sandbox testing

How It Works

Authentication

✅ Authenticated

Validates your API key and retrieves user data

Environment Selection

? Select environment: 
  🔧 Sandbox (with skill overrides)
  🚀 Production

Choose between sandbox (testing) or production (live)

Sandbox Setup (if Sandbox)

🔄 Compiling skill...
🔄 Pushing skills to sandbox...
✅ Pushed 2 skills to sandbox

Compiles and deploys your local skills to sandbox

Chat Interface

============================================================
💬 Lua Chat Interface
Environment: 🔧 Sandbox
Press Ctrl+C to exit
============================================================

🤖 Assistant: Hi there! How can I help you today?

👤 You: 

Interactive conversation begins

Sandbox vs Production

Sandbox Mode
Production Mode

For Development & Testing

$ lua chat
? Select environment: 🔧 Sandbox

Features:

✅ Local skill overrides
✅ Persona customization
✅ Environment variables from .env
✅ Test before deploying

Setup time: ~10-30 seconds (includes compilation)Use when:

Developing new features
Testing skill changes
Iterating on persona
Before pushing to production

For Validation

$ lua chat
? Select environment: 🚀 Production

Features:

✅ Production skills only
✅ Live production persona
✅ Real environment variables
✅ Verify deployed changes

Setup time: ~1-2 secondsUse when:

Validating deployed changes
Testing production experience
Verifying skill interactions

Example Session

Sandbox Mode

$ lua chat
✅ Authenticated
? Select environment: 🔧 Sandbox (with skill overrides)
🔄 Setting up sandbox environment...
🔄 Compiling skill...
✅ Skill compiled successfully - 3 tools bundled
🔄 Pushing skills to sandbox...
✅ Pushed 2 skills to sandbox

============================================================
💬 Lua Chat Interface
Environment: 🔧 Sandbox
Press Ctrl+C to exit
============================================================

🤖 Assistant: Hi there! How can I help you today?

👤 You: What's the weather in London?
🤖 Assistant: ...
🤖 Assistant: The current weather in London is 15°C and cloudy with light wind.

👤 You: Search for laptops
🤖 Assistant: ...
🤖 Assistant: I found 5 laptops in our catalog:
1. MacBook Pro - $1999
2. Dell XPS 13 - $1299
3. ThinkPad X1 - $1499
...

👤 You: ^C

👋 Goodbye!

Persona Override

Configuration

In lua.skill.yaml:

agent:
  agentId: "agent_abc123"
  organizationId: "org_xyz789"
  persona: |
    You are a helpful customer service assistant.
    You help users with product inquiries and order management.
    Be friendly, professional, and concise.

In Sandbox Mode:

Persona is automatically loaded and sent with each request
Test different persona variations
Iterate quickly

In Production Mode:

Uses production persona (from server)
No local override

Skill Override

How It Works

Sandbox mode automatically:

Compiles all skills in your project
Pushes to sandbox environment
Gets sandbox IDs for each skill
Includes all sandbox IDs in chat requests

Example override:

{
  "skillOverride": [
    {
      "skillId": "skill_abc123",
      "sandboxId": "sandbox_def456"
    }
  ]
}

The AI uses your local sandbox versions instead of production versions.

Thread Isolation

By default, lua chat uses your agent’s shared conversation context. Use the --thread flag to scope a session to an isolated thread — useful for running consecutive tests without state leaking between runs.

Usage

# Scope to an explicit thread ID
lua chat --thread my-test-scenario

# Auto-generate a fresh thread ID (printed at session start)
lua chat --thread

# Reuse a thread across multiple non-interactive messages
lua chat -m "step 1" --thread test-flow
lua chat -m "step 2" --thread test-flow

# Isolated test: scoped thread, auto-cleared on exit
lua chat -m "run test" -t --clear

# Explicit thread with auto-clear
lua chat -m "run test" -t my-test --clear

Flags

Flag	Description
`-t, --thread [id]`	Scope to a thread. Omit the ID to auto-generate a UUID. The active thread ID is always printed at session start.
`--clear`, `--clear-thread`	Clear the thread’s history when the session ends (interactive: on exit, non-interactive: after response). Requires `--thread`.

Clearing a Thread Manually

lua chat clear --thread my-test-scenario

Testing Workflow Example

Run 10 isolated test cases against your agent, each with a clean slate:

for i in $(seq 1 10); do
  lua chat -m "test scenario $i" -t "test-run-$i" --clear -e sandbox
done

File Attachments

You can attach files to any message using @<path> syntax — in both interactive and non-interactive mode.

# Attach an image
@/path/to/screenshot.png what's wrong with this UI?

# Attach a document
@report.pdf summarize this

# Mix text and attachment
check @screenshot.png and tell me what you see

The @ must appear at the start of your message or after a space. Email addresses ([email protected]) are never treated as attachments.

Supported File Types

Images
Documents & Spreadsheets
Text & Markup
Email

Sent natively to vision-capable models.

Extension	Type
`.png`	PNG image
`.jpg`, `.jpeg`	JPEG image
`.gif`	GIF image
`.webp`	WebP image
`.bmp`	Bitmap image
`.tiff`, `.tif`	TIFF image
`.heic`	HEIC image

If the model natively supports the format it is sent as-is; otherwise it is converted to an LLM-friendly format automatically.

Extension	Type
`.pdf`	PDF document
`.doc`, `.docx`	Word document
`.xls`, `.xlsx`	Excel spreadsheet
`.ppt`, `.pptx`	PowerPoint presentation
`.odt`	OpenDocument text
`.epub`	E-book

Extension	Type
`.txt`	Plain text
`.md`	Markdown
`.csv`	Comma-separated values
`.tsv`	Tab-separated values
`.html`, `.htm`	HTML
`.xml`	XML
`.json`	JSON
`.rtf`	Rich text
`.rst`	reStructuredText
`.org`	Org-mode

Extension	Type
`.eml`	Email message
`.msg`	Outlook message

Files with unsupported extensions are left as plain text in your message — they are never silently stripped.

Model support required. Attachment support depends on the model configured for your agent. If the model doesn’t support vision or file inputs, attachments won’t be processed — even if the CLI sends them successfully. Check your agent’s model configuration if attachments aren’t being picked up.

Limits

Maximum file size: 10 MB per attachment
Multiple attachments per message are supported

Non-Interactive Mode

The same @<path> syntax works in -m / --message flags:

lua chat -m "@screenshot.png what do you see?" -e production
lua chat -m "review @report.pdf and @notes.txt" -e sandbox

Batch Mode

Test how your agent handles concurrent or rapid-fire messages with the -b/--batch flag. Useful for stress-testing skills that share state or for reproducing race conditions reported in production.

# Send 3 messages concurrently
lua chat --batch "list my orders" "what's the status of order 1" "cancel order 1"

# Add a delay (ms) between dispatches
lua chat --batch "msg 1" "msg 2" "msg 3" --delay 250

Option	Description
`-b, --batch <messages...>`	Dispatch multiple messages and print every reply. Each message is treated as an independent turn.
`-d, --delay <ms>`	Delay between batch messages in milliseconds (default: `100`).

Batch mode is not a way to scriptably hold a multi-turn conversation — each batched message is a separate turn. For ordered scripted conversations, use repeated lua chat -m "..." calls with -t <thread-id> instead.

Keyboard Shortcuts

Shortcut	Action
`Enter`	Send message
`Ctrl+C`	Exit chat
`Ctrl+D`	Exit chat (alternative)

Best Practices

Development Workflow

Make changes to your skills
Run lua chat in sandbox mode
Test changes interactively
Iterate until satisfied
Run lua push to deploy
Test again in production mode
Deploy with lua deploy

Testing Strategy

Start with sandbox:

Test happy paths
Test error cases
Test edge cases
Test multi-step flows

Validate with production:

Verify deployed changes work
Test with production data
Confirm no regressions

Persona Iteration

Update persona in your LuaAgent code (src/index.ts)
Run lua chat in sandbox
Test conversation style
Refine persona
Repeat until satisfied
Deploy to production with lua push persona

Active log probe (`agent_error` after every turn)

After every lua chat turn — interactive or -m non-interactive — the CLI runs a quiet lua logs --type agent_error probe scoped to the current session. The probe checks for server-side pipeline errors that don’t always surface in the chat response itself (billing failures, schema validation failures, LLM provider errors, post-processor errors). When the probe is silent, no agent errors fired during your turn — you’re clean. When new errors fire, the CLI prints a one-line warning at the end of the turn:

⚠️  2 new agent error(s) during this turn — run `lua logs --type agent_error --limit 2` to inspect.

Empty response: If the agent returns no text (empty stream), the CLI warns: ⚠️ The agent returned an empty response and points you at agent_error and runtime logs so you can see what failed on the server. Run the suggested command verbatim to inspect the errors. To opt out (for example in CI that captures only command output), set LUA_NO_HINTS=1:

LUA_NO_HINTS=1 lua chat -m "test" -e production

Debugging recipe

# Send one isolated test, then check for pipeline errors
lua chat -m "test" -t debug-1 --clear && lua logs --type agent_error --limit 5

See Debugging your agent — the post-deploy loop for the complete flow.

Troubleshooting

Debugging after a failed chat: If a chat turn returns a wrong, empty, or error response, the CLI now automatically surfaces a count of agent_error logs that fired during that turn. To inspect them, run the suggested lua logs --type agent_error --limit N command. See Debugging your agent — the post-deploy loop for the canonical loop.

No API key found

Error:

❌ No API key found

Solution:

lua auth configure

Configuration file missing

Error:

❌ No agent ID found in lua.skill.yaml

Solution:

lua init

Compilation failed

Error:

❌ Compilation failed

Solution:

Fix TypeScript errors in your code
Check src/index.ts for syntax errors
Verify all imports are correct

Skills not in sandbox

Error:

❌ Failed to push skills to sandbox

Solution:

lua push  # Deploy skills first
lua chat  # Then try again

Slow responses

Issue: Long wait times in sandboxCauses:

First request after compilation
Large skill bundles
Network latency

Solution: Subsequent messages will be faster

Persona not working

Issue: Persona override not being appliedCheck:

Using sandbox mode (not production)
agent.persona exists in lua.skill.yaml
Persona is properly formatted YAML

Debugging Loop

Canonical push → test → check flow + the active log probe

lua logs

Inspect agent_error and tool execution logs

lua test

Test individual tools with specific inputs

lua push

Deploy skills to server

Next Steps

Test Individual Tools

Test tools one at a time

Deploy to Production

Push your skills live

​Overview

​Features

Sandbox Mode

Production Mode

Interactive Loop

Multi-Skill Support

​Prerequisites

​How It Works

​Sandbox vs Production

​Example Session

​Sandbox Mode

​Persona Override

​Configuration

​Skill Override

​How It Works

​Thread Isolation

​Usage

​Flags

​Clearing a Thread Manually

​Testing Workflow Example

​File Attachments

​Supported File Types

​Limits

​Non-Interactive Mode

​Batch Mode

​Keyboard Shortcuts

​Best Practices

​Active log probe (agent_error after every turn)

​Debugging recipe

​Troubleshooting

​Related Commands

Debugging Loop

lua logs

lua test

lua push

​Next Steps

Test Individual Tools

Deploy to Production

Overview

Features

Prerequisites

How It Works

Sandbox vs Production

Example Session

Sandbox Mode

Persona Override

Configuration

Skill Override

How It Works

Thread Isolation

Usage

Flags

Clearing a Thread Manually

Testing Workflow Example

File Attachments

Supported File Types

Limits

Non-Interactive Mode

Batch Mode

Keyboard Shortcuts

Best Practices

Active log probe (`agent_error` after every turn)

Debugging recipe

Troubleshooting

Related Commands

Next Steps