CLI

v0.2.1 · npm · MIT

@sonenta/cli

Una línea de comandos ligera y scriptable para todo lo que de otro modo harías en el dashboard: importar un proyecto i18next existente, hacer push y pull de traducciones, comparar la CI con el remoto, publicar una release de CDN y crear un snapshot de los bundles para un build offline-first. MIT, en npm.

Ruptura · 0.1 → 0.2

Toda la CLI pasa ahora por la superficie MCP: necesita una clave API con el scope mcp:* — las claves limitadas al proyecto devuelven 403. Genera una en el dashboard en Org Settings → API Keys y vuelve a emitir cualquier clave que usaras con la 0.1.

Instalación

Solo npm — no hay fórmula de Homebrew para la CLI. Requiere Node 18 o más reciente, e instala el comando sonenta.

terminal

1# instalar una vez, globalmente2npm i -g @sonenta/cli 4# o ejecutar sin instalar5npx @sonenta/cli <command>

Autenticarse

Cada llamada envía Authorization: ApiKey <prefix>.<secret> con el scope mcp:*. Inicia sesión una vez para almacenar la clave en ~/.sonenta/credentials, o define SONENTA_TOKEN en la CI.

terminal

1# interactivo — almacena la clave por host en ~/.sonenta/credentials (0600)2sonenta login --host https://api.sonenta.com3API key: snt_live_••••••••.••••••••••••••••4✓ guardado para https://api.sonenta.com 6# CI — sin prompt, la clave se lee del entorno7export SONENTA_TOKEN=snt_live_<prefix>.<secret>8sonenta push

Orden de resolución, gana el primero: la variable de entorno SONENTA_TOKEN, luego ~/.sonenta/credentials para el host activo. Genera la clave en Org Settings → API Keys con el scope mcp:*.

Configurar

sonenta init escribe un sonenta.config.json en tu repositorio (resuelto subiendo desde el directorio actual). Las credenciales viven aparte, por usuario, y nunca se commitean.

sonenta.config.json

1# commiteado en tu repositorio — ningún secreto aquí2{3  "host": "https://api.sonenta.com",4  "project_uuid": "<project_uuid>",5  "version_slug": "main"6}

~/.sonenta/credentials

1# ~/.sonenta/credentials — modo 0600, por usuario, nunca commitear2{ "default": "https://api.sonenta.com",3  "hosts": {4    "https://api.sonenta.com": { "api_key": "snt_live_..." }5  } }

version_slug vale main por defecto. Mantén la clave API fuera de sonenta.config.json — solo tiene su sitio en el archivo de credenciales o en SONENTA_TOKEN.

Comandos

Agrupados según lo que estés haciendo — configurar la autenticación y la config, inspeccionar un proyecto o sincronizar traducciones. Cada comando pasa por la superficie MCP y respeta sonenta.config.json.

Auth y config

sonenta login Almacenar una clave API para un host.

Opciones

--host <url> Host API contra el que autenticarse.
--token <key> Pasar la clave sin prompt en lugar de pedirla.

Ejemplo

sonenta login --host https://api.sonenta.com

sonenta logout Eliminar las credenciales almacenadas de un host.

Opciones

Sin opciones.

Ejemplo

sonenta logout

sonenta whoami Mostrar el host activo y una clave enmascarada.

Opciones

Sin opciones.

Ejemplo

sonenta whoami

sonenta init Generar sonenta.config.json para un proyecto.

Opciones

--project <uuid> UUID del proyecto a escribir en la config (obligatorio).
--version <slug> Slug de versión a apuntar (por defecto main).
--force Sobrescribir un archivo de config existente.

Ejemplo

sonenta init --project <uuid> --version main

Inspeccionar

sonenta projects list Listar los proyectos accesibles para tu clave.

Opciones

Sin opciones.

Ejemplo

sonenta projects list

sonenta keys list Listar las claves con la forma namespace_slug/key_name.

Opciones

--namespace <slug> Restringir a un namespace.

Ejemplo

sonenta keys list --namespace common

sonenta status Comparar tu locales/ local con el remoto.

Opciones

--language <code> Limitar la comparación a un idioma.
--namespace <slug> Limitar la comparación a un namespace.
--src <dir> Directorio de origen (por defecto locales).

Ejemplo

sonenta status

sonenta missing Listar las claves faltantes detectadas en tiempo de ejecución.

Opciones

--language <code> Filtrar por idioma.
--namespace <slug> Filtrar por namespace.
--limit <n> Limitar el número de filas.

Ejemplo

sonenta missing --limit 50

Importación y sincronización

sonenta import <files...> Importación i18next en una sola pasada — anidado o plano; crea las claves, actualiza las traducciones, idempotente.

Opciones

--dry-run Solo vista previa; no envía nada.
--status <draft|translated> Estado entrante (por defecto translated).
--language <code> Forzar el idioma en lugar de deducirlo de la ruta.
--namespace <slug> Forzar el namespace (obligatorio para un <lang>.json simple).
--version <slug> Apuntar a una versión no predeterminada.

Ejemplo

sonenta import locales/fr/common.json

sonenta push Hacer push de todo el árbol locales/ local en una sola llamada de import.

Opciones

--src <dir> Directorio de origen (por defecto locales).
--dry-run Solo vista previa; no envía nada.
--status <state> Estado entrante (por defecto translated).

Ejemplo

sonenta push --dry-run

sonenta pull Escribir las traducciones remotas en locales/<lang>/<namespace>.json (plano).

Opciones

--language <code> Limitar a un idioma.
--namespace <slug> Limitar a un namespace.
--dest <dir> Directorio de destino (por defecto locales).

Ejemplo

sonenta pull --language fr

sonenta export Exportar como JSON i18next — plano por defecto, --nested para árboles.

Opciones

--nested Emitir árboles anidados en lugar de claves planas.
--out <dir> Escribir archivos en un directorio en lugar de en stdout.

Ejemplo

sonenta export --nested --out ./dump

sonenta releases publish Disparar una release de CDN; los SDK suscritos se refrescan en vivo.

Opciones

--version <slug> Versión a publicar (por defecto main).
--dry-run Solo vista previa; no publica nada.

Ejemplo

sonenta releases publish

sonenta snapshot Recuperar los bundles públicos del CDN en un módulo de build para el fallback offline-first del SDK.

Opciones

--format <ts|json> Formato de salida: ts (por defecto) o json.
--out <file> Escribir en un archivo en lugar de en stdout.
--cdn <base> Base del CDN (por defecto https://cdn.sonenta.com).

Ejemplo

sonenta snapshot --out src/sonenta-bundles.ts

Cada comando también acepta --host <url> para sobrescribir el host API configurado durante una sola ejecución.

Rupturas 0.1 → 0.2

¿Subes desde la 0.1? Dos cambios requieren acción.

Superficie MCP + scope. Toda la CLI pasó de la superficie REST del proyecto a la superficie MCP. Vuelve a emitir tu clave API con el scope mcp:* — las claves limitadas al proyecto ahora devuelven 403.
push en una sola pasada. push ahora envía todo tu árbol locales/ en una sola llamada de import (antes era una creación de clave más un PUT por traducción). Es idempotente y muestra creadas / actualizadas / sin cambios.
Nuevos comandos. import, export, releases publish, snapshot y projects list son nuevos en la 0.2.0.