plazbot-cli 0.4.0 → 0.5.0

package/README.md

@@ -1,159 +1,115 @@
 # Plazbot CLI
 
-CLI oficial de Plazbot: conecta WhatsApp, envía mensajes, gestiona agentes IA y despliega workers desde tu terminal.
-
-## Empieza en 3 comandos
+The official Plazbot CLI: connect WhatsApp, send messages, manage AI agents and deploy workers from your terminal.
 
 ```bash
 npm i -g plazbot-cli
-plazbot login            # abre el navegador y autorizas (sin copiar API key)
-plazbot whatsapp setup   # conecta tu número y prueba tu primer mensaje
+plazbot login            # sign in from the browser (no API key to copy)
+plazbot whatsapp setup   # connect a number and send your first message
 ```
 
-`plazbot whatsapp setup` te guía paso a paso: conecta un número (WhatsApp API o tu
-WhatsApp Business actual), te pide escribir "hola" desde tu celular, responde por la API
-y registra tu webhook. Al final te da el código para tu app.
+Requires Node.js 18.17 or later. Full documentation: https://developers.plazbot.com/cli
 
-### Sesión
+## Session
 
 ```bash
-plazbot login [--zone LA|EU] [--no-browser]   # login por navegador
-plazbot whoami                                # sesión activa
-plazbot workspace list | use <id>             # cambiar de workspace
-plazbot logout
+plazbot login [--zone LA|EU] [--no-browser]   # browser sign-in
+plazbot whoami                                # active account, workspace and zone
+plazbot workspace list                        # your workspaces (● = active)
+plazbot workspace use wok_AbcDef123           # switch workspace
+plazbot logout                                # remove the local session
 ```
 
-En CI o servidores usa variables de entorno en lugar de `plazbot login`:
-`PLAZBOT_API_KEY`, `PLAZBOT_WORKSPACE_ID` y `PLAZBOT_ZONE` (`LA` o `EU`).
-
-### WhatsApp
+In CI or on servers, use environment variables instead of `plazbot login`:
 
 ```bash
-plazbot whatsapp setup                                         # asistente de primer uso
-plazbot whatsapp connect [--business]                          # conectar un número
-plazbot whatsapp send-message --to 51912345678 --message "Hola"
-plazbot whatsapp send-template --phone 51912345678 --template welcome --var 1=Ana
-plazbot whatsapp register-webhook --number 51966446311 --url https://tu-app.com/whatsapp
+export PLAZBOT_API_KEY=...
+export PLAZBOT_WORKSPACE_ID=wok_...
+export PLAZBOT_ZONE=LA   # or EU
 ```
 
-Documentación: https://developers.plazbot.com/cli
+## WhatsApp
 
-## Más funciones
+Phone numbers always go in `-p, --phone`, in any international format (`+51912345678`, `"+51 912 345 678"`, `0051912345678`).
 
-🧠 **Agent Studio (REPL interactivo, estilo Claude Code)**
 ```bash
-# Modo REPL completo (TUI con Ink)
-plazbot studio
-
-# One-shot (resultado a stdout, sin TUI)
-plazbot studio ask "lista mis agentes"
-plazbot studio -m "crea un agente de ventas para WhatsApp"
-
-# NDJSON crudo de los chunks SSE
-plazbot studio ask "diagnostica el agente xyz" --json
-
-# Backend local
-plazbot studio --dev
+plazbot whatsapp connect [--business]
+plazbot whatsapp send-message -p +51912345678 -m "Hello"
+plazbot whatsapp send-template -p +51912345678 -t welcome --var name=Anna
+plazbot whatsapp broadcast -t welcome --phones ./numbers.txt --dry-run
+plazbot whatsapp chat -p +51912345678
+plazbot whatsapp assign -p +51912345678 -a age_AbcDef123
+plazbot whatsapp channels
+plazbot whatsapp register-webhook -p +51912345678 -u https://your-app.com/whatsapp
 ```
 
