hintoai/hinto-cli

Skill da CLI Hinto

Esta skill cobre todos os fluxos de trabalho do terminal Hinto: instalação, autenticação, todos os grupos de comandos, manipulação de tarefas assíncronas e encadeamento de comandos.

Instalação

Esta skill controla a CLI hinto.

Nome do pacote: o comando é hinto, mas o pacote npm é @hintoai/cli. Não adivinhe @hinto/cli ou hinto — esses não existem e resultarão em erro 404. Sempre instale, atualize e faça referência ao pacote como @hintoai/cli.

Antes de executar qualquer comando, certifique-se de que a CLI está instalada — se hinto não estiver no PATH, instale-o primeiro:

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

# Verificar
hinto --version

Para atualizar para a versão mais recente, execute:

npm install -g @hintoai/cli@latest

Em seguida, autentique-se (veja abaixo). Se um comando hinto falhar com "comando não encontrado", execute novamente a etapa de instalação acima.

Instalar esta skill em si (para qualquer agente) é feito com a CLI universal de skills: npx skills add hintoai/hinto-cli

Autenticação

Onde obter a chave da API

As chaves de API são por projeto (não por conta) — cada chave é vinculada a um único projeto, e a CLI age no projeto ao qual a chave pertence. Para criar uma:

1. Abra o projeto no aplicativo Hinto (https://app.hintoai.com).
2. Clique em Configurações (barra superior) para abrir as Configurações do Projeto.
3. Vá para Chaves de API e Webhooks → guia Chaves de API.
4. Clique em Nova Chave de API e copie a chave gerada.

Configurando a chave

Prefira a variável de ambiente — ela funciona em CI e substitui o arquivo de configuração:

export HINTO_API_KEY=hinto_...

Para uso interativo/local, execute init uma vez:

hinto init --key hinto_...
# Escreve ~/.hinto/config.json — permissões 600

Para direcionar um ambiente de staging ou uma instância auto-hospedada, use --api-url:

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

Flags Globais

Essas flags funcionam em todos os comandos:

Flag	Propósito
--json	Saída JSON bruta para stdout — use ao encadear comandos ou analisar saída
--api-url <url>	Substituir URL base (staging, auto-hospedado)

Estilo de Trabalho

Quando esta skill estiver ativa:

1. Execute comandos via Bash — execute comandos hinto diretamente, não apenas descreva-os.
2. Use --json ao encadear — canalize ou analise a saída JSON para alimentar o próximo comando.
3. Use --wait para tarefas assíncronas — suportado apenas em generate start e generate structure. Sem --wait, esses comandos retornam imediatamente com um jobId. publish now, publish republish e project retranslate são sempre assíncronos (sem --wait) — consulte manualmente com hinto generate status <jobId>.
4. Verifique a autenticação primeiro — se um comando retornar UNAUTHORIZED, verifique se HINTO_API_KEY está definida ou se hinto init foi executado.
5. Spinner vai para stderr — stdout permanece limpo para pipe mesmo com --wait.

Padrões de interação:

6. Pergunte vs. automático — só pergunte ao usuário quando houver uma escolha real (2+ opções). Com 0–1 opções, prossiga e informe o que foi usado.
7. Confirme ações destrutivas — antes de articles delete e publish unpublish, confirme com o usuário, informando exatamente o que será removido ou retirado do ar. Nunca execute-as de forma especulativa.
8. Disciplina de saída — termine cada tarefa com: o(s) comando(s) executado(s) + resultado, qualquer jobId para trabalho assíncrono não aguardado, links (editUrl / previewUrl quando disponíveis) e o próximo passo de verificação.

Orientação — comece aqui

Execute estes comandos primeiro para se situar no projeto que a chave visa (a chave é por projeto — você age em exatamente um):

hinto project get --json          # nome, tipo, publicado, domínio personalizado
hinto project structure --json    # árvore de pastas + artigos
hinto publish status --json       # está no ar e em qual URL

Se os resultados não corresponderem à expectativa do usuário, a chave provavelmente visa um projeto diferente — o usuário deve fornecer a chave correta; você não pode trocar de projeto.

Escopos

Cada chave de API carrega escopos. As operações falham com INSUFFICIENT_SCOPE (403) quando um escopo está ausente:

Escopo	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

Recuperação: informe ao usuário qual escopo está ausente — uma nova chave com esse escopo deve ser criada na interface do aplicativo.

Peculiaridades de ID e estado

• IDs de artigos e pastas são inteiros; IDs de tarefas são uuids.
• slug e previewUrl são nulos até serem publicados (e para artigos não incluídos no snapshot atual da publicação).
• Um vídeo deve estar ready antes de generate start / generate structure.
• generate structure produz esqueletos vazios, não artigos completos — veja references/product-behavior.md.
• Limite de taxa: 60 req/min por chave (RATE_LIMITED 429 → aguarde Retry-After). A geração pode retornar QUOTA_EXCEEDED.

O que a CLI não pode fazer (apenas interface web)

Não invente comandos para estas funcionalidades — elas estão no aplicativo web Hinto:

• Criar um projeto ou uma chave de API
• Gerenciamento de workspace / faturamento
• Edição de marca e configurações de publicação não expostas por um comando documentado

Fluxo de Trabalho Principal: Upload → Gerar → Publicar

# 1. Fazer upload de um arquivo de vídeo local
hinto videos upload --file ./video.mp4 --json
# → { "videoId": "..." }

# OU importar de uma URL (retorna um objeto Job — consulte até concluído para obter o videoId)
hinto videos import --url https://exemplo.com/video.mp4 --json
# → { "jobId": "...", "type": "import_video_url", "status": "pending", "output": null, ... }
# Em seguida, consulte: hinto generate status <jobId> — a saída concluída contém o videoId

# 2. Aguardar até que o vídeo esteja pronto
hinto videos status <videoId> --json
# → { "videoId": "...", "status": "ready", ... }

# 3. Listar templates disponíveis
hinto templates article --json

# 4. Gerar um artigo e aguardar a conclusão
hinto generate start --video <videoId> --template <templateId> --wait --json

# 4b. Entregar ao usuário um link para o novo artigo (editUrl sempre presente; previewUrl quando publicado)
hinto articles get <articleId> --json   # → inclui editUrl + previewUrl

# 5. Publicar o projeto (assíncrono — retorna um jobId imediatamente)
hinto publish now --json
# → { "jobId": "...", "type": "publish", "status": "pending", ... }
# Consultar: hinto generate status <jobId>

Roteamento de Categorias

Leia o arquivo de referência para o grupo de comandos relevante:

Tarefa	Arquivo de referência
Upload, importação, gerenciamento de vídeos	references/videos.md
Criar, editar, mover, traduzir artigos	references/articles.md
Criar e organizar pastas	references/folders.md
Gerar artigos ou estrutura a partir de vídeo	references/generate.md
Informações do projeto, árvore da estrutura, idiomas	references/project.md
Publicar, republicar, despublicar	references/publish.md
Navegar pelos templates disponíveis	references/templates.md
Exportar artigos, pastas ou projeto completo	references/export.md
Transformar um vídeo em conteúdo (um artigo vs. estrutura)	references/content-from-video.md
Receitas de tarefas comuns (upload→gerar→publicar, editar→republicar, adicionar imagens)	references/recipes.md
Comportamento do produto (versionamento/restauração, esqueletos/geração automática, imagens, traduções)	references/product-behavior.md

Checklist de Saída

Deixe o usuário com:

• O comando executado e sua saída
• O jobId se a operação for assíncrona e --wait não foi usado
• O próximo passo de verificação (ex.: hinto videos status <id>, hinto generate status <jobId>)
• Quaisquer ressalvas de escopo ou autenticação que afetaram o resultado