@botozap/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bytecraft Consultoria em Tecnologia LTDA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,215 @@
+# @botozap/cli
+
+CLI dev-first para a **API pública do BotoZap** — a plataforma multi-tenant sobre a
+WhatsApp Cloud API oficial (a "Kapso brasileira"). Envie mensagens, gerencie contatos,
+clientes, números, templates e webhooks direto do terminal ou de scripts.
+
+A CLI é uma casca fina sobre o SDK oficial [`@botozap/sdk`](../sdk) — toda chamada de
+rede passa por ele.
+
+> Requer **Node ≥ 20.19**. Projeto usa **pnpm** (nunca npm/npx/yarn/bun).
+
+> **Status: preview `0.x`, ainda não publicado no npm.** Sem promessa de
+> estabilidade de comandos/flags até a `1.0`. A [API REST](https://botozap.com.br/docs)
+> é a interface oficial e estável — se algo faltar na CLI, chame
+> `https://botozap.com.br/api/v1` direto (`curl` + `Authorization: Bearer`).
+> A CLI cobre hoje um SUBCONJUNTO da API: transmissões (`broadcasts`) e `flows`
+> existem no SDK/REST, mas ainda não têm comando. Bugs:
+> [issues do monorepo](https://github.com/bytecraft-fernando/botozap-js/issues)
+> — nunca inclua sua chave de API no relato.
+
+## Instalação
+
+Ainda **não publicado no npm** (em preparação). Por ora, use dentro do monorepo
+`botozap-js`:
+
+```bash
+# na raiz do monorepo
+pnpm install
+pnpm --filter @botozap/cli build
+```
+
+Isso gera `packages/cli/dist/` com o binário `botozap` (campo `bin`). Para usar a partir
+do checkout:
+
+```bash
+# na pasta do pacote
+cd packages/cli
+pnpm link --global    # disponibiliza o comando `botozap`
+# ou rode direto:
+node dist/index.js --help
+```
+
+## Autenticação
+
+A CLI fala com `/api/v1` autenticando com o header `Authorization: Bearer bz_live_…`
+(herdado do SDK). O servidor também aceita o legado `X-API-Key`, mas a CLI agora envia
+**Bearer**. A chave é criada no painel do BotoZap, em **/chaves**.
+
+A chave (e a URL base) são resolvidas nesta **ordem de prioridade**:
+
+| Item     | 1º (maior)        | 2º                   | 3º                          | padrão                          |
+| -------- | ----------------- | -------------------- | --------------------------- | ------------------------------- |
+| API key  | `--api-key`       | `BOTOZAP_API_KEY`    | `~/.botozap/cli/config.json`| —                               |
+| URL base | `--api-url`       | `BOTOZAP_API_URL`    | `~/.botozap/cli/config.json`| `https://botozap.com.br/api/v1` |
+
+> **Segurança:** prefira `BOTOZAP_API_KEY` (env) ou `botozap login` a passar
+> `--api-key` na linha de comando — argumentos de CLI ficam no histórico do shell
+> e visíveis em `ps`/argv. A flag existe para conveniência e CI, mas trata a chave
+> como segredo em argv. O `config.json` é gravado com permissão `0600` (diretório `0700`).
+
+### Gravando a chave
+
+```bash
+# stub amigável: explica /chaves e oferece colar a chave
+botozap login
+
+# direto
+botozap config set apiKey bz_live_xxxxxxxxxxxx
+botozap config set baseUrl https://botozap.com.br/api/v1
+
+botozap config get     # mostra config (apiKey mascarada)
+botozap config path    # caminho do config.json
+```
+
+> **`botozap login` é um stub.** O BotoZap ainda não tem login OAuth por navegador
+> (como `kapso login`); o comando apenas instrui a criar a chave em `/chaves` e grava
+> a chave colada no config local.
+
+### Verificando
+
+```bash
+botozap status
+# Autenticado. Conta acessível.
+# URL base       https://botozap.com.br/api/v1
+# Origem da chave config
+# Números        3
+```
+
+## Saída: humano vs. JSON
+
+Por padrão a saída é **humana** (tabelas/linhas compactas). Para scripts, use
+`-o json` (ou `--output json`), que imprime o JSON **cru** da resposta:
+
+```bash
+botozap messages list -o json | jq '.data[].id'
+```
+
+> **Listas** preservam o envelope da API (`{ data, paging }` por cursor, `{ data, meta }`
+> por offset). **Itens** (`get`, `create`, `update`, `media ingest`, `webhooks test`)
+> saem **desembrulhados** — o objeto direto, sem a chave `data` em volta — porque os
+> métodos de item do SDK já entregam a entidade. `messages send` sempre respondeu o
+> objeto direto (a rota `POST /messages` não usa envelope).
+
+## Comandos
+
+```
+botozap messages      send | list | get
+botozap conversations list | get | update
+botozap contacts      list | get | create | update | delete
+botozap media         ingest
+botozap customers     list | get | create | update | delete
+botozap setup-links   list | create | update      (--customer <id>)
+botozap numbers       list | get | health
+botozap templates     list | get | create
+botozap webhooks      list | get | create | update | delete | test
+botozap deliveries    list                          (webhook_deliveries)
+botozap logs          list                          (api_logs)
+botozap users         list
+botozap config        set | get | path
+botozap login
+botozap status
+```
+
+### Flags globais
+
+- `--api-key <chave>` / `--api-url <url>` — sobrepõem env e config.
+- `-o, --output <human|json>` — formato de saída (padrão `human`).
+- Listas por **cursor**: `--limit`, `--after`, `--before`.
+- Listas por **offset**: `--page`, `--per-page`.
+
+### Exemplos
+
+```bash
+# Enviar texto simples
+botozap messages send --to 5511999999999 --text "Olá do BotoZap!"
+
+# Enviar payload completo (template, mídia, etc.) via arquivo ou stdin
+botozap messages send --input ./mensagem.json
+cat ./mensagem.json | botozap messages send --stdin
+
+# Listar mensagens com filtro e paginação por cursor
+botozap messages list --direction inbound --limit 20
+botozap messages list --after <cursor>
+
+# Encerrar uma conversa
+botozap conversations update <id> --status ended
+
+# Criar contato
+botozap contacts create --wa-id 5511999999999 --profile-name "Maria"
+
+# Ingerir mídia por URL
+botozap media ingest --phone-number-id <id> --source https://exemplo.com/foto.jpg
+
+# Clientes (offset)
+botozap customers list --page 1 --per-page 25
+botozap customers create --name "Acme LTDA" --external-customer-id acme-001
+
+# Setup links de um cliente
+botozap setup-links list --customer <customerId>
+botozap setup-links create --customer <customerId>
+
+# Números e saúde
+botozap numbers list
+botozap numbers health <phoneNumberId>
+
+# Templates (componentes via arquivo JSON)
+botozap templates create --name boas_vindas --language pt_BR \
+  --category UTILITY --components ./components.json
+
+# Webhooks (eventos válidos: messages, statuses)
+botozap webhooks create --url https://meu.app/webhook \
+  --events messages,statuses --secret s3cr3t
+botozap webhooks test <id>
+
+# Entregas e logs
+botozap deliveries list --status failed
+botozap logs list --status-code 500
+```
+
+## Tratamento de erros
+
+A API usa o envelope `{ "error": { "code", "message" } }`. A CLI imprime a `message`
+(em PT-BR) no **stderr** e sai com **código 1**:
+
+```
+Erro [authentication_error]: Chave de API inválida ou expirada.
+```
+
+Num `429 rate_limited`, a CLI acrescenta o `Retry-After` (e `X-RateLimit-*`,
+quando presentes) à mensagem — espere esse tempo antes de reenviar.
+
+Com `-o json`, erros saem **estruturados no stderr** (stdout fica limpo para
+pipes): `{ "error": { "code", "message", "status", "rate_limit"? } }`. O exit
+code é **1** para qualquer erro (`0` só no sucesso) — trate classes de erro pelo
+`code` do JSON, não pelo exit code.
+
+## Estrutura
+
+```
+src/
+  index.ts            # entrada (bin), parsing com commander, tratamento de erro
+  client.ts           # resolve config e instancia `BotoZap` de @botozap/sdk
+  config.ts           # leitura/escrita de ~/.botozap/cli/config.json + resolução
+  output.ts           # formatação human/json (tabelas, detalhes, paginação)
+  commands/*.ts        # um arquivo por recurso
+```
+
+## Desenvolvimento
+
+```bash
+pnpm --filter @botozap/cli typecheck   # tsc --noEmit
+pnpm --filter @botozap/cli test        # vitest
+pnpm --filter @botozap/cli build       # tsc -> dist/
+node packages/cli/dist/index.js --help
+```

package/dist/client.js

@@ -0,0 +1,24 @@
+import { BotoZap } from "@botozap/sdk";
+import { resolveAuth } from "./config.js";
+// `BotoZapError` (erro de API: `.code`/`.message`/`.status`) vem do SDK — a CLI
+// não tem mais cliente HTTP próprio. Re-exporta para o handler central de erro.
+export { BotoZapError } from "@botozap/sdk";
+/** Erro de configuração local (ex.: falta de API key). Não sai do SDK. */
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+/**
+ * Resolve credenciais (flag > env > config) e instancia o cliente do SDK.
+ * A ausência de chave é um erro LOCAL (`ConfigError`) — nunca chega a rede.
+ */
+export function createClient(global) {
+    const auth = resolveAuth({ apiKey: global.apiKey, apiUrl: global.apiUrl });
+    if (!auth.apiKey) {
+        throw new ConfigError("Nenhuma API key encontrada. Defina com `botozap config set apiKey bz_live_…`, " +
+            "exporte BOTOZAP_API_KEY ou passe --api-key. Crie uma chave em /chaves no painel.");
+    }
+    return new BotoZap({ apiKey: auth.apiKey, baseUrl: auth.baseUrl });
+}

package/dist/commands/config.js

@@ -0,0 +1,53 @@
+import { readConfig, setConfigValue, configPath, } from "../config.js";
+import { resolveFormat, printJson, printLine, dim } from "../output.js";
+const ALLOWED_KEYS = ["apiKey", "baseUrl"];
+/** Mascara a API key, mostrando só o prefixo e os últimos 4 caracteres. */
+function maskKey(key) {
+    if (!key)
+        return "(não definida)";
+    if (key.length <= 12)
+        return key.slice(0, 4) + "…";
+    return key.slice(0, 8) + "…" + key.slice(-4);
+}
+export function registerConfig(program) {
+    const config = program
+        .command("config")
+        .description("Ler e gravar a configuração local da CLI");
+    config
+        .command("set <chave> <valor>")
+        .description("Define uma chave de config (apiKey | baseUrl)")
+        .action((key, value) => {
+        if (!ALLOWED_KEYS.includes(key)) {
+            throw new Error(`Chave inválida: "${key}". Use uma de: ${ALLOWED_KEYS.join(", ")}.`);
+        }
+        setConfigValue(key, value);
+        printLine(`Gravado em ${configPath()}`);
+        if (key === "apiKey") {
+            printLine(dim(`apiKey = ${maskKey(value)}`));
+        }
+        else {
+            printLine(dim(`${key} = ${value}`));
+        }
+    });
+    config
+        .command("get")
+        .description("Mostra a config atual (apiKey mascarada)")
+        .action((_opts, cmd) => {
+        const format = resolveFormat(cmd.optsWithGlobals().output);
+        const stored = readConfig();
+        if (format === "json") {
+            return printJson({
+                apiKey: stored.apiKey ? maskKey(stored.apiKey) : null,
+                baseUrl: stored.baseUrl ?? null,
+            });
+        }
+        printLine(`apiKey   ${maskKey(stored.apiKey)}`);
+        printLine(`baseUrl  ${stored.baseUrl ?? dim("(padrão)")}`);
+    });
+    config
+        .command("path")
+        .description("Mostra o caminho do arquivo de configuração")
+        .action(() => {
+        printLine(configPath());
+    });
+}

package/dist/commands/contacts.js

@@ -0,0 +1,110 @@
+import { context, toInt, toBool } from "./shared.js";
+import { printJson, printTable, printDetail, printCursorFooter, printLine, } from "../output.js";
+export function registerContacts(program) {
+    const contacts = program
+        .command("contacts")
+        .description("Gerenciar contatos");
+    contacts
+        .command("list")
+        .description("Lista contatos (paginação por cursor)")
+        .option("--customer-id <id>", "filtra por cliente")
+        .option("--profile-name-contains <texto>", "filtra por nome do perfil")
+        .option("--wa-id-contains <texto>", "filtra por wa_id")
+        .option("--has-customer <bool>", "true | false")
+        .option("--created-after <data>", "ISO 8601")
+        .option("--created-before <data>", "ISO 8601")
+        .option("--limit <n>", "quantidade por página")
+        .option("--after <cursor>", "cursor da próxima página")
+        .option("--before <cursor>", "cursor da página anterior")
+        .action(async (opts, cmd) => {
+        const { client, format } = context(cmd);
+        const res = await client.contacts.list({
+            customer_id: opts.customerId,
+            profile_name_contains: opts.profileNameContains,
+            wa_id_contains: opts.waIdContains,
+            has_customer: toBool(opts.hasCustomer),
+            created_after: opts.createdAfter,
+            created_before: opts.createdBefore,
+            limit: toInt(opts.limit),
+            after: opts.after,
+            before: opts.before,
+        });
+        if (format === "json")
+            return printJson(res);
+        printTable(res.data, [
+            { header: "ID", key: "id", max: 36 },
+            { header: "WA_ID", key: "wa_id" },
+            { header: "NOME", key: "profile_name" },
+            { header: "USERNAME", key: "username" },
+            { header: "CLIENTE", key: "customer_id", max: 36 },
+        ]);
+        printCursorFooter(res.paging);
+    });
+    contacts
+        .command("get <id>")
+        .description("Detalha um contato")
+        .action(async (id, _opts, cmd) => {
+        const { client, format } = context(cmd);
+        const data = await client.contacts.get(id);
+        if (format === "json")
+            return printJson(data);
+        printDetail(data);
+    });
+    contacts
+        .command("create")
+        .description("Cria um contato")
+        .requiredOption("--wa-id <wa_id>", "WhatsApp ID (obrigatório)")
+        .option("--profile-name <nome>", "nome do perfil")
+        .option("--phone <telefone>", "telefone")
+        .option("--user-id <id>", "id externo do usuário")
+        .option("--username <username>", "username")
+        .option("--customer-id <id>", "cliente vinculado")
+        .option("--phone-number-id <id>", "número vinculado")
+        .action(async (opts, cmd) => {
+        const { client, format } = context(cmd);
+        const data = await client.contacts.create({
+            wa_id: opts.waId,
+            profile_name: opts.profileName,
+            phone: opts.phone,
+            user_id: opts.userId,
+            username: opts.username,
+            customer_id: opts.customerId,
+            phone_number_id: opts.phoneNumberId,
+        });
+        if (format === "json")
+            return printJson(data);
+        printLine("Contato criado.");
+        printDetail(data);
+    });
+    contacts
+        .command("update <id>")
+        .description("Atualiza um contato")
+        .option("--profile-name <nome>", "novo nome do perfil")
+        .option("--username <username>", "novo username")
+        .action(async (id, opts, cmd) => {
+        const { client, format } = context(cmd);
+        const body = {};
+        if (opts.profileName !== undefined)
+            body.profile_name = opts.profileName;
+        if (opts.username !== undefined)
+            body.username = opts.username;
+        if (Object.keys(body).length === 0) {
+            throw new Error("Informe ao menos --profile-name ou --username.");
+        }
+        const data = await client.contacts.update(id, body);
+        if (format === "json")
+            return printJson(data);
+        printLine("Contato atualizado.");
+        printDetail(data);
+    });
+    contacts
+        .command("delete <id>")
+        .description("Remove um contato")
+        .action(async (id, _opts, cmd) => {
+        const { client, format } = context(cmd);
+        await client.contacts.delete(id);
+        if (format === "json")
+            return printJson({ deleted: true });
+        printLine("Contato removido.");
+    });
+}

package/dist/commands/conversations.js

@@ -0,0 +1,60 @@
+import { context, toInt } from "./shared.js";
+import { printJson, printTable, printDetail, printCursorFooter, printLine, } from "../output.js";
+export function registerConversations(program) {
+    const conv = program
+        .command("conversations")
+        .description("Listar e gerenciar conversas");
+    conv
+        .command("list")
+        .description("Lista conversas (paginação por cursor)")
+        .option("--phone-number-id <id>", "filtra por número")
+        .option("--status <status>", "active | ended")
+        .option("--phone-number <e164>", "filtra pelo número do contato")
+        .option("--limit <n>", "quantidade por página")
+        .option("--after <cursor>", "cursor da próxima página")
+        .option("--before <cursor>", "cursor da página anterior")
+        .action(async (opts, cmd) => {
+        const { client, format } = context(cmd);
+        const res = await client.conversations.list({
+            phone_number_id: opts.phoneNumberId,
+            status: opts.status,
+            phone_number: opts.phoneNumber,
+            limit: toInt(opts.limit),
+            after: opts.after,
+            before: opts.before,
+        });
+        if (format === "json")
+            return printJson(res);
+        printTable(res.data, [
+            { header: "ID", key: "id", max: 36 },
+            { header: "CONTATO", key: "phone_number" },
+            { header: "STATUS", key: "status" },
+            { header: "ATUALIZADA", key: "updated_at" },
+        ]);
+        printCursorFooter(res.paging);
+    });
+    conv
+        .command("get <id>")
+        .description("Detalha uma conversa")
+        .action(async (id, _opts, cmd) => {
+        const { client, format } = context(cmd);
+        const data = await client.conversations.get(id);
+        if (format === "json")
+            return printJson(data);
+        printDetail(data);
+    });
+    conv
+        .command("update <id>")
+        .description("Atualiza o status de uma conversa (active | ended)")
+        .requiredOption("--status <status>", "active | ended")
+        .action(async (id, opts, cmd) => {
+        const { client, format } = context(cmd);
+        const data = await client.conversations.update(id, {
+            status: opts.status,
+        });
+        if (format === "json")
+            return printJson(data);
+        printLine("Conversa atualizada.");
+        printDetail(data);
+    });
+}

package/dist/commands/customers.js

@@ -0,0 +1,86 @@
+import { context, toInt } from "./shared.js";
+import { printJson, printTable, printDetail, printOffsetFooter, printLine, } from "../output.js";
+export function registerCustomers(program) {
+    const customers = program
+        .command("customers")
+        .description("Gerenciar clientes (do seu workspace)");
+    customers
+        .command("list")
+        .description("Lista clientes (paginação por offset)")
+        .option("--page <n>", "página")
+        .option("--per-page <n>", "itens por página")
+        .action(async (opts, cmd) => {
+        const { client, format } = context(cmd);
+        const res = await client.customers.list({
+            page: toInt(opts.page),
+            per_page: toInt(opts.perPage),
+        });
+        if (format === "json")
+            return printJson(res);
+        printTable(res.data, [
+            { header: "ID", key: "id", max: 36 },
+            { header: "NOME", key: "name" },
+            { header: "EXTERNO", key: "external_customer_id" },
+            { header: "CRIADO", key: "created_at" },
+        ]);
+        printOffsetFooter(res.meta);
+    });
+    customers
+        .command("get <id>")
+        .description("Detalha um cliente")
+        .action(async (id, _opts, cmd) => {
+        const { client, format } = context(cmd);
+        const data = await client.customers.get(id);
+        if (format === "json")
+            return printJson(data);
+        printDetail(data);
+    });
+    customers
+        .command("create")
+        .description("Cria um cliente")
+        .requiredOption("--name <nome>", "nome do cliente (obrigatório)")
+        .option("--external-customer-id <id>", "id externo")
+        .action(async (opts, cmd) => {
+        const { client, format } = context(cmd);
+        const data = await client.customers.create({
+            name: opts.name,
+            external_customer_id: opts.externalCustomerId,
+        });
+        if (format === "json")
+            return printJson(data);
+        printLine("Cliente criado.");
+        printDetail(data);
+    });
+    customers
+        .command("update <id>")
+        .description("Atualiza um cliente")
+        .option("--name <nome>", "novo nome")
+        .option("--external-customer-id <id>", "novo id externo")
+        .action(async (id, opts, cmd) => {
+        const { client, format } = context(cmd);
+        const body = {};
+        if (opts.name !== undefined)
+            body.name = opts.name;
+        if (opts.externalCustomerId !== undefined) {
+            body.external_customer_id = opts.externalCustomerId;
+        }
+        if (Object.keys(body).length === 0) {
+            throw new Error("Informe ao menos --name ou --external-customer-id.");
+        }
+        const data = await client.customers.update(id, body);
+        if (format === "json")
+            return printJson(data);
+        printLine("Cliente atualizado.");
+        printDetail(data);
+    });
+    customers
+        .command("delete <id>")
+        .description("Remove um cliente")
+        .action(async (id, _opts, cmd) => {
+        const { client, format } = context(cmd);
+        await client.customers.delete(id);
+        if (format === "json")
+            return printJson({ deleted: true });
+        printLine("Cliente removido.");
+    });
+}

package/dist/commands/deliveries.js

@@ -0,0 +1,40 @@
+import { context, toInt } from "./shared.js";
+import { printJson, printTable, printCursorFooter } from "../output.js";
+export function registerDeliveries(program) {
+    const deliveries = program
+        .command("deliveries")
+        .description("Entregas de webhook (webhook_deliveries)");
+    deliveries
+        .command("list")
+        .description("Lista entregas de webhook (paginação por cursor)")
+        .option("--endpoint-id <id>", "filtra por endpoint")
+        .option("--webhook-id <id>", "alias de --endpoint-id")
+        .option("--status <status>", "filtra por status")
+        .option("--event-type <tipo>", "filtra por tipo de evento")
+        .option("--limit <n>", "quantidade por página")
+        .option("--after <cursor>", "cursor da próxima página")
+        .option("--before <cursor>", "cursor da página anterior")
+        .action(async (opts, cmd) => {
+        const { client, format } = context(cmd);
+        // `webhook_id` é alias de `endpoint_id` na rota; --endpoint-id/--webhook-id
+        // colapsam no mesmo param (endpoint tem precedência).
+        const res = await client.webhookDeliveries.list({
+            webhook_id: opts.endpointId ?? opts.webhookId,
+            status: opts.status,
+            event_type: opts.eventType,
+            limit: toInt(opts.limit),
+            after: opts.after,
+            before: opts.before,
+        });
+        if (format === "json")
+            return printJson(res);
+        printTable(res.data, [
+            { header: "ID", key: "id", max: 36 },
+            { header: "EVENTO", key: "event_type" },
+            { header: "STATUS", key: "status" },
+            { header: "HTTP", key: "response_status" },
+            { header: "CRIADA", key: "created_at" },
+        ]);
+        printCursorFooter(res.paging);
+    });
+}

package/dist/commands/login.js

@@ -0,0 +1,61 @@
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { setConfigValue, configPath } from "../config.js";
+import { printLine, dim } from "../output.js";
+import pc from "picocolors";
+/**
+ * `botozap login` — STUB amigável.
+ *
+ * O BotoZap ainda não tem login OAuth por navegador (como o `kapso login`).
+ * Por isso este comando apenas (1) explica como criar uma API key no painel,
+ * em /chaves, e (2) oferece colar a chave para gravá-la no config local.
+ */
+export function registerLogin(program) {
+    program
+        .command("login")
+        .description("Instruções para autenticar e gravar sua API key (stub)")
+        .option("--api-key <chave>", "grava a chave informada sem perguntar")
+        .action(async (opts, _cmd) => {
+        printLine(pc.bold("Autenticação do BotoZap CLI"));
+        printLine("");
+        printLine("Ainda não há login por navegador (OAuth). Use uma API key do painel:");
+        printLine(`  1. Acesse ${pc.cyan("https://botozap.com.br/chaves")}`);
+        printLine("  2. Crie uma chave (formato bz_live_…)");
+        printLine("  3. Cole a chave abaixo (ou rode com --api-key).");
+        printLine("");
+        let key = opts.apiKey;
+        if (!key) {
+            const interativo = Boolean(stdin.isTTY);
+            const rl = createInterface({ input: stdin, output: stdout });
+            try {
+                const pergunta = rl.question("Cole sua API key: ");
+                if (interativo) {
+                    // Mascara a digitação: o prompt acima já foi impresso, então a
+                    // partir daqui suprimimos o eco de cada caractere da chave. Assim
+                    // ela não aparece na tela nem fica no scrollback do terminal.
+                    // (Num pipe/redirect não há eco de terminal, então não mascaramos —
+                    // o `botozap login < chave.txt` / `echo … | botozap login` funciona.)
+                    rl._writeToOutput = () => { };
+                }
+                key = (await pergunta).trim();
+                // O Enter final também foi suprimido pela máscara: reponha a quebra.
+                if (interativo)
+                    stdout.write("\n");
+            }
+            finally {
+                rl.close();
+            }
+        }
+        if (!key) {
+            printLine(dim("Nenhuma chave informada. Nada foi gravado."));
+            return;
+        }
+        if (!key.startsWith("bz_")) {
+            printLine(pc.yellow("Aviso: a chave não começa com `bz_`. Gravando mesmo assim."));
+        }
+        setConfigValue("apiKey", key);
+        printLine(pc.green("Chave gravada com sucesso."));
+        printLine(dim(`Arquivo: ${configPath()}`));
+        printLine(dim("Verifique com `botozap status`."));
+    });
+}