-Slash commands: `/help`, `/clear`, `/quit`, `/agents`, `/load <id>`, `/save`,
-`/diagnose`, `/panel`, `/json`, `/preview`.
+## AI agents
 
-Atajos: `Tab` panel · `Esc` cancelar stream · `Ctrl+C` salir.
-
-🤖 **Agent Management**
 ```bash
-# Create a new agent
-plazbot agent create -n "My Agent" -d "Description"
-
-# List all agents
 plazbot agent list
-
-# Delete an agent
-plazbot agent delete -i agent_id
+plazbot agent create                         # interactive wizard
+plazbot agent create ./agent.json            # from a JSON file
+plazbot agent templates --list               # ready-made templates
+plazbot agent get age_AbcDef123
+plazbot agent chat age_AbcDef123
+plazbot agent message age_AbcDef123 -q "What are your opening hours?"
+plazbot agent export age_AbcDef123 -o agent.json
+plazbot agent validate agent.json --strict
+plazbot agent update age_AbcDef123 ./changes.json   # only the fields in the file change
+plazbot agent ai-config age_AbcDef123 --provider openai --model gpt-4o --api-token sk-...
+plazbot agent monitor age_AbcDef123
+plazbot agent delete age_AbcDef123
 ```
 
-🌐 **Portal Management**
-```bash
-# Add a link to portal
-plazbot portal add-link -n "Example" -u "https://example.com"
+## Studio
 
-# Clear all links
-plazbot portal clear-links
-```
+An interactive terminal assistant to create, diagnose and edit agents in natural language.
 
-💬 **WhatsApp Integration**
 ```bash
-# Send a message
-plazbot whatsapp send-message -t "+1234567890" -m "Hello"
-
-# Send a template
-plazbot whatsapp send-template -t "+1234567890" -n "welcome"
-
-# Manage webhooks
-plazbot whatsapp register-webhook -u "https://your-webhook.com"
-plazbot whatsapp delete-webhook
+plazbot studio
+plazbot studio ask "list my agents"
+plazbot studio ask "diagnose agent age_AbcDef123" --json   # NDJSON stream
 ```
 
-## Installation
+## Portals
 
 ```bash
-npm install -g plazbot-cli
+plazbot portal list
+plazbot portal create -n "Help Center" -t "How can we help?"
+plazbot portal add-agent por_AbcDef123 -a age_AbcDef123
+plazbot portal add-link por_AbcDef123 -t "Docs" -u https://docs.example.com
+plazbot portal update por_AbcDef123 --disable
 ```
 
-## Usage
-
-### Portal Commands
+## Workers
 
 ```bash
-# Add a link to portal
-plazbot portal add-link -n "Example Link" -u "https://example.com"
-
-# Clear all links
-plazbot portal clear-links
+plazbot workers deploy                                   # every file in ./workers
+plazbot workers list
+plazbot workers test my-tool -d '{"product":"iPhone 15"}'
+plazbot workers logs my-tool --follow
+echo "$STRIPE_KEY" | plazbot workers secret set STRIPE_API_KEY
 ```
 
