Hinto CLI

Hinto CLI Skill

Este skill cubre todos los flujos de trabajo de terminal de Hinto: instalación, autenticación, cada grupo de comandos, manejo de trabajos asíncronos y encadenamiento de comandos.

Instalación

Este skill impulsa la CLI hinto.

Nombre del paquete: el comando es hinto, pero el paquete npm es @hintoai/cli. No adivines @hinto/cli o hinto — esos no existen y darán error 404. Siempre instala, actualiza y referencia el paquete como @hintoai/cli.

Antes de ejecutar cualquier comando, asegúrate de que la CLI esté instalada — si hinto no está en PATH, instálala primero:

# Instalar la CLI globalmente
npm install -g @hintoai/cli

# Verificar
hinto --version

Para actualizar a la última versión, ejecuta:

npm install -g @hintoai/cli@latest

Luego autentícate (ver más abajo). Si un comando hinto falla con "command not found", vuelve a ejecutar el paso de instalación anterior.

Instalar este skill en sí mismo (para cualquier agente) se hace con la CLI universal de skills: npx skills add hintoai/hinto-cli

Autenticación

Dónde obtener la clave API

Las claves API son por proyecto (no a nivel de cuenta) — cada clave está asociada a un solo proyecto, y la CLI actúa sobre el proyecto al que pertenece la clave. Para crear una:

