plazbot-cli 0.2.25 → 0.3.1

package/src/commands/agent/files.ts

@@ -1,18 +1,30 @@
 import { Command } from 'commander';
 import { Agent } from 'plazbot';
-import { getStoredCredentials } from '../../utils/credentials';
-import { logger } from '../../utils/logger';
-import { createSpinner, createTable, theme, section, statusBadge } from '../../utils/ui';
-import { AgentCommandOptions } from '../../types/agent';
+import { getStoredCredentials } from '../../utils/credentials.js';
+import { logger } from '../../utils/logger.js';
+import { addExamples } from '../../utils/help.js';
+import { createSpinner, createTable, theme, section, statusBadge } from '../../utils/ui.js';
+import { AgentCommandOptions } from '../../types/agent.js';
 
 const filesGroup = new Command('files')
-  .description('Gestionar archivos de la base de conocimiento del agente');
+  .description('Manage files in the agent knowledge base');
+
+addExamples(filesGroup, [
+  { description: 'List the knowledge-base files of an agent',
+    command: 'plazbot agent files list agt_AbcDef123' },
+  { description: 'Add a remote PDF/DOC to the knowledge base',
+    command: 'plazbot agent files add agt_AbcDef123 -u https://files.example.com/manual.pdf -r manual -t docs,onboarding' },
+  { description: 'Check whether a file finished processing',
+    command: 'plazbot agent files status file_AbcDef123' },
+  { description: 'Remove a file from the knowledge base',
+    command: 'plazbot agent files delete agt_AbcDef123 file_AbcDef123' },
+]);
 
 // Listar archivos
 filesGroup.command('list')
-  .description('Listar archivos del agente')
-  .argument('<agentId>', 'ID del agente')
-  .option('--dev', 'Usar ambiente de desarrollo', false)
+  .description('List agent files')
+  .argument('<agentId>', 'Agent ID')
+  .option('--dev', 'Use development environment', false)
   .action(async (agentId: string, options: AgentCommandOptions) => {
     try {
       const credentials = await getStoredCredentials();
@@ -23,31 +35,31 @@ filesGroup.command('list')
         ...(options.dev && { customUrl: "http://localhost:5090" })
       });
 
-      const spinner = createSpinner('Cargando archivos...');
+      const spinner = createSpinner('Loading files...');
       spinner.start();
       const _res: any = await agent.getAgentById({ id: agentId });
       const agentData = _res.agent || _res.data || _res;
       spinner.stop();
 
       const files = (agentData as any).files || [];
-      console.log(section('Archivos - ' + (agentData.name || agentId)));
+      console.log(section('Files - ' + (agentData.name || agentId)));
 
       if (files.length === 0) {
-        console.log(theme.muted('\n  No hay archivos en la base de conocimiento'));
-        console.log(theme.muted('  Usa: plazbot agent files add <agentId> --url <url>\n'));
+        console.log(theme.muted('\n  No files in the knowledge base'));
+        console.log(theme.muted('  Use: plazbot agent files add <agentId> --url <url>\n'));
         return;
       }
 
       const rows = files.map((f: any) => [
         f.fileId || f.id || 'N/A',
-        f.name || f.reference || 'Sin nombre',
+        f.name || f.reference || 'Untitled',
         (f.tags || []).join(', ') || '-',
       ]);
 
-      console.log(createTable(['ID', 'Nombre', 'Tags'], rows));
+      console.log(createTable(['ID', 'Name', 'Tags'], rows));
 
     } catch (error) {
-      const message = error instanceof Error ? error.message : 'Error desconocido';
+      const message = error instanceof Error ? error.message : 'Unknown error';
       logger.error(message);
       process.exit(1);
     }
@@ -55,12 +67,12 @@ filesGroup.command('list')
 
 // Agregar archivo
 filesGroup.command('add')
