lua-cli 3.12.2 → 3.14.0

package/dist/cli/command-definitions.js

@@ -2,7 +2,7 @@
  * Command Definitions
  * Centralized command structure for the CLI
  */
-import { configureCommand, initCommand, destroyCommand, apiKeyCommand, compileCommand, testCommand, pushCommand, deployCommand, chatCommand, chatClearCommand, envCommand, personaCommand, productionCommand, resourcesCommand, adminCommand, evalsCommand, docsCommand, channelsCommand, logsCommand, completionCommand, skillsCommand, webhooksCommand, devicesCommand, jobsCommand, featuresCommand, preprocessorsCommand, postprocessorsCommand, marketplaceCommand, mcpCommand, syncCommand, integrationsCommand, agentsCommand, updateCommand, telemetryCommand, governanceCommand, modelsCommand } from "../commands/index.js";
+import { configureCommand, initCommand, destroyCommand, apiKeyCommand, compileCommand, testCommand, pushCommand, deployCommand, chatCommand, chatClearCommand, envCommand, personaCommand, productionCommand, resourcesCommand, adminCommand, evalsCommand, docsCommand, channelsCommand, logsCommand, completionCommand, skillsCommand, webhooksCommand, devicesCommand, jobsCommand, featuresCommand, preprocessorsCommand, postprocessorsCommand, marketplaceCommand, mcpCommand, syncCommand, integrationsCommand, agentsCommand, updateCommand, telemetryCommand, governanceCommand, modelsCommand, statusCommand, } from '../commands/index.js';
 /**
  * Sets up authentication-related commands.
  *
@@ -15,8 +15,8 @@ import { configureCommand, initCommand, destroyCommand, apiKeyCommand, compileCo
  */
 export function setupAuthCommands(program) {
     const authCommand = program
-        .command("auth")
-        .description("🔐 Authentication management")
+        .command('auth')
+        .description('🔐 Authentication management')
         .addHelpText('after', `
 Examples:
   $ lua auth configure                           Interactive setup (choose API key or email)
@@ -29,11 +29,11 @@ Examples:
   $ lua auth logout --force                      Remove stored credentials without confirmation
 `);
     authCommand
-        .command("configure")
-        .description("Set up your API key")
-        .option("--api-key <key>", "Set API key directly (non-interactive)")
-        .option("--email <email>", "Email address for OTP authentication")
-        .option("--otp <code>", "OTP code received via email (use with --email)")
+        .command('configure')
+        .description('Set up your API key')
+        .option('--api-key <key>', 'Set API key directly (non-interactive)')
+        .option('--email <email>', 'Email address for OTP authentication')
+        .option('--otp <code>', 'OTP code received via email (use with --email)')
         .addHelpText('after', `
 Non-Interactive Modes:
   --api-key <key>                  Set API key directly (for CI/CD or when you have a key from dashboard)
@@ -48,14 +48,14 @@ Examples:
 `)
         .action(configureCommand);
     authCommand
-        .command("logout")
-        .description("Delete your stored API key")
-        .option("--force", "Skip confirmation prompt")
+        .command('logout')
+        .description('Delete your stored API key')
+        .option('--force', 'Skip confirmation prompt')
         .action(destroyCommand);
     authCommand
-        .command("key")
-        .description("Display your stored API key")
-        .option("--force", "Skip confirmation prompt")
+        .command('key')
+        .description('Display your stored API key')
+        .option('--force', 'Skip confirmation prompt')
         .action(apiKeyCommand);
 }
 /**
@@ -65,20 +65,20 @@ Examples:
  */
 export function setupMarketplaceCommands(program) {
     program
-        .command("marketplace [role] [action]")
-        .description("🛍️  Browse, install, and manage marketplace skills")
-        .option("--skill-name <name>", "Skill name (for creator list, installer update/uninstall)")
-        .option("--display-name <name>", "Display name (for creator list/update)")
-        .option("--marketplace-id <id>", "Marketplace skill ID")
-        .option("--version-id <id>", "Version ID (for publish/install)")
-        .option("--changelog <text>", "Changelog for version (for publish)")
-        .option("--env-vars-json <json>", "JSON string with env var metadata (for creator publish)")
-        .option("--env-vars <pairs>", "Comma-separated key=value pairs (for installer)")
-        .option("--query <text>", "Search query (for search)")
-        .option("--page <n>", "Page number (for search)")
-        .option("--limit <n>", "Results per page (for search)")
-        .option("--json", "Output as JSON")
-        .option("--force", "Skip confirmation prompts")
+        .command('marketplace [role] [action]')
+        .description('🛍️  Browse, install, and manage marketplace skills')
+        .option('--skill-name <name>', 'Skill name (for creator list, installer update/uninstall)')
+        .option('--display-name <name>', 'Display name (for creator list/update)')
+        .option('--marketplace-id <id>', 'Marketplace skill ID')
+        .option('--version-id <id>', 'Version ID (for publish/install)')
+        .option('--changelog <text>', 'Changelog for version (for publish)')
+        .option('--env-vars-json <json>', 'JSON string with env var metadata (for creator publish)')
+        .option('--env-vars <pairs>', 'Comma-separated key=value pairs (for installer)')
+        .option('--query <text>', 'Search query (for search)')
+        .option('--page <n>', 'Page number (for search)')
+        .option('--limit <n>', 'Results per page (for search)')
+        .option('--json', 'Output as JSON')
+        .option('--force', 'Skip confirmation prompts')
         .addHelpText('after', `
 Arguments:
   role                   Optional: 'create' or 'install' (prompts if not provided)
@@ -123,17 +123,17 @@ Examples:
 export function setupSkillCommands(program) {
     // Project Setup
     program
-        .command("init")
-        .description("🚀 Initialize a new Lua skill project")
-        .option("--with-examples", "Include example skills, tools, jobs, and webhooks")
-        .option("--agent-id <id>", "Use existing agent by ID (non-interactive)")
-        .option("--agent-name <name>", "Name for new agent (requires --org-id or --org-name)")
-        .option("--org-id <id>", "Use existing organization by ID")
-        .option("--org-name <name>", "Create new organization with this name")
-        .option("--model <model>", "LLM model code to use (e.g. 'openai/gpt-4o')")
-        .option("--force", "Skip confirmations / overwrite existing project")
-        .option("--restore-sources", "Restore project source files from backup (with --agent-id)")
-        .option("--promo-code <code>", "Apply a promo code for bonus credits")
+        .command('init')
+        .description('🚀 Initialize a new Lua skill project')
+        .option('--with-examples', 'Include example skills, tools, jobs, and webhooks')
+        .option('--agent-id <id>', 'Use existing agent by ID (non-interactive)')
+        .option('--agent-name <name>', 'Name for new agent (requires --org-id or --org-name)')
+        .option('--org-id <id>', 'Use existing organization by ID')
+        .option('--org-name <name>', 'Create new organization with this name')
+        .option('--model <model>', "LLM model code to use (e.g. 'openai/gpt-4o')")
+        .option('--force', 'Skip confirmations / overwrite existing project')
+        .option('--restore-sources', 'Restore project source files from backup (with --agent-id)')
+        .option('--promo-code <code>', 'Apply a promo code for bonus credits')
         .addHelpText('after', `
 Non-Interactive Mode:
   --agent-id <id>                              Use existing agent
@@ -157,20 +157,20 @@ Examples:
         .action(initCommand);
     // Development Commands
     program
-        .command("compile")
-        .description("📦 Compile skill to deployable format")
-        .option("--verbose", "Show detailed progress output")
-        .option("--debug", "Enable debug mode with extra verbose logging and temp file preservation")
-        .option("--sync", "Run drift detection check before compiling")
-        .action(compileCommand);
-    program
-        .command("sync")
-        .description("🔄 Sync local code with server state")
-        .option("--check", "Check for drift only, exit code 1 if drift found")
-        .option("--pull", "Pull server state to local without prompting")
-        .option("--accept", "Alias for --pull (kept for backwards compatibility)")
-        .option("--push", "Push local changes to server without prompting")
-        .option("--force", "Skip the local-changes conflict check (use with --pull / --accept)")
+        .command('compile')
+        .description('📦 Compile skill to deployable format')
+        .option('--verbose', 'Show detailed progress output')
+        .option('--debug', 'Enable debug mode with extra verbose logging and temp file preservation')
+        .option('--sync', 'Run drift detection check before compiling')
+        .action((opts) => compileCommand({ ...opts, topLevel: true }));
+    program
+        .command('sync')
+        .description('🔄 Sync local code with server state')
+        .option('--check', 'Check for drift only, exit code 1 if drift found')
+        .option('--pull', 'Pull server state to local without prompting')
+        .option('--accept', 'Alias for --pull (kept for backwards compatibility)')
+        .option('--push', 'Push local changes to server without prompting')
+        .option('--force', 'Skip the local-changes conflict check (use with --pull / --accept)')
         .addHelpText('after', `
 Detects drift between server-deployed state and local code.
 Resolves drift by syncing in either direction.
@@ -200,10 +200,11 @@ Examples:
 `)
         .action((opts) => syncCommand({ ...opts, accept: opts.pull || opts.accept }));
     program
-        .command("test [type]")
-        .description("🧪 Test skills, webhooks, or jobs interactively")
-        .option("--name <name>", "Entity name to test")
-        .option("--input <json>", "JSON input string for testing")
+        .command('test [type]')
+        .description('🧪 Test skills, webhooks, or jobs interactively')
+        .option('--name <name>', 'Entity name to test')
+        .option('--input <json>', 'JSON input string for testing')
+        .option('--json', 'Output result as raw JSON (useful for scripting and piping)')
         .addHelpText('after', `
 Arguments:
   type                   Optional: 'skill', 'webhook', or 'job' (prompts if not provided)
@@ -211,6 +212,7 @@ Arguments:
 Options:
   --name <name>          Entity name to test (non-interactive selection)
   --input <json>         JSON input string for testing (non-interactive input)
+  --json                 Output result as raw JSON instead of formatted inspect output
 
 Examples:
   $ lua test                                          Interactive selection
@@ -220,16 +222,17 @@ Examples:
   $ lua test skill --name mySkill --input '{}'        Test skill with JSON input
   $ lua test webhook --name myWebhook --input '{...}' Test webhook with data
   $ lua test job --name myJob                         Test job execution
+  $ lua test skill --name mySkill --json              Output raw JSON for scripting
 `)
         .action(testCommand);
     // Deployment Commands
     program
-        .command("push [type]")
-        .description("☁️  Push skill, agent, webhook, job, MCP server, or backup to server")
+        .command('push [type]')
+        .description('☁️  Push skill, agent, webhook, job, MCP server, or backup to server')
         .option('--force', 'Skip all confirmation prompts (auto-confirm)')
         .option('--auto-deploy', 'Automatically deploy to production after push')
-        .option("--name <name>", "Entity name to push")
-        .option("--set-version <version>", "Version to set (e.g., 1.0.5)")
+        .option('--name <name>', 'Entity name to push')
+        .option('--set-version <version>', 'Version to set (e.g., 1.0.5)')
         .addHelpText('after', `
 Arguments:
   type                   Optional: 'skill', 'agent', 'persona', 'webhook', 'job', 'preprocessor', 'postprocessor', 'mcp', 'backup', or 'all' (prompts if not provided)
@@ -256,14 +259,14 @@ Examples:
 `)
         .action(pushCommand);
     program
-        .command("deploy [type]")
-        .description("🚀 Deploy a version to production")
-        .option("--name <name>", "Entity name to deploy (non-interactive selection)")
-        .option("--set-version <ver>", "Version to deploy, or 'latest' for newest version")
-        .option("--force", "Skip confirmation prompt")
+        .command('deploy [type]')
+        .description('🚀 Deploy a version to production')
+        .option('--name <name>', 'Entity name to deploy (non-interactive selection)')
+        .option('--set-version <ver>', "Version to deploy, or 'latest' for newest version")
+        .option('--force', 'Skip confirmation prompt')
         // Deprecated aliases kept for backward compatibility
-        .option("--skill-name <name>", "Deprecated: use --name")
-        .option("--skill-version <ver>", "Deprecated: use --set-version")
+        .option('--skill-name <name>', 'Deprecated: use --name')
+        .option('--skill-version <ver>', 'Deprecated: use --set-version')
         .addHelpText('after', `
 Arguments:
   type    Optional: skill | webhook | job | preprocessor | postprocessor | persona | all (prompts if not provided)
@@ -286,15 +289,15 @@ Examples:
         .action(deployCommand);
     // Chat Commands
     const chatCmd = program
-        .command("chat")
-        .description("💬 Interactive chat with your agent")
-        .option("-e, --env <environment>", "Environment: sandbox or production")
-        .option("-m, --message <text>", "Message to send (non-interactive mode)")
-        .option("-b, --batch <messages...>", "Send multiple messages concurrently to test batching")
-        .option("-d, --delay <ms>", "Delay between batch messages in ms (default: 100)")
-        .option("-t, --thread [id]", "Thread ID for conversation scoping. If no ID is provided, a UUID is auto-generated. Displayed at session start so you can reuse it later.")
-        .option("--clear", "Automatically clear chat history when session ends (clears thread if -t is used, otherwise clears all history)")
-        .option("--clear-thread", "Alias for --clear")
+        .command('chat')
+        .description('💬 Interactive chat with your agent')
+        .option('-e, --env <environment>', 'Environment: sandbox or production')
+        .option('-m, --message <text>', 'Message to send (non-interactive mode)')
+        .option('-b, --batch <messages...>', 'Send multiple messages concurrently to test batching')
+        .option('-d, --delay <ms>', 'Delay between batch messages in ms (default: 100)')
+        .option('-t, --thread [id]', 'Thread ID for conversation scoping. If no ID is provided, a UUID is auto-generated. Displayed at session start so you can reuse it later.')
+        .option('--clear', 'Automatically clear chat history when session ends (clears thread if -t is used, otherwise clears all history)')
+        .option('--clear-thread', 'Alias for --clear')
         .addHelpText('after', `
 Examples:
   $ lua chat                                     Start interactive chat session
@@ -311,11 +314,11 @@ Examples:
 `)
         .action(chatCommand);
     chatCmd
-        .command("clear")
-        .description("Clear conversation history")
-        .option("--user <identifier>", "User ID, email, or mobile number of the user whose history to clear")
-        .option("-t, --thread <id>", "Clear a specific thread's history instead of all history")
-        .option("--force", "Skip confirmation prompt")
+        .command('clear')
+        .description('Clear conversation history')
+        .option('--user <identifier>', 'User ID, email, or mobile number of the user whose history to clear')
+        .option('-t, --thread <id>', "Clear a specific thread's history instead of all history")
+        .option('--force', 'Skip confirmation prompt')
         .addHelpText('after', `
 Examples:
   $ lua chat clear                                   Clear history
@@ -334,12 +337,12 @@ Notes:
         .action(chatClearCommand);
     // Configuration Commands
     program
-        .command("env [environment]")
-        .description("⚙️  Manage environment variables")
-        .option("-k, --key <name>", "Environment variable key")
-        .option("-v, --value <value>", "Environment variable value")
-        .option("-d, --delete", "Delete the specified key")
-        .option("--list", "List all environment variables")
+        .command('env [environment]')
+        .description('⚙️  Manage environment variables')
+        .option('-k, --key <name>', 'Environment variable key')
+        .option('-v, --value <value>', 'Environment variable value')
+        .option('-d, --delete', 'Delete the specified key')
+        .option('--list', 'List all environment variables')
         .addHelpText('after', `
 Arguments:
   environment            Optional: 'sandbox', 'staging', or 'production' (prompts if not provided)
@@ -357,10 +360,10 @@ Examples:
 `)
         .action(envCommand);
     program
-        .command("persona [env] [action]")
-        .description("🤖 Manage agent persona")
-        .option("--persona-version <version>", "Version number or 'latest' for deploy")
-        .option("--force", "Skip confirmation prompt")
+        .command('persona [env] [action]')
+        .description('🤖 Manage agent persona')
+        .option('--persona-version <version>', "Version number or 'latest' for deploy")
+        .option('--force', 'Skip confirmation prompt')
         .addHelpText('after', `
 Arguments:
   env                      Optional: 'sandbox', 'staging', or 'production' (prompts if not provided)
@@ -381,8 +384,8 @@ Examples:
 `)
         .action(personaCommand);
     program
-        .command("production [action]")
-        .description("🚀 View and manage production environment")
+        .command('production [action]')
+        .description('🚀 View and manage production environment')
         .addHelpText('after', `
 Arguments:
   action                 Optional: 'overview', 'persona', 'skills', 'env' (prompts if not provided)
@@ -396,9 +399,9 @@ Examples:
 `)
         .action(productionCommand);
     program
-        .command("resources [action]")
-        .description("📚 Manage agent resources and knowledge base")
-        .option("--resource-name <name>", "Resource name")
+        .command('resources [action]')
+        .description('📚 Manage agent resources and knowledge base')
+        .option('--resource-name <name>', 'Resource name')
         .addHelpText('after', `
 Arguments:
   action                   Optional: 'list', 'view', 'delete' (prompts if not provided)
@@ -415,21 +418,12 @@ Examples:
   $ lua resources delete --resource-name "Old Doc" Delete a resource
 `)
         .action(resourcesCommand);
+    program.command('admin').description('🔧 Open Lua Admin Dashboard in browser').action(adminCommand);
+    program.command('evals').description('📊 Open Lua Evaluations Dashboard in browser').action(evalsCommand);
+    program.command('docs').description('📖 Open Lua documentation in browser').action(docsCommand);
     program
-        .command("admin")
-        .description("🔧 Open Lua Admin Dashboard in browser")
-        .action(adminCommand);
-    program
-        .command("evals")
-        .description("📊 Open Lua Evaluations Dashboard in browser")
-        .action(evalsCommand);
-    program
-        .command("docs")
-        .description("📖 Open Lua documentation in browser")
-        .action(docsCommand);
-    program
-        .command("channels [action]")
-        .description("📡 Manage agent communication channels")
+        .command('channels [action]')
+        .description('📡 Manage agent communication channels')
         .addHelpText('after', `
 Arguments:
   action                 Optional: 'list' (prompts if not provided)
@@ -442,14 +436,14 @@ Examples:
 `)
         .action(channelsCommand);
     program
-        .command("logs")
-        .description("📊 View agent and skill logs")
-        .option("--type <type>", "Filter by type: all, skill, job, webhook, preprocessor, postprocessor, user_message, agent_response, mcp, mastra")
-        .option("--name <name>", "Entity name to filter (requires --type)")
-        .option("--user-id <userId>", "Filter logs by user ID")
-        .option("--limit <n>", "Number of logs to show (default: 20)")
-        .option("--page <n>", "Page number for pagination")
-        .option("--json", "Output as JSON (for scripting)")
+        .command('logs')
+        .description('📊 View agent and skill logs')
+        .option('--type <type>', 'Filter by type: all, skill, job, webhook, preprocessor, postprocessor, user_message, agent_response, mcp, mastra')
+        .option('--name <name>', 'Entity name to filter (requires --type)')
+        .option('--user-id <userId>', 'Filter logs by user ID')
+        .option('--limit <n>', 'Number of logs to show (default: 20)')
+        .option('--page <n>', 'Page number for pagination')
+        .option('--json', 'Output as JSON (for scripting)')
         .addHelpText('after', `
 Options:
   --type <type>          Filter by type: all, skill, job, webhook, preprocessor, postprocessor, user_message, agent_response, mcp, mastra
@@ -472,10 +466,10 @@ Examples:
 `)
         .action(logsCommand);
     program
-        .command("skills [actionOrEnv] [action]")
-        .description("⚙️  Manage and view skills")
-        .option("--skill-name <name>", "Skill name")
-        .option("--skill-version <version>", "Version for deploy action (or 'latest')")
+        .command('skills [actionOrEnv] [action]')
+        .description('⚙️  Manage and view skills')
+        .option('--skill-name <name>', 'Skill name')
+        .option('--skill-version <version>', "Version for deploy action (or 'latest')")
         .addHelpText('after', `
 Arguments:
   actionOrEnv              Optional: environment ('sandbox', 'production') or action ('view', 'versions', 'deploy', 'delete')
@@ -496,11 +490,11 @@ Examples:
 `)
         .action(skillsCommand);
     program
-        .command("webhooks [action]")
-        .description("🪝 Manage and view webhooks")
-        .option("--webhook-name <name>", "Webhook name")
-        .option("--webhook-version <version>", "Version for deploy action (or 'latest')")
-        .option("--event <eventType>", "Event type for subscribe/unsubscribe (e.g. message.delivered)")
+        .command('webhooks [action]')
+        .description('🪝 Manage and view webhooks')
+        .option('--webhook-name <name>', 'Webhook name')
+        .option('--webhook-version <version>', "Version for deploy action (or 'latest')")
+        .option('--event <eventType>', 'Event type for subscribe/unsubscribe (e.g. message.delivered)')
         .addHelpText('after', `
 Arguments:
   action                   Optional: 'view', 'versions', 'deploy', 'activate', 'deactivate', 'delete',
@@ -526,13 +520,13 @@ Examples:
 `)
         .action(webhooksCommand);
     program
-        .command("devices [action]")
-        .description("📡 Manage connected devices")
-        .option("--device-name <name>", "Device name")
-        .option("--group <group>", "Filter by device group")
-        .option("--payload <json>", "JSON payload for test/test-trigger", "{}")
-        .option("--timeout <ms>", "Timeout in milliseconds", "30000")
-        .option("--force", "Skip confirmation prompts")
+        .command('devices [action]')
+        .description('📡 Manage connected devices')
+        .option('--device-name <name>', 'Device name')
+        .option('--group <group>', 'Filter by device group')
+        .option('--payload <json>', 'JSON payload for test/test-trigger', '{}')
+        .option('--timeout <ms>', 'Timeout in milliseconds', '30000')
+        .option('--force', 'Skip confirmation prompts')
         .addHelpText('after', `
 Arguments:
   action                   Optional: list, status, enable, disable, remove, test, test-trigger
@@ -558,10 +552,10 @@ Examples:
 `)
         .action(devicesCommand);
     program
-        .command("jobs [action]")
-        .description("⏰ Manage and view scheduled jobs")
-        .option("-i, --job-name <name>", "Job name")
-        .option("-v, --job-version <version>", "Version for deploy action (or 'latest')")
+        .command('jobs [action]')
+        .description('⏰ Manage and view scheduled jobs')
+        .option('-i, --job-name <name>', 'Job name')
+        .option('-v, --job-version <version>', "Version for deploy action (or 'latest')")
         .addHelpText('after', `
 Arguments:
   action               Optional: view, versions, deploy, activate, deactivate, trigger, history, delete
@@ -584,9 +578,9 @@ Examples:
 `)
         .action(jobsCommand);
     program
-        .command("features [action]")
-        .description("🎯 Manage agent features (RAG, webSearch, inquiry)")
-        .option("--feature-name <name>", "Feature name")
+        .command('features [action]')
+        .description('🎯 Manage agent features (RAG, webSearch, inquiry)')
+        .option('--feature-name <name>', 'Feature name')
         .addHelpText('after', `
 Arguments:
   action                   Optional: 'list', 'enable', 'disable', 'view' (prompts if not provided)
@@ -603,10 +597,10 @@ Examples:
 `)
         .action(featuresCommand);
     program
-        .command("preprocessors [action]")
-        .description("📥 Manage message preprocessors")
-        .option("--preprocessor-name <name>", "PreProcessor name")
-        .option("--preprocessor-version <version>", "Version for deploy action (or 'latest')")
+        .command('preprocessors [action]')
+        .description('📥 Manage message preprocessors')
+        .option('--preprocessor-name <name>', 'PreProcessor name')
+        .option('--preprocessor-version <version>', "Version for deploy action (or 'latest')")
         .addHelpText('after', `
 Arguments:
   action                       Optional: 'view', 'versions', 'deploy', 'activate', 'deactivate', 'delete' (prompts if not provided)
@@ -627,10 +621,10 @@ Examples:
 `)
         .action(preprocessorsCommand);
     program
-        .command("postprocessors [action]")
-        .description("📤 Manage response postprocessors")
-        .option("--postprocessor-name <name>", "PostProcessor name")
-        .option("--postprocessor-version <version>", "Version for deploy action (or 'latest')")
+        .command('postprocessors [action]')
+        .description('📤 Manage response postprocessors')
+        .option('--postprocessor-name <name>', 'PostProcessor name')
+        .option('--postprocessor-version <version>', "Version for deploy action (or 'latest')")
         .addHelpText('after', `
 Arguments:
   action                        Optional: 'view', 'versions', 'deploy', 'activate', 'deactivate', 'delete' (prompts if not provided)
@@ -651,9 +645,9 @@ Examples:
 `)
         .action(postprocessorsCommand);
     program
-        .command("mcp [action] [name]")
-        .description("🔌 Manage MCP (Model Context Protocol) servers")
-        .option("--server-name <name>", "MCP server name")
+        .command('mcp [action] [name]')
+        .description('🔌 Manage MCP (Model Context Protocol) servers')
+        .option('--server-name <name>', 'MCP server name')
         .addHelpText('after', `
 Arguments:
   action                 Optional: 'list', 'activate', 'deactivate', or 'delete'
@@ -672,23 +666,23 @@ Examples:
 `)
         .action(mcpCommand);
     program
-        .command("integrations [action] [subaction]")
-        .description("🔗 Connect third-party integrations via Unified.to")
-        .option("--integration <type>", "Integration type (e.g., linear, googlecalendar)")
-        .option("--auth-method <method>", "Authentication method: 'oauth' or 'token'")
-        .option("--scopes <scopes>", "Comma-separated OAuth scopes (or 'all' for all scopes)")
-        .option("--hide-sensitive <bool>", "Hide sensitive data from MCP tools (default: true)")
-        .option("--connection-id <id>", "Connection ID to disconnect or pause/resume")
-        .option("--connection <id>", "Connection ID for trigger")
-        .option("--webhook-id <id>", "Trigger ID to delete/pause/resume")
-        .option("--object <type>", "Object type for webhook (e.g., task_task, calendar_event)")
-        .option("--event <type>", "Event type for webhook: created, updated, or deleted")
-        .option("--hook-url <url>", "Custom webhook URL (default: agent trigger)")
-        .option("--interval <minutes>", "Polling interval for virtual webhooks (60, 120, 240, 480, 720, 1440, 2880)")
-        .option("--triggers <events>", "Comma-separated triggers (e.g., task_task.created,task_task.updated)")
-        .option("--custom-webhook", "Use custom webhook URL instead of agent trigger")
-        .option("--json", "Output as JSON (for info and webhooks events commands)")
-        .option("--reason <text>", "Optional reason for pausing a trigger")
+        .command('integrations [action] [subaction]')
+        .description('🔗 Connect third-party integrations via Unified.to')
+        .option('--integration <type>', 'Integration type (e.g., linear, googlecalendar)')
+        .option('--auth-method <method>', "Authentication method: 'oauth' or 'token'")
+        .option('--scopes <scopes>', "Comma-separated OAuth scopes (or 'all' for all scopes)")
+        .option('--hide-sensitive <bool>', 'Hide sensitive data from MCP tools (default: true)')
+        .option('--connection-id <id>', 'Connection ID to disconnect or pause/resume')
+        .option('--connection <id>', 'Connection ID for trigger')
+        .option('--webhook-id <id>', 'Trigger ID to delete/pause/resume')
+        .option('--object <type>', 'Object type for webhook (e.g., task_task, calendar_event)')
+        .option('--event <type>', 'Event type for webhook: created, updated, or deleted')
+        .option('--hook-url <url>', 'Custom webhook URL (default: agent trigger)')
+        .option('--interval <minutes>', 'Polling interval for virtual webhooks (60, 120, 240, 480, 720, 1440, 2880)')
+        .option('--triggers <events>', 'Comma-separated triggers (e.g., task_task.created,task_task.updated)')
+        .option('--custom-webhook', 'Use custom webhook URL instead of agent trigger')
+        .option('--json', 'Output as JSON (for info and webhooks events commands)')
+        .option('--reason <text>', 'Optional reason for pausing a trigger')
         .addHelpText('after', `
 Arguments:
   action                 Optional: 'connect', 'update', 'list', 'available', 'info', 'disconnect', 'webhooks', or 'mcp'
@@ -747,17 +741,17 @@ MCP Server Examples:
         .action(integrationsCommand);
     // 'lua triggers' — top-level alias for 'lua integrations webhooks' (discoverability)
     program
-        .command("triggers [action]")
-        .description("⚡ Manage integration triggers (alias for: lua integrations webhooks)")
-        .option("--connection-id <id>", "Connection ID to pause/resume all triggers")
-        .option("--connection <id>", "Connection ID for creating a trigger")
-        .option("--webhook-id <id>", "Trigger ID to delete/pause/resume")
-        .option("--object <type>", "Object type for webhook (e.g., task_task, calendar_event)")
-        .option("--event <type>", "Event type: created, updated, or deleted")
-        .option("--hook-url <url>", "Custom webhook URL (default: agent trigger)")
-        .option("--interval <minutes>", "Polling interval for virtual webhooks")
-        .option("--json", "Output as JSON")
-        .option("--reason <text>", "Optional reason for pausing")
+        .command('triggers [action]')
+        .description('⚡ Manage integration triggers (alias for: lua integrations webhooks)')
+        .option('--connection-id <id>', 'Connection ID to pause/resume all triggers')
+        .option('--connection <id>', 'Connection ID for creating a trigger')
+        .option('--webhook-id <id>', 'Trigger ID to delete/pause/resume')
+        .option('--object <type>', 'Object type for webhook (e.g., task_task, calendar_event)')
+        .option('--event <type>', 'Event type: created, updated, or deleted')
+        .option('--hook-url <url>', 'Custom webhook URL (default: agent trigger)')
+        .option('--interval <minutes>', 'Polling interval for virtual webhooks')
+        .option('--json', 'Output as JSON')
+        .option('--reason <text>', 'Optional reason for pausing')
         .addHelpText('after', `
 This is a shortcut for: lua integrations webhooks <action>
 
@@ -782,8 +776,8 @@ Examples:
         return integrationsCommand('webhooks', action || '', opts);
     });
     program
-        .command("completion [shell]")
-        .description("🎯 Generate shell completion script")
+        .command('completion [shell]')
+        .description('🎯 Generate shell completion script')
         .addHelpText('after', `
 Arguments:
   shell                  Optional: 'bash', 'zsh', or 'fish' (shows instructions if not provided)
@@ -797,9 +791,9 @@ Examples:
 `)
         .action(completionCommand);
     program
-        .command("agents")
-        .description("👥 List all organizations and agents you have access to")
-        .option("--json", "Output as JSON")
+        .command('agents')
+        .description('👥 List all organizations and agents you have access to')
+        .option('--json', 'Output as JSON')
         .addHelpText('after', `
 Examples:
   $ lua agents              List all orgs and agents (formatted)
@@ -807,10 +801,10 @@ Examples:
 `)
         .action(agentsCommand);
     program
-        .command("models [action]")
-        .description("🧠 List and manage LLM models for your agent")
-        .option("--model <code>", "Model code for 'set' action (e.g. 'openai/gpt-4o')")
-        .option("--json", "Output as JSON")
+        .command('models [action]')
+        .description('🧠 List and manage LLM models for your agent')
+        .option('--model <code>', "Model code for 'set' action (e.g. 'openai/gpt-4o')")
+        .option('--json', 'Output as JSON')
         .addHelpText('after', `
 Arguments:
   action    Optional: 'list', 'set', or 'unset' (default: list)
@@ -829,16 +823,35 @@ Examples:
 `)
         .action(modelsCommand);
     program
-        .command("update")
-        .description("🔄 Update lua-cli to the latest version")
+        .command('status')
+        .alias('describe')
+        .description('📋 Show full state: env, auth, project, updates, sync state')
+        .option('--json', 'Output as machine-readable JSON')
+        .addHelpText('after', `
+Shows full diagnostics in one shot: CLI version + updates, install method,
+auth state and server reachability, project config, per-primitive sync state
+(local vs deployed), persona/backup status, and telemetry. Degrades gracefully
+when run outside a project or unauthenticated.
+
+Use --json for machine consumption (LLM agents).
+
+Examples:
+  $ lua status            Full status report
+  $ lua describe          Same (alias)
+  $ lua status --json     Stable JSON for automation
+`)
+        .action(statusCommand);
+    program
+        .command('update')
+        .description('🔄 Update lua-cli to the latest version')
         .addHelpText('after', `
 Examples:
   $ lua update               Check for updates and install the latest version
 `)
         .action(updateCommand);
     program
-        .command("telemetry [action]")
-        .description("📊 Manage usage telemetry")
+        .command('telemetry [action]')
+        .description('📊 Manage usage telemetry')
         .addHelpText('after', `
 Arguments:
   action    Optional: 'on', 'off', or 'status' (default: status)
@@ -850,8 +863,8 @@ Examples:
 `)
         .action(telemetryCommand);
     program
-        .command("governance [action]")
-        .description("🛡️  Manage governance for your agent project")
+        .command('governance [action]')
+        .description('🛡️  Manage governance for your agent project')
         .addHelpText('after', `
 Arguments:
   action    Optional: 'add' or 'remove' (default: interactive setup)