Hinto CLI スキル
このスキルは、Hintoの全ターミナルワークフロー（インストール、認証、全コマンドグループ、非同期ジョブ処理、コマンドのチェーン実行）をカバーします。
インストール
このスキルは hinto CLI を駆動します。
パッケージ名: コマンドは
hintoですが、npm パッケージは@hintoai/cliです。@hinto/cliやhintoを推測しないでください — それらは存在せず、404 エラーになります。 常にパッケージは@hintoai/cliとしてインストール、アップグレード、参照してください。
コマンドを実行する前に、CLI がインストールされていることを確認してください — hinto が PATH にない場合は、最初にインストールします:
# CLI をグローバルインストール
npm install -g @hintoai/cli
# 確認
hinto --version
最新バージョンにアップグレードするには、以下を実行します:
npm install -g @hintoai/cli@latest
その後、認証します（下記参照）。hinto コマンドが「command not found」で失敗した場合は、上記のインストール手順を再実行してください。
このスキル自体のインストール（任意のエージェント向け）は、ユニバーサルスキル CLI を使用して行います:
npx skills add hintoai/hinto-cli
認証
API キーの取得場所
API キーは プロジェクトごと（アカウント全体ではありません）— 各キーは単一のプロジェクトにスコープされ、CLI はキーが属するプロジェクトに対して動作します。作成するには:
- Hinto アプリ（
https://app.hintoai.com）でプロジェクトを開きます。 - 設定（トップバー）をクリックして プロジェクト設定 を開きます。
- API キーと Webhooks → API キー タブに移動します。
- 新しい API キー をクリックし、生成されたキーをコピーします。
キーの設定
環境変数を推奨します — CI で動作し、設定ファイルより優先されます:
export HINTO_API_KEY=hinto_...
インタラクティブ/ローカル使用の場合は、一度 init を実行します:
hinto init --key hinto_...
# ~/.hinto/config.json に書き込まれます — パーミッション 600
ステージング環境やセルフホストインスタンスを対象にするには、--api-url を使用します:
hinto init --key hinto_... --api-url https://staging.hintoai.com
# またはコマンドごと:
hinto articles list --api-url https://staging.hintoai.com
グローバルフラグ
これらのフラグは すべての コマンドで使用できます:
| フラグ | 目的 |
|---|---|
--json | 標準出力に生の JSON を出力 — コマンドをチェーンしたり出力を解析するときに使用 |
--api-url <url> | ベース URL を上書き（ステージング、セルフホスト） |
作業スタイル
このスキルがアクティブな場合:
- Bash 経由でコマンドを実行 —
hintoコマンドを直接実行し、単に説明するだけにしないでください。 - チェーンするときは
--jsonを使用 — JSON 出力をパイプまたは解析して次のコマンドに渡します。 - 非同期ジョブには
--waitを使用 —generate startとgenerate structureのみサポート。--waitがない場合、これらは即座にjobIdを返します。publish now、publish republish、project retranslateは常に非同期（--waitなし）—hinto generate status <jobId>で手動でポーリングします。 - 最初に認証を確認 — コマンドが
UNAUTHORIZEDを返した場合、HINTO_API_KEYが設定されているか、hinto initが実行されているかを確認します。 - スピナーは stderr に出力 —
--waitを使用しても stdout はパイピングのためにクリーンなままです。
インタラクションパターン:
- 尋ねる vs. 自動 — 実際に選択肢がある場合（2つ以上）のみユーザーに確認します。選択肢が0～1の場合は、進めて使用した内容を明示します。
- 破壊的なアクションを確認 —
articles deleteとpublish unpublishの前に、何が削除またはオフラインになるかを正確に明示してユーザーに確認します。推測で実行しないでください。 - 出力の規律 — すべてのタスクを次のもので終了します: 実行したコマンドとその結果、
--waitを使用しなかった非同期ジョブのjobId、利用可能なリンク（editUrl/previewUrl）、および次の確認手順。
オリエンテーション — ここから開始
まずこれらを実行して、キーが対象とするプロジェクトを把握します（キーは プロジェクトごと — あなたは正確に1つのプロジェクトに対して動作します）:
hinto project get --json # 名前、タイプ、公開状態、カスタムドメイン
hinto project structure --json # フォルダ + 記事ツリー
hinto publish status --json # 公開されているか、どのURLか
結果がユーザーの期待と一致しない場合、キーは異なるプロジェクトを対象としている可能性があります — ユーザーが正しいキーを提供する必要があります。あなたはプロジェクトを切り替えることはできません。
スコープ
各 API キーにはスコープが含まれています。スコープがない場合、操作は INSUFFICIENT_SCOPE（403）で失敗します:
| スコープ | 許可される操作 |
|---|---|
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 |
回復方法: 不足しているスコープをユーザーに伝えます — そのスコープを含む新しいキーをアプリ UI で作成する必要があります。
ID と状態の注意点
- 記事とフォルダの ID は 整数 です。ジョブ ID は uuid です。
slugとpreviewUrlは 公開されるまで null です（また、現在の公開スナップショットに含まれていない記事の場合も null です）。generate start/generate structureの前に、動画はready状態である必要があります。generate structureは 空のスタブ を生成します。完全な記事ではありません —references/product-behavior.mdを参照してください。- レート制限: キーあたり 60 req/min（
RATE_LIMITED429 →Retry-Afterまで待機）。生成はQUOTA_EXCEEDEDを返す場合があります。
CLI ではできないこと（アプリ UI のみ）
これらのためのコマンドを 発明しないでください — これらは Hinto ウェブアプリに存在します:
- プロジェクトまたは API キーの作成
- ワークスペース / 請求管理
- 文書化されたコマンドで公開されていないブランディングや公開設定の編集
コアワークフロー: アップロード → 生成 → 公開
# 1. ローカルの動画ファイルをアップロード
hinto videos upload --file ./video.mp4 --json
# → { "videoId": "..." }
# または URL からインポート（Job オブジェクトを返します — 完了するまでポーリングして videoId を取得）
hinto videos import --url https://example.com/video.mp4 --json
# → { "jobId": "...", "type": "import_video_url", "status": "pending", "output": null, ... }
# その後ポーリング: hinto generate status <jobId> — 完了した出力に videoId が含まれます
# 2. 動画が ready になるまで待機
hinto videos status <videoId> --json
# → { "videoId": "...", "status": "ready", ... }
# 3. 利用可能なテンプレートを一覧表示
hinto templates article --json
# 4. 記事を生成し、完了を待機
hinto generate start --video <videoId> --template <templateId> --wait --json
# 4b. 新しい記事へのリンクをユーザーに渡す（editUrl は常に存在、previewUrl は公開時のみ）
hinto articles get <articleId> --json # → editUrl + previewUrl を含む
# 5. プロジェクトを公開（非同期 — 即座に jobId を返す）
hinto publish now --json
# → { "jobId": "...", "type": "publish", "status": "pending", ... }
# ポーリング: hinto generate status <jobId>
カテゴリルーティング
該当するコマンドグループのリファレンスファイルを読んでください:
| タスク | リファレンスファイル |
|---|---|
| 動画のアップロード、インポート、管理 | references/videos.md |
| 記事の作成、編集、移動、翻訳 | references/articles.md |
| フォルダの作成と整理 | references/folders.md |
| 動画から記事または構造を生成 | references/generate.md |
| プロジェクト情報、構造ツリー、言語 | references/project.md |
| 公開、再公開、非公開 | references/publish.md |
| 利用可能なテンプレートの参照 | references/templates.md |
| 記事、フォルダ、またはプロジェクト全体のエクスポート | references/export.md |
| 動画をコンテンツに変換（1記事 vs 構造） | references/content-from-video.md |
| 一般的なタスクレシピ（アップロード→生成→公開、編集→再公開、画像追加） | references/recipes.md |
| プロダクト動作（バージョニング/復元、スタブ/自動生成、画像、翻訳） | references/product-behavior.md |
出力チェックリスト
ユーザーに次のものを残してください:
- 実行したコマンドとその出力
--waitを使用しなかった非同期ジョブのjobId- 次の確認手順（例:
hinto videos status <id>、hinto generate status <jobId>） - 結果に影響を与えたスコープや認証に関する注意点