1. Abre el proyecto en la aplicación Hinto (https://app.hintoai.com).
2. Haz clic en Settings (barra superior) para abrir Project Settings.
3. Ve a API Keys & Webhooks → API Keys.
4. Haz clic en New Api Key y copia la clave generada.

Configurar la clave

Prefiere la variable de entorno — funciona en CI y anula el archivo de configuración:

export HINTO_API_KEY=hinto_...

Para uso interactivo/local, ejecuta init una vez:

hinto init --key hinto_...
# Escribe ~/.hinto/config.json — permisos 600

Para apuntar a un entorno staging o una instancia autoalojada, usa --api-url:

hinto init --key hinto_... --api-url https://staging.hintoai.com
# o por comando:
hinto articles list --api-url https://staging.hintoai.com

Banderas globales

Estas banderas funcionan en todos los comandos:

Banderas	Propósito
--json	Muestra JSON puro en stdout — úsalo al encadenar comandos o analizar la salida
--api-url <url>	Sobrescribe la URL base (staging, autoalojado)

Estilo de trabajo

Cuando este skill está activo:

1. Ejecuta comandos mediante Bash — ejecuta los comandos hinto directamente, no solo los describas.
2. Usa --json al encadenar — canaliza o analiza la salida JSON para alimentar el siguiente comando.
3. Usa --wait para trabajos asíncronos — solo disponible en generate start y generate structure. Sin --wait, estos devuelven inmediatamente un jobId. publish now, publish republish y project retranslate son siempre asíncronos (sin --wait) — consulta manualmente con hinto generate status <jobId>.
4. Verifica la autenticación primero — si un comando devuelve UNAUTHORIZED, verifica que HINTO_API_KEY esté configurada o que se haya ejecutado hinto init.
5. El spinner va a stderr — stdout se mantiene limpio para tuberías incluso con --wait.

Patrones de interacción:

6. Preguntar vs. automático — solo pregunta al usuario cuando haya una decisión real (2+ opciones). Con 0-1 opciones, procede e indica lo que usaste.
7. Confirmar acciones destructivas — antes de articles delete y publish unpublish, confirma con el usuario, indicando exactamente qué se eliminará o desconectará. Nunca las ejecutes de forma especulativa.
8. Disciplina de salida — termina cada tarea con: el/los comando(s) ejecutados y su resultado, cualquier jobId para trabajo asíncrono no esperado, enlaces (editUrl / previewUrl cuando estén disponibles) y el siguiente paso de verificación.

Orientación — comienza aquí

Ejecuta estos primero para familiarizarte con el proyecto al que apunta la clave (la clave es por proyecto — actúas sobre exactamente uno):

hinto project get --json          # nombre, tipo, publicado, dominio personalizado
hinto project structure --json    # árbol de carpetas + artículos
hinto publish status --json       # si está en vivo, y en qué URL

Si los resultados no coinciden con lo esperado por el usuario, es probable que la clave apunte a un proyecto diferente — el usuario debe proporcionar la clave correcta; no puedes cambiar de proyecto.

Ámbitos

Cada clave API tiene ámbitos. Las operaciones fallan con INSUFFICIENT_SCOPE (403) cuando falta un ámbito:

Ámbito	Permite
read	get / list / status / structure / languages / versions / translations
write	create / update / delete / move / duplicate / restore / add-language
generate	generate start / structure, regenerate, retranslate, trigger-translate
publish	publish now / republish / unpublish

Recuperación: indica al usuario qué ámbito falta — se debe crear una nueva clave con ese ámbito en la interfaz web.

Peculiaridades de ID y estado

• Los IDs de artículos y carpetas son enteros; los IDs de trabajos son uuid.
• slug y previewUrl son null hasta que se publique (y para artículos que no estén en la instantánea de publicación actual).
• Un video debe estar ready antes de generate start / generate structure.
• generate structure produce stubs vacíos, no artículos completos — consulta references/product-behavior.md.
• Límite de tasa: 60 req/min por clave (RATE_LIMITED 429 → esperar Retry-After). La generación puede devolver QUOTA_EXCEEDED.

Lo que la CLI no puede hacer (solo interfaz web)

No inventes comandos para estos — están en la aplicación web de Hinto:

• Crear un proyecto o una clave API
• Gestión de workspace / facturación
• Edición de marca y configuración de publicación no expuesta por un comando documentado

Flujo de trabajo principal: Subir → Generar → Publicar

# 1. Subir un archivo de video local
hinto videos upload --file ./video.mp4 --json
# → { "videoId": "..." }

# O importar desde una URL (devuelve un objeto Job — consulta hasta que se complete para obtener videoId)
hinto videos import --url https://example.com/video.mp4 --json
# → { "jobId": "...", "type": "import_video_url", "status": "pending", "output": null, ... }
# Luego consulta: hinto generate status <jobId> — el output completado contiene el videoId

# 2. Esperar hasta que el video esté listo
hinto videos status <videoId> --json
# → { "videoId": "...", "status": "ready", ... }

# 3. Listar plantillas disponibles
hinto templates article --json

# 4. Generar un artículo y esperar la finalización
hinto generate start --video <videoId> --template <templateId> --wait --json

# 4b. Entregar al usuario un enlace al nuevo artículo (editUrl siempre presente; previewUrl cuando esté publicado)
hinto articles get <articleId> --json   # → incluye editUrl + previewUrl

# 5. Publicar el proyecto (asíncrono — devuelve un jobId inmediatamente)
hinto publish now --json
# → { "jobId": "...", "type": "publish", "status": "pending", ... }
# Consultar: hinto generate status <jobId>

Enrutamiento de categorías

Lee el archivo de referencia para el grupo de comandos correspondiente:

Tarea	Archivo de referencia
Subir, importar, gestionar videos	references/videos.md
Crear, editar, mover, traducir artículos	references/articles.md
Crear y organizar carpetas	references/folders.md
Generar artículos o estructura desde video	references/generate.md
Información del proyecto, árbol de estructura, idiomas	references/project.md
Publicar, volver a publicar, despublicar	references/publish.md
Explorar plantillas disponibles	references/templates.md
Exportar artículos, carpetas o proyecto completo	references/export.md
Convertir un video en contenido (un artículo vs. estructura)	references/content-from-video.md
Recetas de tareas comunes (subir→generar→publicar, editar→volver a publicar, añadir imágenes)	references/recipes.md
Comportamiento del producto (versionado/restauración, stubs/auto-generar, imágenes, traducciones)	references/product-behavior.md

Lista de verificación de salida

Deja al usuario con:

• El comando ejecutado y su resultado
• El jobId si la operación es asíncrona y no se usó --wait
• El siguiente paso de verificación (ej. hinto videos status <id>, hinto generate status <jobId>)
• Cualquier advertencia de ámbito o autenticación que haya afectado el resultado