-  .description('Agregar archivo a la base de conocimiento')
-  .argument('<agentId>', 'ID del agente')
-  .requiredOption('-u, --url <url>', 'URL del archivo (PDF, DOC, DOCX)')
-  .option('-r, --reference <name>', 'Nombre de referencia', 'documento')
-  .option('-t, --tags <tags>', 'Tags separados por coma', '')
-  .option('--dev', 'Usar ambiente de desarrollo', false)
+  .description('Add a file to the knowledge base')
+  .argument('<agentId>', 'Agent ID')
+  .requiredOption('-u, --url <url>', 'File URL (PDF, DOC, DOCX)')
+  .option('-r, --reference <name>', 'Reference name', 'documento')
+  .option('-t, --tags <tags>', 'Comma-separated tags', '')
+  .option('--dev', 'Use development environment', false)
   .action(async (agentId: string, options: any) => {
     try {
       const credentials = await getStoredCredentials();
@@ -71,7 +83,7 @@ filesGroup.command('add')
         ...(options.dev && { customUrl: "http://localhost:5090" })
       });
 
-      const spinner = createSpinner('Subiendo archivo...');
+      const spinner = createSpinner('Uploading file...');
       spinner.start();
 
       const tags = options.tags ? options.tags.split(',').map((t: string) => t.trim()) : [];
@@ -82,16 +94,16 @@ filesGroup.command('add')
         tags,
       });
 
-      spinner.succeed('Archivo agregado');
+      spinner.succeed('File added');
 
       if (result?.fileId) {
         logger.label('File ID', result.fileId);
-        logger.dim('El archivo esta siendo procesado. Verifica con:');
+        logger.dim('The file is being processed. Check status with:');
         logger.dim(`plazbot agent files status ${result.fileId}`);
       }
 
     } catch (error) {
-      const message = error instanceof Error ? error.message : 'Error desconocido';
+      const message = error instanceof Error ? error.message : 'Unknown error';
       logger.error(message);
       process.exit(1);
     }
@@ -99,9 +111,9 @@ filesGroup.command('add')
 
 // Verificar estado
 filesGroup.command('status')
-  .description('Verificar estado de procesamiento de un archivo')
-  .argument('<fileId>', 'ID del archivo')
-  .option('--dev', 'Usar ambiente de desarrollo', false)
+  .description('Check the processing status of a file')
+  .argument('<fileId>', 'File ID')
+  .option('--dev', 'Use development environment', false)
   .action(async (fileId: string, options: AgentCommandOptions) => {
     try {
       const credentials = await getStoredCredentials();
@@ -112,17 +124,17 @@ filesGroup.command('status')
         ...(options.dev && { customUrl: "http://localhost:5090" })
       });
 
-      const spinner = createSpinner('Verificando...');
+      const spinner = createSpinner('Checking...');
       spinner.start();
       const result = await agent.validateFile({ fileId });
       spinner.stop();
 
-      logger.title('Estado del archivo');
+      logger.title('File status');
       logger.label('File ID', fileId);
-      logger.label('Estado', result?.status ? 'Completado' : 'En proceso');
+      logger.label('Status', result?.status ? 'Completed' : 'Processing');
 
     } catch (error) {
-      const message = error instanceof Error ? error.message : 'Error desconocido';
+      const message = error instanceof Error ? error.message : 'Unknown error';
       logger.error(message);
       process.exit(1);
     }
@@ -130,10 +142,10 @@ filesGroup.command('status')
 
 // Eliminar archivo
 filesGroup.command('delete')
