Hinto CLI Skill
이 스킬은 모든 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 키 및 웹훅 → 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을 stdout으로 출력 — 명령어 연결 또는 출력 구문 분석 시 사용 |
--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), 다음 확인 단계.
시작 — 여기서 시작하세요
먼저 다음을 실행하여 키가 대상으로 하는 프로젝트에 익숙해지십시오(키는 프로젝트별 — 정확히 하나의 프로젝트에서 작동합니다):
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입니다(현재 게시 스냅샷에 없는 아티클의 경우도 해당).- 비디오는
generate start/generate structure전에ready상태여야 합니다. generate structure는 빈 스텁을 생성하며, 전체 아티클이 아닙니다. 자세한 내용은references/product-behavior.md를 참조하십시오.- 속도 제한: 키당 분당 60회(
RATE_LIMITED429 →Retry-After기다림). 생성은QUOTA_EXCEEDED를 반환할 수 있습니다.
CLI에서 수행할 수 없는 작업(앱 UI만 가능)
다음 작업에 대한 명령어를 만들지 마십시오. 이는 Hinto 웹 앱에 있습니다:
- 프로젝트 또는 API 키 생성
- 워크스페이스 / 결제 관리
- 문서화된 명령어로 노출되지 않은 브랜딩 및 게시 설정 편집
핵심 워크플로우: 업로드 → 생성 → 게시
# 1. 로컬 비디오 파일 업로드
hinto videos upload --file ./video.mp4 --json
# → { "videoId": "..." }
# 또는 URL에서 가져오기(Job 객체 반환 — completed될 때까지 폴링하여 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. 비디오가 준비될 때까지 대기
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 |
| 비디오를 콘텐츠로 전환(단일 아티클 vs 구조) | references/content-from-video.md |
| 일반 작업 레시피(업로드→생성→게시, 편집→재게시, 이미지 추가) | references/recipes.md |
| 제품 동작(버전 관리/복원, 스텁/자동 생성, 이미지, 번역) | references/product-behavior.md |
출력 체크리스트
사용자에게 다음을 남겨주십시오:
- 실행한 명령어 및 출력
- 작업이 비동기이고
--wait를 사용하지 않은 경우jobId - 다음 확인 단계(예:
hinto videos status <id>,hinto generate status <jobId>) - 결과에 영향을 준 모든 범위 또는 인증 관련 주의사항