hintoai/hinto-cli

Compétence CLI Hinto

Cette compétence couvre tous les workflows Hinto en terminal : installation, authentification, chaque groupe de commandes, gestion des tâches asynchrones et enchaînement de commandes.

Installation

Cette compétence pilote le CLI hinto.

Nom du package : la commande est hinto, mais le package npm est @hintoai/cli. Ne pas deviner @hinto/cli ou hinto — ces packages n'existent pas et renverront une erreur 404. Installez, mettez à jour et référencez toujours le package sous le nom @hintoai/cli.

Avant d'exécuter une commande, assurez-vous que le CLI est installé — si hinto n'est pas dans le PATH, installez-le d'abord :

# Installer le CLI globalement
npm install -g @hintoai/cli

# Vérifier
hinto --version

Pour mettre à jour vers la dernière version, exécutez :

npm install -g @hintoai/cli@latest

Ensuite, authentifiez-vous (voir ci-dessous). Si une commande hinto échoue avec « commande introuvable », relancez l'étape d'installation ci-dessus.

L'installation de cette compétence elle-même (pour n'importe quel agent) se fait avec le CLI universel des compétences : npx skills add hintoai/hinto-cli

Authentification

Où obtenir la clé API

Les clés API sont par projet (pas par compte) — chaque clé est limitée à un seul projet, et le CLI agit sur le projet auquel la clé appartient. Pour en créer une :

1. Ouvrez le projet dans l'application Hinto (https://app.hintoai.com).
2. Cliquez sur Paramètres (barre supérieure) pour ouvrir les Paramètres du projet.
3. Allez dans Clés API & Webhooks → onglet Clés API.
4. Cliquez sur Nouvelle clé API et copiez la clé générée.

Configuration de la clé

Privilégiez la variable d'environnement — elle fonctionne en CI et remplace le fichier de configuration :

export HINTO_API_KEY=hinto_...

Pour une utilisation interactive/locale, exécutez init une fois :

hinto init --key hinto_...
# Écrit ~/.hinto/config.json — permissions 600

Pour cibler une instance de staging ou auto-hébergée, utilisez --api-url :

hinto init --key hinto_... --api-url https://staging.hintoai.com
# ou par commande :
hinto articles list --api-url https://staging.hintoai.com

Drapeaux globaux

Ces drapeaux fonctionnent sur chaque commande :

Drapeau	Objectif
--json	Sortie JSON brute sur stdout — à utiliser lors du chaînage de commandes ou de l'analyse de la sortie
--api-url <url>	Remplacer l'URL de base (staging, auto-hébergé)

Méthode de travail

Lorsque cette compétence est active :

1. Exécutez les commandes via Bash — exécutez les commandes hinto directement, ne vous contentez pas de les décrire.
2. Utilisez --json pour le chaînage — pipez ou analysez la sortie JSON pour alimenter la commande suivante.
3. Utilisez --wait pour les tâches asynchrones — pris en charge uniquement sur generate start et generate structure. Sans --wait, ces commandes renvoient immédiatement un jobId. publish now, publish republish et project retranslate sont toujours asynchrones (pas de --wait) — interrogez manuellement avec hinto generate status <jobId>.
4. Vérifiez d'abord l'authentification — si une commande renvoie UNAUTHORIZED, vérifiez que HINTO_API_KEY est définie ou que hinto init a été exécuté.
5. Le spinner va sur stderr — la sortie standard reste propre pour le piping même avec --wait.

Schémas d'interaction :

6. Demandez vs. automatique — ne sollicitez l'utilisateur que lorsqu'il y a un vrai choix (2 options ou plus). Avec 0–1 option, exécutez et indiquez ce que vous avez utilisé.
7. Confirmez les actions destructrices — avant articles delete et publish unpublish, confirmez avec l'utilisateur en indiquant exactement ce qui sera supprimé ou mis hors ligne. Ne les exécutez jamais de manière spéculative.
8. Discipline de sortie — terminez chaque tâche par : la ou les commandes exécutées + résultat, tout jobId pour un travail asynchrone non attendu, les liens (editUrl / previewUrl quand ils sont disponibles), et la prochaine étape de vérification.

Orientation — commencez ici

Exécutez d'abord ces commandes pour vous familiariser avec le projet ciblé par la clé (la clé est par projet — vous agissez sur un seul) :

