Skip to main content

​
Overview

The lua logs command provides an interactive interface for viewing and navigating your agent’s execution logs with powerful filtering capabilities. 
lua logs
Looking for the canonical debug loop? See Debugging your agent for the recommended push → test → check flow that uses lua logs as the truth source.

​
When to run lua logs

There are three moments when lua logs is the most valuable command in the CLI: 1. Immediately after a lua chat -m "test". A chat response can look fine while the server quietly logged a billing failure, a tool exception, or an LLM provider error. Run lua logs --type agent_error --limit 5 after every test message — if the count is zero, the test passed cleanly. The CLI also runs a quiet agent_error probe automatically after each chat turn and prints a one-line warning when new errors fire (set LUA_NO_HINTS=1 to silence it). 2. After a lua push to verify a new version is healthy in production. The CLI prints a ✨ Tip: line at the end of every push pointing at the right lua logs --type X --limit 10 command for what you just deployed — follow it. 3. When investigating a user-reported issue. Filter to the affected user with --user-id <id> and to the most likely component type: 
lua logs --type all --user-id user_abc123 --limit 50
lua logs --type skill --name <toolName> --user-id user_abc123 --limit 20

​
Non-Interactive Mode

# View all logs
lua logs --type all --limit 50

# Filter by type
lua logs --type skill --limit 20
lua logs --type webhook --limit 20
lua logs --type job --limit 20

# Filter by specific entity
lua logs --type skill --name mySkill --limit 10

# Pagination
lua logs --type all --limit 20 --page 2

# JSON output for scripting
lua logs --type all --json

# View logs for a different agent (admin access required)
lua logs --agent-id agent-abc123
lua logs --agent-id agent-abc123 --type skill --limit 10

# Voice calls
lua logs --type calls                                # recent voice calls (table)
lua logs --type calls --status failed --json         # failed calls as JSON
OptionDescription
--type <type>Filter: all, skill, job, webhook, preprocessor, postprocessor, device, device-trigger, user_message, agent_response, agent_error, mcp, rag, runtime, calls
--name <name>Entity name (requires —type, not for message types)
--user-id <userId>Filter logs by user ID
--agent-id <agentId>View logs for a specific agent (overrides the agent in lua.config.yaml). Requires admin access to the target agent.
--status <status>Filter calls by status (completed, failed, in-progress, etc.). Only with --type calls.
--limit <n>Number of logs (default: 20)
--page <n>Page number for pagination
--jsonOutput as JSON for scripting
--agent-id is useful for inspecting logs across multiple agents you own without switching project directories. If you don’t have admin access to the requested agent, the command returns an access-denied error.
Type values: Use runtime for platform runtime logs (was previously mastra). Use rag for knowledge base search logs, device-trigger for device trigger execution logs, and calls for voice call records.
agent_error vs runtime: Use --type agent_error to find pipeline failures (billing, validation, LLM provider errors) — these often don’t surface in the chat response itself. Use --type runtime for agent runtime / LLM SDK / framework-level diagnostics (low-level model and orchestration logs).

​
Post-deploy verification recipe

# After deploying — generate traffic FIRST
lua push all --force --auto-deploy
lua chat -e production -m "your test message"   # ← generate traffic first
lua logs --type skill --limit 10                # ← now logs exist
Verify pipeline errors: 
lua chat -e production -m "verify deploy" -t prod-verify --clear
lua logs --type agent_error --limit 5
lua logs returns nothing immediately after deploy. You must generate traffic (via lua chat, a webhook call, or a job trigger) before execution logs appear.
If agent_error --limit 5 returns no entries timestamped after your deploy, the version is healthy. If it does, read the entries before walking away. See Debugging your agent for the complete flow.

Filter by Type

Filter logs by Skills, Jobs, Webhooks, Preprocessors, or Postprocessors

See All Your Components

View logs for all your components, including dynamically created jobs

Detailed Information

See which component generated each log, including names and IDs

Color-Coded

Easily spot errors, warnings, and different log types

​
Log Types

Execution errors and failures
  • Tool execution failures
  • API errors
  • Invalid configurations
  • Stack traces for debugging
Color: Red

​
Interactive Flow

1

Choose What to View

📊 Viewing logs for agent: myAgent

? What logs do you want to view?
❯ 📋 All agent logs
  🔎 Filter logs
2

Choose What to Filter (if filtering)

? Filter by:
❯ Skills
  Jobs
  Webhooks
  Preprocessors
  Postprocessors
  MCP
  RAG (knowledge base)
  Runtime
  Agent errors
  Device trigger
  ──────────────────────
  📋 All logs
  ← Back
3

Select Specific Component (if filtering)

? Select a job:
❯ All Jobs
  ──────────────────────
  Nightly User Report
  Daily Cleanup Task
  ──────────────────────
  ← Back
All Jobs Visible: All your jobs appear in the list, including ones created dynamically in your code.
4

View Logs

All Agent Logs
────────────────────────────────────────────────────
Page 1 of 88 (872 total logs)

❌ [2/3/2025, 4:40:55 PM] ERROR
   Job Name: Nightly User Report
   Job ID:   job_abc123
   Error executing function: Invalid API Key
──────────────────────────────────────────────────
✅ [2/3/2025, 4:40:55 PM] COMPLETE
   Skill Name: customer-service
   Skill ID:   skill_def456
   Tool Name:  search_products
   Duration: 125ms
   Execute function completed
──────────────────────────────────────────────────
5

Navigate

? Navigation:
❯ Next Page →
  ← Previous Page
  🔢 Go to specific page
  🔄 Refresh
  ❌ Exit

​
Use Cases