-  .description('Eliminar archivo de la base de conocimiento')
-  .argument('<agentId>', 'ID del agente')
-  .argument('<fileId>', 'ID del archivo')
-  .option('--dev', 'Usar ambiente de desarrollo', false)
+  .description('Delete a file from the knowledge base')
+  .argument('<agentId>', 'Agent ID')
+  .argument('<fileId>', 'File ID')
+  .option('--dev', 'Use development environment', false)
   .action(async (agentId: string, fileId: string, options: AgentCommandOptions) => {
     try {
       const credentials = await getStoredCredentials();
@@ -144,13 +156,13 @@ filesGroup.command('delete')
         ...(options.dev && { customUrl: "http://localhost:5090" })
       });
 
-      const spinner = createSpinner('Eliminando archivo...');
+      const spinner = createSpinner('Deleting file...');
       spinner.start();
       await agent.deleteFile({ fileId, agentId });
-      spinner.succeed('Archivo eliminado');
+      spinner.succeed('File deleted');
 
     } catch (error) {
-      const message = error instanceof Error ? error.message : 'Error desconocido';
+      const message = error instanceof Error ? error.message : 'Unknown error';
       logger.error(message);
       process.exit(1);
     }

package/src/commands/agent/get.ts

@@ -1,17 +1,19 @@
 import { Command } from 'commander';
 import { Agent } from 'plazbot';
-import { getStoredCredentials } from '../../utils/credentials';
-import { logger } from '../../utils/logger';
-import { AgentCommandOptions } from '../../types/agent';
+import { getStoredCredentials } from '../../utils/credentials.js';
+import { logger } from '../../utils/logger.js';
+import { addExamples } from '../../utils/help.js';
+import { describeAgentLoadError } from '../../utils/agent-errors.js';
+import { AgentCommandOptions } from '../../types/agent.js';
 import chalk from 'chalk';
 
 export const getCommand = new Command('get')