hinto project get --json          # nom, type, estPublié, domaine personnalisé
hinto project structure --json    # arborescence des dossiers + articles
hinto publish status --json       # est-ce en ligne, et à quelle URL

Si les résultats ne correspondent pas aux attentes de l'utilisateur, la clé cible probablement un autre projet — l'utilisateur doit fournir la clé correcte ; vous ne pouvez pas changer de projet.

Périmètres

Chaque clé API porte des périmètres. Les opérations échouent avec INSUFFICIENT_SCOPE (403) lorsqu'un périmètre est manquant :

Périmètre	Autorise
read	obtenir / lister / statut / structure / langues / versions / traductions
write	créer / mettre à jour / supprimer / déplacer / dupliquer / restaurer / ajouter une langue
generate	generate start / structure, régénérer, retraduire, déclencher une traduction
publish	publish now / republish / unpublish

Récupération : indiquez à l'utilisateur quel périmètre manque — une nouvelle clé avec ce périmètre doit être créée dans l'interface de l'application.

Pièges d'ID et d'état

• Les ID d'articles et de dossiers sont des entiers ; les ID de tâches sont des UUID.
• slug et previewUrl sont nuls jusqu'à la publication (et pour les articles qui ne sont pas dans l'instantané de publication actuel).
• Une vidéo doit être ready avant generate start / generate structure.
• generate structure produit des ébauches vides, pas des articles complets — voir references/product-behavior.md.
• Limite de débit : 60 req/min par clé (RATE_LIMITED 429 → attendre Retry-After). La génération peut renvoyer QUOTA_EXCEEDED.

Ce que le CLI ne peut pas faire (interface web uniquement)

N'inventez pas de commandes pour ces actions — elles se trouvent dans l'application web Hinto :

• Créer un projet ou une clé API
• Gestion de l'espace de travail / facturation
• Modification de la marque et des paramètres de publication non exposés par une commande documentée

Workflow de base : Uploader → Générer → Publier

# 1. Uploader un fichier vidéo local
hinto videos upload --file ./video.mp4 --json
# → { "videoId": "..." }

# OU importer depuis une URL (renvoie un objet Job — interroger jusqu'à terminaison pour obtenir le videoId)
hinto videos import --url https://example.com/video.mp4 --json
# → { "jobId": "...", "type": "import_video_url", "status": "pending", "output": null, ... }
# Puis interroger : hinto generate status <jobId> — la sortie terminée contient le videoId

# 2. Attendre que la vidéo soit prête
hinto videos status <videoId> --json
# → { "videoId": "...", "status": "ready", ... }

# 3. Lister les templates disponibles
hinto templates article --json

# 4. Générer un article et attendre la fin
hinto generate start --video <videoId> --template <templateId> --wait --json

# 4b. Donner un lien vers le nouvel article (editUrl toujours présent ; previewUrl une fois publié)
hinto articles get <articleId> --json   # → inclut editUrl + previewUrl

# 5. Publier le projet (asynchrone — renvoie immédiatement un jobId)
hinto publish now --json
# → { "jobId": "...", "type": "publish", "status": "pending", ... }
# Interroger : hinto generate status <jobId>

Aiguillage par catégorie

Lisez le fichier de référence correspondant au groupe de commandes concerné :

Tâche	Fichier de référence
Uploader, importer, gérer les vidéos	references/videos.md
Créer, éditer, déplacer, traduire les articles	references/articles.md
Créer et organiser les dossiers	references/folders.md
Générer des articles ou une structure à partir d'une vidéo	references/generate.md
Informations sur le projet, arborescence, langues	references/project.md
Publier, republier, dé-publier	references/publish.md
Parcourir les templates disponibles	references/templates.md
Exporter des articles, dossiers, ou le projet entier	references/export.md
Transformer une vidéo en contenu (un article vs. structure)	references/content-from-video.md
Recettes de tâches courantes (upload→generate→publish, edit→republish, ajouter des images)	references/recipes.md
Comportement du produit (versionnement/restauration, ébauches/génération auto, images, traductions)	references/product-behavior.md

Liste de vérification de sortie

Laissez à l'utilisateur :

• La commande exécutée et sa sortie
• Le jobId si l'opération est asynchrone et que --wait n'a pas été utilisé
• La prochaine étape de vérification (ex. hinto videos status <id>, hinto generate status <jobId>)
• Toute mention de périmètre ou d'authentification ayant affecté le résultat