Logs Command - Lua CLI

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

Option	Description
`--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
`--json`	Output 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

❌ Error
⚠️ Warn
🔍 Debug
ℹ️ Info
▶️ Start/✅ Complete

Execution errors and failures

Tool execution failures
API errors
Invalid configurations
Stack traces for debugging

Color: Red

Interactive Flow

Choose What to View

📊 Viewing logs for agent: myAgent

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

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

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.

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
──────────────────────────────────────────────────

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.

Next Page →
← Previous Page
🔢 Go to specific page
🔄 Refresh
❌ Exit

View the next page of logsDisabled if on last page

? Enter page number (1-88): 45

Jump directly to any page

Best Practices

Start with All Logs

# Get overview first
lua logs → All agent logs

# Then filter if needed
lua logs → Specific skill logs

Monitor After Deployment

# 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

Debug Specific Issues

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

# Focus on errors
# Look for ❌ ERROR entries

Track Performance

# Check operation speed
lua logs → All agent logs

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

Troubleshooting

No logs available

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

Can't find specific error

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

Logs not updating

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

​Overview

​When to run lua logs

​Non-Interactive Mode

​Post-deploy verification recipe

Filter by Type

See All Your Components

Detailed Information

Color-Coded

​Log Types

​Interactive Flow

​Use Cases

​Debug Tool Errors

​Monitor Performance

​Verify Tool Execution

​Track Webhook Activity

​Monitor Job Execution

​Example Session

​Filtering by Skill

​Log Entry Details

​For Skill Logs

​For Job Logs

​For Webhook, Preprocessor, and Postprocessor Logs

​Navigation Options

​Best Practices

​Troubleshooting

​Integration with Workflow

​During Development

​After Deployment

​Debugging Issues

​Related Commands

Debugging Loop

lua chat

lua test

lua push

​Next Steps

Test Your Agent

Deploy Skills

Troubleshooting

Production Monitoring

Overview

When to run `lua logs`

Non-Interactive Mode

Post-deploy verification recipe

Log Types

Interactive Flow

Use Cases

Debug Tool Errors

Monitor Performance

Verify Tool Execution

Track Webhook Activity

Monitor Job Execution

Example Session

Filtering by Skill

Log Entry Details

For Skill Logs

For Job Logs

For Webhook, Preprocessor, and Postprocessor Logs

Navigation Options

Best Practices

Troubleshooting

Integration with Workflow

During Development

After Deployment

Debugging Issues

Related Commands

Next Steps