​
Debug Tool Errors

$ lua logs
→ Filter logs → Skills → Select your skill
→ Look for ❌ ERROR entries
→ Review error messages
→ Fix issues in your code

​
Monitor Performance

$ lua logs
→ Filter logs → Select component type
→ Find ✅ COMPLETE entries
→ Check duration metrics
→ Identify slow operations

​
Verify Tool Execution

$ lua logs
→ Filter logs → Skills → Select your skill
→ Look for 🔍 DEBUG entries
→ Verify tool inputs/outputs

​
Track Webhook Activity

$ lua logs
→ Filter logs → Webhooks → Select your webhook
→ Review webhook execution logs
→ Check request/response data
→ Debug external integrations

​
Monitor Job Execution

$ lua logs
→ Filter logs → Jobs → Select your job
→ View scheduled job execution logs
→ Check for errors or performance issues

​
Example Session

$ lua logs
✅ Authenticated
📊 Viewing logs for agent: myAgent

? What logs do you want to view? 🔎 Filter logs

? Filter by: Jobs

? Select a job: Nightly User Report

All Agent Logs
────────────────────────────────────────────────────────────────────────────────
Page 1 of 12 (120 total logs)

▶️ [11/7/2025, 10:30:00 AM] START
   Job Name: Nightly User Report
   Job ID:   job_abc123
   Duration: 150ms
   Starting job execution...
──────────────────────────────────────────────────────────────────────────────

✅ [11/7/2025, 10:30:05 AM] COMPLETE
   Job Name: Nightly User Report
   Job ID:   job_abc123
   Duration: 5234ms
   Job execution completed successfully
──────────────────────────────────────────────────────────────────────────────

? Navigation: Next Page →

[Shows page 2...]

​
Filtering by Skill

$ lua logs
? What logs do you want to view? 🔎 Filter logs
? Filter by: Skills
? Select a skill: customer-service

All Agent Logs
────────────────────────────────────────────────────────────────────────────────
Page 1 of 25 (250 total logs)

ℹ️ [11/7/2025, 10:31:15 AM] INFO
   Skill Name: customer-service
   Skill ID:   skill_def456
   Tool Name:  search_products
   Fetching products matching query...
──────────────────────────────────────────────────────────────────────────────

✅ [11/7/2025, 10:31:16 AM] COMPLETE
   Skill Name: customer-service
   Skill ID:   skill_def456
   Tool Name:  search_products
   Duration: 89ms
   Found 15 products matching "laptop"
──────────────────────────────────────────────────────────────────────────────

​
Log Entry Details

Each log entry shows you:

​
For Skill Logs

  • Skill Name - Which skill generated the log
  • Skill ID - Unique identifier for the skill
  • Tool Name - Which tool was running (if applicable)
  • Timestamp - When the log was created
  • Log Type - Error, debug, info, warn, start, or complete
  • Message - The actual log message
  • Duration - How long the operation took (for completed operations)

​
For Job Logs

  • Job Name - Which job generated the log
  • Job ID - Unique identifier for the job
  • Timestamp - When the log was created
  • Log Type - Error, debug, info, warn, start, or complete
  • Message - The actual log message
  • Duration - How long the job took to run

​
For Webhook, Preprocessor, and Postprocessor Logs

  • Name - Which component generated the log
  • ID - Unique identifier
  • Timestamp - When the log was created
  • Log Type - Error, debug, info, warn, start, or complete
  • Message - The actual log message
  • Duration - How long the operation took
Tool Information: Tool names are only shown for skill logs, since tools belong to skills.
View the next page of logsDisabled if on last page

​
Best Practices

# Get overview first
lua logs → All agent logs

# Then filter if needed
lua logs → Specific skill logs

# After deploying — generate traffic FIRST
lua push all --force --auto-deploy
lua chat -e production -m "your test message"   # ← generate traffic first
lua logs --type skill --limit 10                # ← now logs exist

lua logs → All agent logs → Refresh periodically

# Issue with specific skill
lua logs → Specific skill logs → Select problem skill

# Focus on errors
# Look for ❌ ERROR entries

# Check operation speed
lua logs → All agent logs

# Note duration on ✅ COMPLETE entries
# Identify slow operations (>1000ms)

​
Troubleshooting

Causes:
  • Skills not deployed yet
  • Agent hasn’t been used
  • Viewing wrong agent
Solution:
lua push  # Deploy skills
lua chat  # Use agent to generate logs
lua logs  # View logs
Try:
  • Navigate through pages using the navigation menu
  • Filter by the specific component (skill, job, etc.)
  • Check the most recent pages first (page 1)
  • Look at the timestamp to find when the error occurred
Use refresh:
? Navigation: 🔄 Refresh
Reloads current page with latest data

​
Integration with Workflow

​
During Development

# Make changes
vim src/tools/MyTool.ts

# Test
lua chat

# Check logs immediately
lua logs
# Look for errors or warnings

​
After Deployment

# Deploy
lua push && lua deploy

# Monitor logs
lua logs
# Watch for errors in production
# Check performance metrics

​
Debugging Issues

# User reports an issue
lua logs
# Find the relevant error in the logs
# Note the timestamp and which component had the error
# Fix the issue in your code
# Deploy the fix
# Monitor logs again to verify the fix

Debugging Loop

Canonical push → test → check flow

lua chat

Test agent (generates logs + auto agent_error probe)

lua test

Test tools locally (no remote logs)

lua push

Deploy skills (required for logs)

​
Next Steps

Test Your Agent

Generate logs to view

Deploy Skills

Push skills to generate logs

Troubleshooting

Common issues and solutions

Production Monitoring

Monitor production environment