-### WhatsApp Commands
-
-```bash
-# Send a direct message
-plazbot whatsapp send-message -t "+1234567890" -m "Hello World"
+## Scripting
 
-# Send a template message
-plazbot whatsapp send-template -t "+1234567890" -n "welcome_template"
+Every command is built to run in scripts and CI:
 
-# Register a webhook
-plazbot whatsapp register-webhook -u "https://your-webhook.com"
+- **`--json`**: commands that read, list or change data print JSON to stdout. Progress messages go to stderr. Errors print as `{"error": {"message", "code", "hint"}}` on stderr.
+- **`-y, --yes`**: skips confirmation prompts (`--confirm` also works). Without a terminal, destructive commands refuse to run unless you pass `--yes`, so they never hang waiting for input.
+- **Exit codes**: `0` means success. `1` means something failed, including partial failures such as a broadcast with failed sends or a deploy with failed files.
 
-# Delete a webhook
-plazbot whatsapp delete-webhook
+```bash
+plazbot agent list --json | jq -r '.[].id'
+plazbot agent delete age_AbcDef123 --yes --json
 ```
 
-## Command Options
-
-### Portal Commands
-- `add-link`
-  - `-n, --name`: Link name
-  - `-u, --url`: Link URL
-- `clear-links`: No options required
-
-### WhatsApp Commands
-- `send-message`
-  - `-t, --to`: Recipient phone number
-  - `-m, --message`: Message text
-- `send-template`
-  - `-t, --to`: Recipient phone number
-  - `-n, --name`: Template name
-- `register-webhook`
-  - `-u, --url`: Webhook URL
-- `delete-webhook`: No options required
+Run `plazbot <command> --help` for every option and more examples.
 
-## Requirements
+## Support
 
-- Node.js 14 or higher
-- npm or yarn package manager
-- Valid Plazbot API credentials
+Documentation: https://developers.plazbot.com/cli · support@plazbot.com
 
-## Support
+## License
 
-For more documentation, please visit our [Documentation](https://docs.plazbot.com) or contact support@plazbot.com
+MIT

package/dist/cli.js

@@ -10,34 +10,49 @@ import { whatsappCommands } from './commands/whatsapp/index.js';
 import { workersCommands } from './commands/workers/index.js';
 import { studioCommand } from './studio/index.js';
 import { showBanner } from './utils/banner.js';
-// Guard de runtime: Plazbot CLI v0.3+ requiere Node 18.17+
+import { fail, setJsonMode } from './utils/output.js';
+// Runtime guard: Plazbot CLI requires Node 18.17+
 const [major, minor] = process.versions.node.split('.').map(Number);
 if (major < 18 || (major === 18 && minor < 17)) {
-    console.error(`Plazbot CLI v0.3+ requires Node.js >=18.17.0. Current version: ${process.versions.node}`);
+    console.error(`Plazbot CLI requires Node.js >=18.17.0. Current version: ${process.versions.node}`);
     process.exit(1);
 }
-// Leer version desde package.json
+// Read the version from package.json
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgPath = join(__dirname, '..', 'package.json');
 const { version } = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-// Configuracion basica del CLI
+// Basic CLI configuration
 program
     .name('plazbot')
     .description('Official Plazbot CLI - AI agents for WhatsApp, portals and developers')
     .version(version);
-// Registrar todos los comandos de autenticacion
+// Register commands
 authCommands.forEach(cmd => program.addCommand(cmd));
-// Registrar todos los comandos de agente
 program.addCommand(agentCommands);
-// Registrar todos los comandos de portal
 program.addCommand(portalCommands);
-// Registrar todos los comandos de WhatsApp
 program.addCommand(whatsappCommands);
-// Registrar todos los comandos de Workers
 program.addCommand(workersCommands);
-// Registrar el comando Studio (REPL interactivo)
 program.addCommand(studioCommand);
-// Si no se pasan argumentos, mostrar banner
+// Settings shared by every command:
+// - --dev (local backend) is an internal flag: it keeps working but is hidden from help.
+// - Usage errors suggest --help and the closest command/option.
+function configureTree(cmd) {
+    cmd.showHelpAfterError('(run with --help for usage)');
+    cmd.showSuggestionAfterError(true);
+    for (const opt of cmd.options) {
+        if (opt.long === '--dev')
+            opt.hideHelp();
+    }
+    cmd.commands.forEach(configureTree);
+}
+configureTree(program);
+// --json on the command being run: stdout only carries JSON
+program.hook('preAction', (_thisCommand, actionCommand) => {
+    setJsonMode(Boolean(actionCommand.opts().json));
+});
+// Anything that escapes a command still ends with a clear message and exit code 1
+process.on('unhandledRejection', (reason) => fail(reason));
+// Without arguments, show the banner
 if (process.argv.length <= 2) {
     showBanner().then(() => {
         program.outputHelp();