plazbot-cli 0.4.0 → 0.5.0

package/dist/commands/auth/browser-login.js

@@ -3,10 +3,10 @@ import os from 'node:os';
 import axios from 'axios';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
-import { apiBaseUrl, appBaseUrl, saveCredentials } from '../../utils/credentials.js';
+import { apiBaseUrl, appBaseUrl, parseZone, saveCredentials } from '../../utils/credentials.js';
+import { fail, CliError } from '../../utils/output.js';
 import { openBrowser } from '../../utils/open-browser.js';
 import { createSpinner, theme } from '../../utils/ui.js';
-import { logger } from '../../utils/logger.js';
 import { addExamples, addNotes } from '../../utils/help.js';
 const sleep = (ms) => new Promise(r => setTimeout(r, ms));
 /**
@@ -16,16 +16,23 @@ const sleep = (ms) => new Promise(r => setTimeout(r, ms));
 export async function runBrowserLogin(options) {
     let zone;
     if (options.zone) {
-        zone = options.zone.toUpperCase() === 'EU' ? 'EU' : 'LA';
+        const parsed = parseZone(options.zone);
+        if (!parsed) {
+            throw new CliError(`Invalid zone "${options.zone}".`, 'invalid_zone', 'Use --zone LA (Americas) or --zone EU (Europe).');
+        }
+        zone = parsed;
     }
     else {
+        if (!process.stdin.isTTY) {
+            throw new CliError('The zone is required without an interactive terminal.', 'missing_zone', 'Pass --zone LA or --zone EU.');
+        }
         const answer = await inquirer.prompt([{
                 type: 'list',
                 name: 'zone',
-                message: '¿Dónde creaste tu cuenta de Plazbot?',
+                message: 'Where did you create your Plazbot account?',
                 choices: [
-                    { name: 'América  (appla.plazbot.com)', value: 'LA' },
-                    { name: 'Europa   (appeu.plazbot.com)', value: 'EU' },
+                    { name: 'Americas (appla.plazbot.com)', value: 'LA' },
+                    { name: 'Europe   (appeu.plazbot.com)', value: 'EU' },
                 ],
             }]);
         zone = answer.zone;
@@ -38,22 +45,22 @@ export async function runBrowserLogin(options) {
         data = start.data?.success ? start.data?.data : undefined;
     }
     catch (error) {
-        throw new Error(`No se pudo conectar con Plazbot (${axios.isAxiosError(error) ? error.message : 'error de red'}).`);
+        throw new CliError(`Could not reach Plazbot (${axios.isAxiosError(error) ? error.message : 'network error'}).`, 'network_error', 'Check your internet connection and try again.');
     }
     if (!data?.deviceCode) {
-        throw new Error('No se pudo iniciar el login. Inténtalo de nuevo en unos segundos.');
+        throw new CliError('Could not start the login.', 'login_start_failed', 'Try again in a few seconds.');
     }
     const url = `${appBaseUrl(zone, dev)}/cli/authorize?code=${encodeURIComponent(data.userCode)}&r=${encodeURIComponent(data.requestToken)}`;
     console.log();
-    console.log(`  Tu código de verificación: ${chalk.bold.hex('#22d3ee')(data.userCode)}`);
+    console.log(`  Your verification code: ${chalk.bold.hex('#22d3ee')(data.userCode)}`);
     console.log();
     const opened = options.browser !== false && openBrowser(url);
     console.log(theme.muted(opened
-        ? '  Abrimos tu navegador. Si no se abrió, entra a:'
-        : '  Abre este link en tu navegador:'));
+        ? '  We opened your browser. If it did not open, go to:'
+        : '  Open this link in your browser:'));
     console.log(`  ${chalk.underline(url)}`);
     console.log();
-    const spinner = createSpinner('Esperando la autorización en el navegador... (Ctrl+C para cancelar)');
+    const spinner = createSpinner('Waiting for authorization in the browser... (Ctrl+C to cancel)');
     spinner.start();
     const deadline = Date.now() + data.expiresIn * 1000;
     const intervalMs = Math.max(2, data.interval || 3) * 1000;
@@ -72,8 +79,8 @@ export async function runBrowserLogin(options) {
         }
     }
     if (!approved) {
-        spinner.fail('El código venció sin autorización.');
-        throw new Error('Ejecuta plazbot login otra vez.');
+        spinner.fail('The code expired before it was authorized.');
+        throw new CliError('Login timed out.', 'login_expired', "Run 'plazbot login' again.");
     }
     const credentials = {
         apiKey: approved.apiKey,
@@ -85,37 +92,36 @@ export async function runBrowserLogin(options) {
         source: 'login',
     };
     await saveCredentials(credentials);
-    spinner.succeed(`Sesión iniciada en ${chalk.bold(approved.workspaceName || approved.workspaceId)} (${credentials.zone})`);
+    spinner.succeed(`Signed in to ${chalk.bold(approved.workspaceName || approved.workspaceId)} (${credentials.zone})`);
     if (approved.email)
-        console.log(theme.muted(`  Cuenta: ${approved.email}`));
+        console.log(theme.muted(`  Account: ${approved.email}`));
     console.log();
     return credentials;
 }
 export const browserLoginCommand = new Command('login')
-    .description('Inicia sesión desde el navegador (sin copiar API key)')
-    .option('-z, --zone <zone>', 'Zona donde creaste tu cuenta: LA (América) o EU (Europa)')
-    .option('--no-browser', 'No abrir el navegador automáticamente (solo mostrar el link)')
-    .option('--dev', 'Usar el entorno de desarrollo local', false)
+    .description('Sign in with your browser (no API key to copy)')
+    .option('-z, --zone <zone>', 'Zone where you created your account: LA (Americas) or EU (Europe)')
+    .option('--no-browser', 'Do not open the browser, only print the link')
+    .option('--dev', 'Use development environment', false)
     .action(async (options) => {
     try {
         await runBrowserLogin(options);
-        console.log(theme.muted('  Siguiente paso:'));
-        console.log(`    ${chalk.cyan('plazbot whatsapp setup')}     ${theme.muted('Conecta WhatsApp y envía tu primer mensaje')}`);
-        console.log(`    ${chalk.cyan('plazbot whoami')}             ${theme.muted('Ver la sesión activa')}`);
-        console.log(`    ${chalk.cyan('plazbot workspace list')}     ${theme.muted('Cambiar de workspace')}`);
+        console.log(theme.muted('  Next steps:'));
+        console.log(`    ${chalk.cyan('plazbot whatsapp setup')}     ${theme.muted('Connect WhatsApp and send your first message')}`);
+        console.log(`    ${chalk.cyan('plazbot whoami')}             ${theme.muted('Show the active session')}`);
+        console.log(`    ${chalk.cyan('plazbot workspace list')}     ${theme.muted('Switch workspace')}`);
         console.log();
     }
     catch (error) {
-        logger.error(error instanceof Error ? error.message : 'Error desconocido');
-        process.exit(1);
+        fail(error);
     }
 });
 addExamples(browserLoginCommand, [
-    { description: 'Iniciar sesión (pregunta la zona y abre el navegador)', command: 'plazbot login' },
-    { description: 'Cuenta en Europa', command: 'plazbot login --zone EU' },
-    { description: 'Servidor sin navegador: solo muestra el link', command: 'plazbot login --no-browser' },
+    { description: 'Sign in (asks for the zone and opens the browser)', command: 'plazbot login' },
+    { description: 'Account in Europe', command: 'plazbot login --zone EU' },
+    { description: 'Server without a browser: only print the link', command: 'plazbot login --no-browser' },
 ]);
 addNotes(browserLoginCommand, [
-    'En CI o servidores usa variables de entorno: PLAZBOT_API_KEY, PLAZBOT_WORKSPACE_ID y PLAZBOT_ZONE.',
-    'Puedes revocar el acceso en el panel: Configuración → Developer.',
+    'In CI or servers use environment variables: PLAZBOT_API_KEY, PLAZBOT_WORKSPACE_ID and PLAZBOT_ZONE (or plazbot init).',
+    'You can revoke access in the app: Settings → Developer.',
 ]);

package/dist/commands/auth/login.js

@@ -1,64 +1,68 @@
 import { Command } from 'commander';
-import { saveCredentials } from '../../utils/credentials.js';
+import chalk from 'chalk';
+import { parseZone, saveCredentials } from '../../utils/credentials.js';
 import { logger } from '../../utils/logger.js';
-import { addExamples } from '../../utils/help.js';
+import { addExamples, addNotes } from '../../utils/help.js';
+import { jsonOption, isJsonMode, printJson, fail, CliError } from '../../utils/output.js';
 export const loginCommand = new Command('init')
-    .description('Guarda una API key manualmente (para CI; lo normal es plazbot login)')
-    .option('-e, --email <email>', 'User email (optional)')
-    .requiredOption('-k, --api-key <apiKey>', 'User API key')
-    .requiredOption('-w, --workspace <workspace>', 'Workspace ID')
-    .requiredOption('-z, --zone <zone>', 'Zone (LA or EU)')
-    .option('-u, --user-id <userId>', 'User ID for x-user-id (optional, used by studio)')
+    .description('Save an API key manually (for CI; use plazbot login on your machine)')
+    .requiredOption('-k, --api-key <apiKey>', 'API key (Settings → Developer)')
+    .requiredOption('-w, --workspace <workspaceId>', 'Workspace ID')
+    .requiredOption('-z, --zone <zone>', 'Zone where the account lives: LA (Americas) or EU (Europe)')
+    .option('-e, --email <email>', 'Account email (optional, shown by whoami)')
+    .option('-u, --user-id <userId>', 'User ID (optional, needed by studio and workspace list)')
+    .addOption(jsonOption())
     .option('--dev', 'Use development environment', false)
     .action(async (options) => {
     try {
-        // Banner de bienvenida
-        logger.info('┌' + '─'.repeat(70) + '┐');
-        logger.info('│' + ' Welcome to Plazbot CLI'.padEnd(69) + '│');
-        logger.info('│' + ''.padEnd(69) + '│');
-        logger.info('│' + ' With this tool you can:'.padEnd(69) + '│');
-        logger.info('│' + '   Create and update agents'.padEnd(69) + '│');
-        logger.info('│' + '   Manage configurations'.padEnd(69) + '│');
-        logger.info('│' + '   Interact with your agents'.padEnd(69) + '│');
-        logger.info('│' + '   Activate all their capabilities'.padEnd(69) + '│');
-        logger.info('└' + '─'.repeat(70) + '┘\n');
+        const zone = parseZone(options.zone);
+        if (!zone) {
+            throw new CliError(`Invalid zone "${options.zone}".`, 'invalid_zone', 'Use -z LA (Americas) or -z EU (Europe).');
+        }
+        const apiKey = options.apiKey.trim();
+        const workspace = options.workspace.trim();
+        if (!apiKey)
+            throw new CliError('API key cannot be empty.', 'missing_api_key', 'Pass it with -k, --api-key <apiKey>.');
+        if (!workspace)
+            throw new CliError('Workspace ID cannot be empty.', 'missing_workspace', 'Pass it with -w, --workspace <workspaceId>.');
         await saveCredentials({
             email: options.email || '',
-            apiKey: options.apiKey,
-            workspace: options.workspace,
-            zone: options.zone,
-            userId: options.userId
+            apiKey,
+            workspace,
+            zone,
+            userId: options.userId,
+            source: 'init',
         });
-        logger.success('Configuration saved successfully:');
+        if (isJsonMode()) {
+            printJson({ workspace, zone });
+            return;
+        }
+        logger.success('Credentials saved to ~/.plazbot/config.json');
+        logger.label('Workspace', workspace);
+        logger.label('Zone', zone === 'EU' ? 'Europe (EU)' : 'Americas (LA)');
         if (options.email)
             logger.label('Email', options.email);
-        logger.label('Workspace', options.workspace);
-        logger.label('Zone', options.zone);
         if (options.userId)
-            logger.label('UserId', options.userId);
-        logger.title('You can start by using the following commands');
-        logger.dim('plazbot agent list        - View your agents');
-        logger.dim('plazbot agent templates   - Create an agent from a template');
-        logger.dim('plazbot agent chat        - Chat with an agent');
-        logger.dim('plazbot --help            - View all commands');
+            logger.label('User ID', options.userId);
+        console.log();
+        logger.dim('The key is not verified yet. Check it with:');
+        console.log(`    ${chalk.cyan('plazbot agent list')}     ${chalk.gray('List your agents (fails if the key or zone is wrong)')}`);
+        console.log(`    ${chalk.cyan('plazbot whoami')}         ${chalk.gray('Show the active session')}`);
         console.log();
-        if (options.dev) {
-            logger.warning('Environment: development');
-        }
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : 'Unknown error';
-        logger.error(message);
-        process.exit(1);
+        fail(error);
     }
 });
 addExamples(loginCommand, [
-    { description: 'Save credentials for a LA workspace',
-        command: 'plazbot init -e you@company.com -k <jwt> -w wok_AbcDef123 -z LA' },
-    { description: 'Save credentials for an EU workspace',
-        command: 'plazbot init -k <jwt> -w wok_AbcDef123 -z EU' },
-    { description: 'Include userId (used by studio support mode)',
-        command: 'plazbot init -k <jwt> -w wok_AbcDef123 -z LA -u usr_AbcDef123' },
-    { description: 'Target the local backend (dev mode)',
-        command: 'plazbot init -k <jwt> -w wok_AbcDef123 -z LA --dev' },
+    { description: 'Save credentials for a workspace in the Americas',
+        command: 'plazbot init -k <apiKey> -w wok_AbcDef123 -z LA' },
+    { description: 'Save credentials for a workspace in Europe',
+        command: 'plazbot init -k <apiKey> -w wok_AbcDef123 -z EU -e you@company.com' },
+    { description: 'Include the user ID (needed by studio and workspace list)',
+        command: 'plazbot init -k <apiKey> -w wok_AbcDef123 -z LA -u usr_AbcDef123' },
+]);
+addNotes(loginCommand, [
+    'On your own machine prefer plazbot login (browser, no key to copy).',
+    'In CI you can skip the file entirely: set PLAZBOT_API_KEY, PLAZBOT_WORKSPACE_ID and PLAZBOT_ZONE.',
 ]);

package/dist/commands/auth/logout.js

@@ -1,26 +1,35 @@
 import { Command } from 'commander';
 import { removeCredentials } from '../../utils/credentials.js';
 import { logger } from '../../utils/logger.js';
-import { addExamples } from '../../utils/help.js';
+import { addExamples, addNotes } from '../../utils/help.js';
+import { jsonOption, isJsonMode, printJson, fail } from '../../utils/output.js';
 export const logoutCommand = new Command('logout')
     .alias('finish')
-    .description('Cierra la sesión local (borra ~/.plazbot/config.json)')
+    .description('Sign out on this machine (removes ~/.plazbot/config.json)')
+    .addOption(jsonOption())
     .option('--dev', 'Use development environment', false)
-    .action(async (options) => {
+    .action(async (_options) => {
     try {
         await removeCredentials();
-        logger.success('You have been signed out successfully');
-        if (options.dev) {
-            logger.warning('Environment: development');
+        if (isJsonMode()) {
+            printJson({ loggedOut: true });
+            return;
         }
+        logger.success('Signed out');
+        logger.dim('The token stays valid until you revoke it in Settings → Developer.');
+        if (process.env.PLAZBOT_API_KEY) {
+            logger.warning('PLAZBOT_API_KEY is still set in your environment, so commands keep working with it.');
+        }
+        console.log();
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : 'Unknown error while signing out';
-        logger.error(message);
-        process.exit(1);
+        fail(error);
     }
 });
 addExamples(logoutCommand, [
-    { description: 'Remove the local configuration (~/.plazbot/config.json)',
-        command: 'plazbot logout' },
+    { description: 'Sign out on this machine', command: 'plazbot logout' },
+    { description: 'Sign out from a script', command: 'plazbot logout --json' },
+]);
+addNotes(logoutCommand, [
+    'Logging out only deletes the local session. Revoke the token in Settings → Developer to invalidate it.',
 ]);

package/dist/commands/auth/status.js

@@ -1,30 +1,54 @@
 import { Command } from 'commander';
-import { getStoredCredentials } from '../../utils/credentials.js';
+import { apiBaseUrl, getStoredCredentials } from '../../utils/credentials.js';
 import { logger } from '../../utils/logger.js';
 import { addExamples } from '../../utils/help.js';
+import { jsonOption, isJsonMode, printJson, fail, CliError } from '../../utils/output.js';
 import { section } from '../../utils/ui.js';
+const SOURCE_LABELS = {
+    login: 'Browser login (plazbot login)',
+    init: 'API key (plazbot init)',
+    env: 'Environment variables (PLAZBOT_API_KEY)',
+};
 export const statusCommand = new Command('whoami')
     .alias('status')
-    .description('Muestra la sesión activa (cuenta, workspace, zona)')
+    .description('Show the active session (account, workspace and zone)')
+    .addOption(jsonOption())
     .action(async () => {
     try {
-        const credentials = await getStoredCredentials();
+        let credentials;
+        try {
+            credentials = await getStoredCredentials();
+        }
+        catch {
+            throw new CliError('You are not signed in.', 'not_signed_in', "Run 'plazbot login' to sign in.");
+        }
+        const api = apiBaseUrl(credentials.zone);
+        if (isJsonMode()) {
+            printJson({
+                email: credentials.email || null,
+                workspace: credentials.workspace,
+                workspaceName: credentials.workspaceName || null,
+                zone: credentials.zone,
+                api,
+                source: credentials.source || 'init',
+            });
+            return;
+        }
         console.log(section('Active session'));
         if (credentials.email)
             logger.label('Email', credentials.email);
         logger.label('Workspace', credentials.workspaceName ? `${credentials.workspaceName} (${credentials.workspace})` : credentials.workspace);
-        logger.label('Zone', credentials.zone === 'LA' ? 'Latin America (LA)' : 'Europe (EU)');
-        logger.label('API', credentials.zone === 'EU' ? 'https://apieu.plazbot.com' : 'https://api.plazbot.com');
-        if (credentials.source === 'env')
-            logger.label('Origen', 'variables de entorno (PLAZBOT_API_KEY)');
+        logger.label('Zone', credentials.zone === 'EU' ? 'Europe (EU)' : 'Americas (LA)');
+        logger.label('API', api);
+        logger.label('Source', SOURCE_LABELS[credentials.source || 'init'] || credentials.source || 'init');
         console.log();
     }
-    catch {
-        logger.error("No hay una sesión activa. Ejecuta 'plazbot login' para iniciar sesión.");
-        process.exit(1);
+    catch (error) {
+        fail(error);
     }
 });
 addExamples(statusCommand, [
-    { description: 'Show the active workspace, email and zone',
-        command: 'plazbot whoami' },
+    { description: 'Show the active workspace, email and zone', command: 'plazbot whoami' },
+    { description: 'Get the session as JSON', command: 'plazbot whoami --json' },
+    { description: 'Get only the workspace ID', command: "plazbot whoami --json | jq -r '.workspace'" },
 ]);

package/dist/commands/auth/workspace.js

@@ -4,11 +4,12 @@ import chalk from 'chalk';
 import { apiBaseUrl, getStoredCredentials, saveCredentials } from '../../utils/credentials.js';
 import { createSpinner, createTable, theme } from '../../utils/ui.js';
 import { logger } from '../../utils/logger.js';
-import { addExamples } from '../../utils/help.js';
+import { addExamples, addNotes } from '../../utils/help.js';
+import { jsonOption, isJsonMode, printJson, fail, CliError } from '../../utils/output.js';
 async function fetchWorkspaces(dev) {
     const creds = await getStoredCredentials();
     if (!creds.userId) {
-        throw new Error("Esta sesión no tiene usuario asociado. Vuelve a iniciar sesión con 'plazbot login'.");
+        throw new CliError('This session has no user attached, so workspaces cannot be listed.', 'missing_user_id', "Sign in again with 'plazbot login'.");
     }
     const res = await axios.get(`${apiBaseUrl(creds.zone, dev)}/api/workspace/workspaceByUserId/${encodeURIComponent(creds.userId)}`, {
         headers: { Authorization: `Bearer ${creds.apiKey}`, 'x-workspace-id': creds.workspace },
@@ -18,56 +19,89 @@ async function fetchWorkspaces(dev) {
         .map((w) => ({ id: w.data.id, name: w.data.name || w.data.id }));
 }
 const listCommand = new Command('list')
-    .description('Lista tus workspaces')
-    .option('--json', 'Salida en JSON')
-    .option('--dev', 'Usar el entorno de desarrollo local', false)
+    .description('List the workspaces you belong to (same zone as the session)')
+    .addOption(jsonOption())
+    .option('--dev', 'Use development environment', false)
     .action(async (options) => {
     try {
         const creds = await getStoredCredentials();
-        const spinner = options.json ? null : createSpinner('Cargando workspaces...').start();
-        const items = await fetchWorkspaces(options.dev);
-        spinner?.stop();
-        if (options.json) {
-            console.log(JSON.stringify(items.map(w => ({ ...w, active: w.id === creds.workspace })), null, 2));
+        const spinner = createSpinner('Loading workspaces...').start();
+        let items;
+        try {
+            items = await fetchWorkspaces(options.dev);
+        }
+        finally {
+            spinner.stop();
+        }
+        if (isJsonMode()) {
+            printJson(items.map(w => ({ ...w, active: w.id === creds.workspace })));
+            return;
+        }
+        if (items.length === 0) {
+            logger.dim('No workspaces found for this account.');
             return;
         }
         console.log(createTable(['', 'Workspace', 'ID'], items.map(w => [
             w.id === creds.workspace ? chalk.green('●') : ' ', w.name, theme.muted(w.id),
         ])));
-        console.log(theme.muted(`  Cambia con: plazbot workspace use <id>`));
+        console.log(theme.muted('  Switch with: plazbot workspace use <workspaceId>'));
     }
     catch (error) {
-        logger.error(error instanceof Error ? error.message : 'Error desconocido');
-        process.exit(1);
+        fail(error);
     }
 });
 const useCommand = new Command('use')
-    .description('Cambia el workspace activo')
-    .argument('<workspaceId>', 'ID del workspace (ver plazbot workspace list)')
-    .option('--dev', 'Usar el entorno de desarrollo local', false)
+    .description('Switch the active workspace')
+    .argument('<workspaceId>', 'Workspace ID (see plazbot workspace list)')
+    .addOption(jsonOption())
+    .option('--dev', 'Use development environment', false)
     .action(async (workspaceId, options) => {
     try {
         const creds = await getStoredCredentials();
         if (creds.source === 'env') {
-            throw new Error('La sesión viene de variables de entorno; cambia PLAZBOT_WORKSPACE_ID.');
+            throw new CliError('The session comes from environment variables.', 'env_session', 'Change PLAZBOT_WORKSPACE_ID instead.');
+        }
+        const spinner = createSpinner('Checking access...').start();
+        let items;
+        try {
+            items = await fetchWorkspaces(options.dev);
+        }
+        finally {
+            spinner.stop();
+        }
+        const target = items.find(w => w.id === workspaceId.trim());
+        if (!target) {
+            throw new CliError(`You do not have access to workspace ${workspaceId}.`, 'workspace_not_found', "See your workspaces with 'plazbot workspace list'.");
         }
-        const items = await fetchWorkspaces(options.dev);
-        const target = items.find(w => w.id === workspaceId);
-        if (!target)
-            throw new Error(`No tienes acceso al workspace ${workspaceId}.`);
         await saveCredentials({ ...creds, workspace: target.id, workspaceName: target.name });
-        logger.success(`Workspace activo: ${target.name}`);
+        if (isJsonMode()) {
+            printJson({ id: target.id, name: target.name, active: true });
+            return;
+        }
+        logger.success(`Active workspace: ${target.name} ${theme.muted(`(${target.id})`)}`);
+        console.log();
     }
     catch (error) {
-        logger.error(error instanceof Error ? error.message : 'Error desconocido');
-        process.exit(1);
+        fail(error);
     }
 });
 export const workspaceCommand = new Command('workspace')
-    .description('Ver y cambiar el workspace activo')
+    .description('List and switch workspaces')
     .addCommand(listCommand)
     .addCommand(useCommand);
 addExamples(workspaceCommand, [
-    { description: 'Listar tus workspaces', command: 'plazbot workspace list' },
-    { description: 'Cambiar el workspace activo', command: 'plazbot workspace use wok_AbcDef123' },
+    { description: 'List your workspaces', command: 'plazbot workspace list' },
+    { description: 'Switch the active workspace', command: 'plazbot workspace use wok_AbcDef123' },
+    { description: 'List workspaces as JSON', command: 'plazbot workspace list --json' },
+]);
+addExamples(listCommand, [
+    { description: 'List your workspaces (● marks the active one)', command: 'plazbot workspace list' },
+    { description: 'Get them as JSON', command: 'plazbot workspace list --json' },
+]);
+addExamples(useCommand, [
+    { description: 'Switch the active workspace', command: 'plazbot workspace use wok_AbcDef123' },
+    { description: 'Switch from a script', command: 'plazbot workspace use wok_AbcDef123 --json' },
+]);
+addNotes(workspaceCommand, [
+    'Only workspaces in the zone of the current session are listed. For another zone, run plazbot login --zone EU (or LA).',
 ]);