-  .description('Obtiene información detallada de un agente específico')
-  .argument('<agentId>', 'ID del agente a consultar')
-  .option('-w, --workspace <id>', 'Workspace ID (sobreescribe config local)')
-  .option('-z, --zone <zone>', 'Zona LA o EU (sobreescribe config local)')
-  .option('--raw', 'Mostrar el JSON completo sin formatear', false)
-  .option('--dev', 'Usar ambiente de desarrollo', false)
+  .description('Get detailed information about a specific agent')
+  .argument('<agentId>', 'Agent ID to fetch')
+  .option('-w, --workspace <id>', 'Workspace ID (overrides local config)')
+  .option('-z, --zone <zone>', 'Zone LA or EU (overrides local config)')
+  .option('--raw', 'Show full unformatted JSON', false)
+  .option('--dev', 'Use development environment', false)
   .action(async (agentId: string, options: AgentCommandOptions & { raw: boolean; workspace?: string; zone?: string }) => {
     try {
       const credentials = await getStoredCredentials();
@@ -20,7 +22,7 @@ export const getCommand = new Command('get')
       const effectiveZone = (options.zone?.toUpperCase() === 'EU' ? 'EU' : options.zone?.toUpperCase() === 'LA' ? 'LA' : credentials.zone) as 'LA' | 'EU';
 
       if (options.workspace || options.zone) {
-        console.log(chalk.hex('#FFA726')(`\n  Modo soporte: workspace=${effectiveWorkspace} zona=${effectiveZone}`));
+        console.log(chalk.hex('#FFA726')(`\n  Support mode: workspace=${effectiveWorkspace} zone=${effectiveZone}`));
       }
 
       const agent = new Agent({
@@ -53,23 +55,23 @@ export const getCommand = new Command('get')
 
       console.log();
       console.log(chalk.hex('#4CAF50')('  ┌' + '─'.repeat(58) + '┐'));
-      console.log(chalk.hex('#4CAF50')('  │') + chalk.bold(`  ${agentData.name || 'Agente'}`).padEnd(68) + chalk.hex('#4CAF50')('│'));
+      console.log(chalk.hex('#4CAF50')('  │') + chalk.bold(`  ${agentData.name || 'Agent'}`).padEnd(68) + chalk.hex('#4CAF50')('│'));
       console.log(chalk.hex('#4CAF50')('  │') + chalk.gray(`  ${agentId}`).padEnd(68) + chalk.hex('#4CAF50')('│'));
       console.log(chalk.hex('#4CAF50')('  └' + '─'.repeat(58) + '┘'));
 
       // Informacion basica
-      sectionHeader('Informacion Basica');
+      sectionHeader('Basic Information');
       label('ID', agentData.id);
-      label('Nombre', agentData.name);
-      label('Descripcion', agentData.description);
-      label('Estado', agentData.enable ? chalk.hex('#66BB6A')('Activo') : chalk.hex('#EF5350')('Inactivo'));
-      label('Zona', agentData.zone);
+      label('Name', agentData.name);
+      label('Description', agentData.description);
+      label('Status', agentData.enable ? chalk.hex('#66BB6A')('Active') : chalk.hex('#EF5350')('Inactive'));
+      label('Zone', agentData.zone);
       label('Buffer', agentData.buffer);
       label('Color', agentData.color);
-      label('Pregunta inicial', agentData.question);
-      label('Zona horaria', agentData.timezone);
-      label('Mostrar en chat', agentData.showInChat ? 'Si' : 'No');
-      label('Tool Calling', agentData.useToolCalling ? 'Activado' : 'Desactivado');
+      label('Initial question', agentData.question);
+      label('Timezone', agentData.timezone);
+      label('Show in chat', agentData.showInChat ? 'Yes' : 'No');
+      label('Tool Calling', agentData.useToolCalling ? 'Enabled' : 'Disabled');
 
       // Tags
       if (agentData.tags && agentData.tags.length > 0) {
@@ -87,7 +89,7 @@ export const getCommand = new Command('get')
 
       // Ejemplos
       if (agentData.examples && agentData.examples.length > 0) {
-        sectionHeader('Ejemplos');
+        sectionHeader('Examples');
         agentData.examples.forEach((example: any) => {
           console.log(chalk.white(`  - ${example.value || example}`));
         });
@@ -95,64 +97,64 @@ export const getCommand = new Command('get')
 
       // Instrucciones
       if (agentData.instructions) {
-        sectionHeader('Instrucciones');
+        sectionHeader('Instructions');
         const inst = agentData.instructions;
-        label('Tono', inst.tone);
-        label('Estilo', inst.style);
-        label('Personalidad', inst.personality);
-        label('Objetivo', inst.objective);
-        label('Idioma', inst.language);
-        label('Emojis', inst.emojis ? 'Si' : 'No');
-        label('Formato preferido', inst.preferredFormat);
-        label('Max palabras', inst.maxWords);
+        label('Tone', inst.tone);
+        label('Style', inst.style);
+        label('Personality', inst.personality);
+        label('Objective', inst.objective);
+        label('Language', inst.language);
+        label('Emojis', inst.emojis ? 'Yes' : 'No');
+        label('Preferred format', inst.preferredFormat);
+        label('Max words', inst.maxWords);
         if (inst.avoidTopics && inst.avoidTopics.length > 0) {
-          label('Temas a evitar', inst.avoidTopics.join(', '));
+          label('Topics to avoid', inst.avoidTopics.join(', '));
         }
-        label('Solo responder si sabe', inst.respondOnlyIfKnows ? 'Si' : 'No');
-        label('Saludo', inst.greeting);
+        label('Only respond if known', inst.respondOnlyIfKnows ? 'Yes' : 'No');
+        label('Greeting', inst.greeting);
       }
 
       // Persona
       if (agentData.person) {
         sectionHeader('Persona');
         const p = agentData.person;
-        label('Nombre', p.name);
-        label('Rol', p.role);
-        label('Primera persona', p.speaksInFirstPerson ? 'Si' : 'No');
-        label('Es humano', p.isHuman ? 'Si' : 'No');
+        label('Name', p.name);
+        label('Role', p.role);
+        label('First person', p.speaksInFirstPerson ? 'Yes' : 'No');
+        label('Is human', p.isHuman ? 'Yes' : 'No');
       }
 
       // Fallbacks
       if (agentData.fallbacks) {
         sectionHeader('Fallbacks');
         const fb = agentData.fallbacks;
-        label('Sin respuesta', fb.noAnswer);
-        label('Error de servicio', fb.serviceError);
-        label('No entiende', fb.doNotUnderstand);
+        label('No answer', fb.noAnswer);
+        label('Service error', fb.serviceError);
+        label('Does not understand', fb.doNotUnderstand);
       }
 
       // Reglas
       if (agentData.rules) {
-        sectionHeader('Reglas');
+        sectionHeader('Rules');
         const r = agentData.rules;
-        label('No mencionar precios', r.doNotMentionPrices ? 'Si' : 'No');
-        label('No diagnosticar', r.doNotDiagnose ? 'Si' : 'No');
+        label('Do not mention prices', r.doNotMentionPrices ? 'Yes' : 'No');
+        label('Do not diagnose', r.doNotDiagnose ? 'Yes' : 'No');
         if (r.doNotRespondOutsideHours) {
-          label('Fuera de horario', r.doNotRespondOutsideHours);
+          label('Out of hours', r.doNotRespondOutsideHours);
         }
       }
 
       // Servicios
       if (agentData.services && agentData.services.length > 0) {
-        sectionHeader(`Servicios (${agentData.services.length})`);
+        sectionHeader(`Services (${agentData.services.length})`);
         agentData.services.forEach((svc: any, i: number) => {
-          console.log(chalk.hex('#2196F3')(`  ${i + 1}. ${svc.intent || svc.reference || 'Servicio'}`));
-          label('    Referencia', svc.reference);
-          label('    Habilitado', svc.enabled ? 'Si' : 'No');
-          label('    Metodo', svc.method);
+          console.log(chalk.hex('#2196F3')(`  ${i + 1}. ${svc.intent || svc.reference || 'Service'}`));
+          label('    Reference', svc.reference);
+          label('    Enabled', svc.enabled ? 'Yes' : 'No');
+          label('    Method', svc.method);
           label('    Endpoint', svc.endpoint);
           if (svc.requiredFields && svc.requiredFields.length > 0) {
-            console.log(chalk.gray('    Campos:'));
+            console.log(chalk.gray('    Fields:'));
             svc.requiredFields.forEach((f: any) => {
               console.log(chalk.white(`      - ${f.name} (${f.type}): ${f.description || ''}`));
             });
@@ -162,17 +164,17 @@ export const getCommand = new Command('get')
 
       // Acciones
       if (agentData.actions && agentData.actions.length > 0) {
-        sectionHeader(`Acciones (${agentData.actions.length})`);
+        sectionHeader(`Actions (${agentData.actions.length})`);
         agentData.actions.forEach((act: any, i: number) => {
-          console.log(chalk.hex('#FFA726')(`  ${i + 1}. ${act.intent || act.reference || 'Accion'}`));
-          label('    Referencia', act.reference);
-          label('    Habilitado', act.enabled ? 'Si' : 'No');
+          console.log(chalk.hex('#FFA726')(`  ${i + 1}. ${act.intent || act.reference || 'Action'}`));
+          label('    Reference', act.reference);
+          label('    Enabled', act.enabled ? 'Yes' : 'No');
           if (act.tags && act.tags.length > 0) {
             label('    Tags', act.tags.join(', '));
           }
-          label('    Respuesta', act.responseMessage);
+          label('    Response', act.responseMessage);
           if (act.action && act.action.length > 0) {
-            console.log(chalk.gray('    Sub-acciones:'));
+            console.log(chalk.gray('    Sub-actions:'));
             act.action.forEach((sa: any) => {
               console.log(chalk.white(`      - ${sa.type}: ${sa.value || ''}`));
             });
@@ -182,32 +184,50 @@ export const getCommand = new Command('get')
 
       // Canales
       if (agentData.channels && agentData.channels.length > 0) {
-        sectionHeader(`Canales (${agentData.channels.length})`);
+        sectionHeader(`Channels (${agentData.channels.length})`);
         agentData.channels.forEach((ch: any) => {
-          console.log(chalk.white(`  ${chalk.hex('#22d3ee')(ch.channel || 'canal')}: ${ch.key || ''}`));
+          console.log(chalk.white(`  ${chalk.hex('#22d3ee')(ch.channel || 'channel')}: ${ch.key || ''}`));
         });
       }
 
       // AI Config
       if (agentData.customAIConfig && agentData.aiProviders && agentData.aiProviders.length > 0) {
-        sectionHeader('Modelo IA');
+        sectionHeader('AI Model');
         agentData.aiProviders.forEach((ai: any) => {
-          label('Proveedor', ai.provider);
-          label('Modelo', ai.model);
+          label('Provider', ai.provider);
+          label('Model', ai.model);
         });
       }
 
       console.log();
-      console.log(chalk.gray('  Usa --raw para ver el JSON completo'));
+      console.log(chalk.gray('  Use --raw to see the full JSON'));
       console.log();
 
       if (options.dev) {
-        logger.warning('Ambiente: desarrollo');
+        logger.warning('Environment: development');
       }
 
     } catch (error) {
-      const message = error instanceof Error ? error.message : 'Error desconocido al obtener el agente';
-      logger.error(message);
+      const credentials = await getStoredCredentials().catch(() => null);
+      if (credentials) {
+        logger.error(describeAgentLoadError(error, agentId, credentials, {
+          dev: options.dev,
+          workspaceOverride: options.workspace,
+          zoneOverride: options.zone,
+        }));
+      } else {
+        const message = error instanceof Error ? error.message : 'Unknown error while fetching the agent';
+        logger.error(message);
+      }
       process.exit(1);
     }
-  }); 
+  });
+
+addExamples(getCommand, [
+  { description: 'Show the agent in a human-friendly layout',
+    command: 'plazbot agent get agt_AbcDef123' },
+  { description: 'Dump the full raw JSON (useful for piping to jq)',
+    command: 'plazbot agent get agt_AbcDef123 --raw' },
+  { description: 'Inspect an agent from another workspace (support mode)',
+    command: 'plazbot agent get agt_AbcDef123 -w wok_Other123 -z LA' },
+]);

package/src/commands/agent/index.ts

@@ -1,23 +1,25 @@
 import { Command } from 'commander';
-import { listCommand } from './list';
-import { getCommand } from './get';
-import { deleteCommand } from './delete';
-import { createCommand } from './create';
-import { updateCommand } from './update';
-import { enableCommand } from './enable-widget';
-import { chatCommand } from './chat';
-import { messageCommand } from './on-message';
-import { toolsCommand } from './tools';
-import { aiConfigCommand } from './ai-config';
-import { templatesCommand } from './templates';
-import { copyCommand } from './copy';
-import { filesCommand } from './files';
-import { setCommand } from './set';
-import { monitorCommand } from './monitor';
-import { exportCommand, crossCopyCommand } from './export';
+import { addExamples } from '../../utils/help.js';
+import { listCommand } from './list.js';
+import { getCommand } from './get.js';
+import { deleteCommand } from './delete.js';
+import { createCommand } from './create.js';
+import { updateCommand } from './update.js';
+import { enableCommand } from './enable-widget.js';
+import { chatCommand } from './chat.js';
+import { messageCommand } from './on-message.js';
+import { toolsCommand } from './tools.js';
+import { aiConfigCommand } from './ai-config.js';
+import { templatesCommand } from './templates.js';
+import { copyCommand } from './copy.js';
+import { filesCommand } from './files.js';
+import { setCommand } from './set.js';
+import { monitorCommand } from './monitor.js';
+import { exportCommand, crossCopyCommand } from './export.js';
+import { validateCommand } from './validate.js';
 
 export const agentCommands = new Command('agent')
-  .description('Comandos relacionados con agentes de IA')
+  .description('Commands related to AI agents')
   .addCommand(listCommand)
   .addCommand(getCommand)
   .addCommand(deleteCommand)
@@ -34,4 +36,20 @@ export const agentCommands = new Command('agent')
   .addCommand(setCommand)
   .addCommand(monitorCommand)
   .addCommand(exportCommand)
-  .addCommand(crossCopyCommand);
+  .addCommand(crossCopyCommand)
+  .addCommand(validateCommand);
+
+addExamples(agentCommands, [
+  { description: 'List agents in the active workspace',
+    command: 'plazbot agent list' },
+  { description: 'Chat interactively with an agent',
+    command: 'plazbot agent chat agt_AbcDef123' },
+  { description: 'Create an agent from a JSON template',
+    command: 'plazbot agent create ./agent.json' },
+  { description: 'Export an agent and copy it to another workspace',
+    command: 'plazbot agent cross-copy agt_AbcDef123 --from-workspace wok_Source --to-workspace wok_Target' },
+  { description: 'Monitor activity of an agent in real time',
+    command: 'plazbot agent monitor agt_AbcDef123' },
+  { description: 'Validate a local agent JSON file against the schema',
+    command: 'plazbot agent validate ./agent.json' },
+]);

package/src/commands/agent/list.ts

@@ -1,12 +1,13 @@
 import { Command } from 'commander';
 import { Agent } from 'plazbot';
-import { getStoredCredentials } from '../../utils/credentials';
-import { logger } from '../../utils/logger';
-import { ListAgentsOptions } from '../../types/agent';
+import { getStoredCredentials } from '../../utils/credentials.js';
+import { logger } from '../../utils/logger.js';
+import { addExamples } from '../../utils/help.js';
+import { ListAgentsOptions } from '../../types/agent.js';
 
 export const listCommand = new Command('list')
-  .description('Lista todos los agentes del workspace')
-  .option('--dev', 'Usar ambiente de desarrollo', false)
+  .description('List all agents in the workspace')
+  .option('--dev', 'Use development environment (localhost:5090)', false)
   .action(async (options: ListAgentsOptions) => {
     try {
       // Obtener credenciales guardadas
@@ -24,29 +25,34 @@ export const listCommand = new Command('list')
       const agents = await agent.getAgents();
       
       if (agents.length === 0) {
-        logger.info('No se encontraron agentes en este workspace');
+        logger.info('No agents found in this workspace');
         return;
       }
 
-      logger.info('\nLista de Agentes:');
+      logger.info('\nAgents:');
       logger.doubleDivider();
-      
+
       agents.forEach((a: any, index: number) => {
         logger.info(`${index + 1}. ID: ${a.id}`);
-        logger.info(`   Nombre: ${a.name}`);
-        logger.info(`   Estado: ${a.enable ? 'Activo' : 'Inactivo'}`);
-        logger.info(`   Descripción: ${a.description}`);
-        logger.info(`   Creado: ${a.createdAt ? new Date(a.createdAt).toLocaleString() : 'N/A'}`);
+        logger.info(`   Name: ${a.name}`);
+        logger.info(`   Status: ${a.enable ? 'Active' : 'Inactive'}`);
+        logger.info(`   Description: ${a.description}`);
+        logger.info(`   Created: ${a.createdAt ? new Date(a.createdAt).toLocaleString() : 'N/A'}`);
         logger.divider();
       });
 
       if (options.dev) {
-        logger.warning('Ambiente: desarrollo');
+        logger.warning('Environment: development');
       }
-      
+
     } catch (error) {
-      const message = error instanceof Error ? error.message : 'Error desconocido al listar agentes';
+      const message = error instanceof Error ? error.message : 'Unknown error while listing agents';
       logger.error(message);
       process.exit(1);
     }
-  }); 
+  });
+
+addExamples(listCommand, [
+  { description: 'List every agent in the active workspace',     command: 'plazbot agent list' },
+  { description: 'List against a local backend (dev mode)',      command: 'plazbot agent list --dev' },
+]);