hintoai/hinto-cli

Hinto CLI Skill

Dieser Skill deckt alle Hinto-Terminal-Workflows ab: Installation, Authentifizierung, alle Befehlsgruppen, asynchrone Jobverarbeitung und die Verkettung von Befehlen.

Installation

Dieser Skill steuert die hinto-CLI.

Paketname: Der Befehl lautet hinto, aber das npm-Paket ist @hintoai/cli. Nicht raten – @hinto/cli oder hinto existieren nicht und führen zu 404-Fehlern. Installieren, aktualisieren und referenzieren Sie das Paket immer als @hintoai/cli.

Bevor Sie einen Befehl ausführen, stellen Sie sicher, dass die CLI installiert ist – falls hinto nicht im PATH ist, installieren Sie es zuerst:

# CLI global installieren
npm install -g @hintoai/cli

# Überprüfen
hinto --version

Aktualisieren auf die neueste Version:

npm install -g @hintoai/cli@latest

Dann authentifizieren (siehe unten). Falls ein hinto-Befehl mit „command not found" fehlschlägt, führen Sie den obigen Installationsschritt erneut aus.

Die Installation dieses Skills selbst (für jeden Agenten) erfolgt mit der universellen Skills-CLI: npx skills add hintoai/hinto-cli

Authentifizierung

Wo erhalte ich den API-Schlüssel?

API-Schlüssel gelten pro Projekt (nicht kontoweit) – jeder Schlüssel ist auf ein einzelnes Projekt beschränkt, und die CLI agiert auf dem Projekt, zu dem der Schlüssel gehört. So erstellen Sie einen:

1. Öffnen Sie das Projekt in der Hinto-App (https://app.hintoai.com).
2. Klicken Sie auf Settings (obere Leiste), um die Project Settings zu öffnen.
3. Gehen Sie zu API Keys & Webhooks → Reiter API Keys.
4. Klicken Sie auf New Api Key und kopieren Sie den generierten Schlüssel.

Konfigurieren des Schlüssels

Bevorzugen Sie die Umgebungsvariable – sie funktioniert in CI und überschreibt die Konfigurationsdatei:

export HINTO_API_KEY=hinto_...

Für interaktive/lokale Nutzung führen Sie init einmal aus:

hinto init --key hinto_...
# Schreibt ~/.hinto/config.json – Berechtigungen 600

Um auf ein Staging-System oder eine selbst gehostete Instanz zu zielen, verwenden Sie --api-url:

hinto init --key hinto_... --api-url https://staging.hintoai.com
# oder pro Befehl:
hinto articles list --api-url https://staging.hintoai.com

Globale Flags

Diese Flags funktionieren bei jedem Befehl:

Flag	Zweck
--json	Gibt rohes JSON auf stdout aus – verwenden bei der Verkettung von Befehlen oder zum Parsen der Ausgabe
--api-url <url>	Überschreibt die Basis-URL (Staging, selbst gehostet)

Arbeitsstil

Wenn dieser Skill aktiv ist:

1. Befehle über Bash ausführen – hinto-Befehle direkt ausführen, nicht nur beschreiben.
2. --json bei Verkettung verwenden – JSON-Ausgabe pipen oder parsen, um den nächsten Befehl zu füttern.
3. --wait für asynchrone Jobs verwenden – wird nur bei generate start und generate structure unterstützt. Ohne --wait geben diese sofort mit einer jobId zurück. publish now, publish republish und project retranslate sind immer asynchron (kein --wait) – manuell mit hinto generate status <jobId> abfragen.
4. Zuerst Authentifizierung prüfen – wenn ein Befehl UNAUTHORIZED zurückgibt, überprüfen Sie, ob HINTO_API_KEY gesetzt ist oder hinto init ausgeführt wurde.
5. Spinner geht nach stderr – stdout bleibt sauber für Piping, auch mit --wait.

Interaktionsmuster:

6. Fragen vs. automatisch – den Benutzer nur fragen, wenn es eine echte Wahlmöglichkeit gibt (2+ Optionen). Bei 0-1 Optionen fortfahren und angeben, was verwendet wurde.
7. Destruktive Aktionen bestätigen – vor articles delete und publish unpublish den Benutzer bestätigen lassen, genau angeben, was entfernt oder offline genommen wird. Niemals spekulativ ausführen.
8. Ausgabedisziplin – jede Aufgabe beenden mit: den ausgeführten Befehl(en) + Ergebnis, einer jobId für asynchrone Arbeiten, auf die nicht gewartet wurde, Links (editUrl / previewUrl, falls verfügbar) und dem nächsten Überprüfungsschritt.

Orientierung – hier beginnen

Führen Sie diese zuerst aus, um sich im Projekt zu orientieren, das der Schlüssel adressiert (der Schlüssel gilt pro Projekt – Sie agieren genau auf einem):

hinto project get --json          # Name, Typ, ist veröffentlicht, benutzerdefinierte Domain
hinto project structure --json    # Ordner + Artikelbaum
hinto publish status --json       # Ist es live, und unter welcher URL

Wenn die Ergebnisse nicht den Erwartungen des Benutzers entsprechen, zielt der Schlüssel wahrscheinlich auf ein anderes Projekt – der Benutzer muss den richtigen Schlüssel bereitstellen; Sie können das Projekt nicht wechseln.

Berechtigungen (Scopes)

Jeder API-Schlüssel trägt Berechtigungen. Operationen schlagen mit INSUFFICIENT_SCOPE (403) fehl, wenn eine Berechtigung fehlt:

Berechtigung	Erlaubt
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

Wiederherstellung: dem Benutzer mitteilen, welche Berechtigung fehlt – ein neuer Schlüssel mit dieser Berechtigung muss in der App-UI erstellt werden.

ID- und Zustandsfallen

• Artikel- und Ordner-IDs sind Ganzzahlen; Job-IDs sind UUIDs.
• slug und previewUrl sind null bis zur Veröffentlichung (und für Artikel, die nicht im aktuellen Veröffentlichungs-Snapshot sind).
• Ein Video muss ready sein, bevor generate start / generate structure ausgeführt wird.
• generate structure erzeugt leere Platzhalter, keine vollständigen Artikel – siehe references/product-behavior.md.
• Ratenlimit: 60 req/min pro Schlüssel (RATE_LIMITED 429 → Retry-After abwarten). Generierung kann QUOTA_EXCEEDED zurückgeben.

Was die CLI nicht kann (nur App-UI)

Erfinden Sie keine Befehle für diese – sie befinden sich in der Hinto-Web-App:

• Erstellen eines Projekts oder eines API-Schlüssels
• Workspace-/Abrechnungsverwaltung
• Branding und Veröffentlichungseinstellungen, die nicht durch einen dokumentierten Befehl verfügbar sind

Kern-Workflow: Hochladen → Generieren → Veröffentlichen

# 1. Eine lokale Videodatei hochladen
hinto videos upload --file ./video.mp4 --json
# → { "videoId": "..." }

# ODER aus einer URL importieren (gibt ein Job-Objekt zurück – abfragen, bis abgeschlossen, um videoId zu erhalten)
hinto videos import --url https://example.com/video.mp4 --json
# → { "jobId": "...", "type": "import_video_url", "status": "pending", "output": null, ... }
# Dann abfragen: hinto generate status <jobId> – die abgeschlossene Ausgabe enthält die videoId

# 2. Warten, bis das Video bereit ist
hinto videos status <videoId> --json
# → { "videoId": "...", "status": "ready", ... }

# 3. Verfügbare Vorlagen auflisten
hinto templates article --json

# 4. Einen Artikel generieren und auf Abschluss warten
hinto generate start --video <videoId> --template <templateId> --wait --json

# 4b. Dem Benutzer einen Link zum neuen Artikel übergeben (editUrl immer vorhanden; previewUrl bei Veröffentlichung)
hinto articles get <articleId> --json   # → enthält editUrl + previewUrl

# 5. Das Projekt veröffentlichen (asynchron – gibt sofort eine jobId zurück)
hinto publish now --json
# → { "jobId": "...", "type": "publish", "status": "pending", ... }
# Abfragen: hinto generate status <jobId>

Kategorie-Routing

Lesen Sie die Referenzdatei für die entsprechende Befehlsgruppe:

Aufgabe	Referenzdatei
Videos hochladen, importieren, verwalten	references/videos.md
Artikel erstellen, bearbeiten, verschieben, übersetzen	references/articles.md
Ordner erstellen und organisieren	references/folders.md
Artikel oder Struktur aus Video generieren	references/generate.md
Projektinfo, Strukturbaum, Sprachen	references/project.md
Veröffentlichen, erneut veröffentlichen, zurückziehen	references/publish.md
Verfügbare Vorlagen durchsuchen	references/templates.md
Artikel, Ordner oder gesamtes Projekt exportieren	references/export.md
Ein Video in Inhalt umwandeln (ein Artikel vs. Struktur)	references/content-from-video.md
Häufige Aufgaben-Rezepte (hochladen→generieren→veröffentlichen, bearbeiten→erneut veröffentlichen, Bilder hinzufügen)	references/recipes.md
Produktverhalten (Versionierung/Wiederherstellung, Platzhalter/automatische Generierung, Bilder, Übersetzungen)	references/product-behavior.md

Ausgabe-Checkliste

Hinterlassen Sie dem Benutzer:

• Den ausgeführten Befehl und seine Ausgabe
• Die jobId, falls die Operation asynchron ist und --wait nicht verwendet wurde
• Den nächsten Überprüfungsschritt (z. B. hinto videos status <id>, hinto generate status <jobId>)
• Alle Berechtigungs- oder Authentifizierungshinweise, die das Ergebnis beeinflusst haben