CLI Skill 사용 가이드

NadouPro CLI 기능 소개

이 문서는 NadouPro CLI를 사용하는 사용자와 Agent를 대상으로 설치, 로그인, 모델 탐색, 콘텐츠 생성, 작업 전달, 공간 관리, 로컬 미디어 처리, Canvas 조작을 안내합니다. CLI의 구체적 기능은 버전, 계정, 시나리오에 따라 달라지므로 nadou capability list --json, 명령 반환 결과, 실제 산출물을 기준으로 하세요.

권장

설치 또는 업그레이드 후 먼저 nadou version --json과 nadou capability list --json을 실행해 현재 버전과 사용 가능한 기능을 확인하세요.

주의

쓰기, 생성, 삭제, 덮어쓰기가 관련된 작업은 “한 번 제출, 자동 재시도 없음, 결과가 불확실하면 원래 작업을 조회” 원칙을 따르세요. Cookie, token, Authorization 등 로그인 자격 증명을 공유하거나 기록하지 마세요.

1. 빠른 시작

1.1 설치

Node.js 16 이상이 필요합니다. npm 공용 레지스트리 설치를 권장합니다.

한 줄 설치 안내: NadouPro CLI를 설치해 주세요: npm install -g @iqiyi-intl-nadoupro/nadou-cli. 설치가 끝나면 nadou version --json으로 확인하세요.

npm exec --yes --registry=https://registry.npmjs.org/ --package=@iqiyi-intl-nadoupro/nadou-cli@latest -- nadou-install
nadou version --json
nadou skill install --json
nadou skill read --json

전역 설치도 가능합니다.

npm install -g @iqiyi-intl-nadoupro/nadou-cli
nadou version --json

현재 지원: Windows x64, Linux x64/arm64, macOS x64/arm64. npm이 해당 플랫폼 의존성을 자동 선택합니다. 설치 시 optional dependencies를 끄면 정상 설치 방식으로 다시 설치하세요.

1.2 업데이트 확인 및 업그레이드

nadou version --check --json
nadou update --json --no-interactive
nadou version --json

업그레이드 후 nadou skill install --json을 다시 실행해 로컬 Skill이 CLI 버전과 일치하도록 하세요.

1.3 구성 및 로그인

로그인은 시스템 브라우저에서 국제판 로그인 페이지를 엽니다. “Continue to international sign in”을 클릭한 뒤 페이지가 안내하는 방식으로 국제 사이트 계정 로그인을 완료하세요. Profile은 공간, 제한 시간 등 비민감 설정을 저장하고, 로그인 세션은 로컬 시스템 자격 증명 저장소에 보관됩니다. 국제판의 로컬 구성과 로그인 세션은 따로 저장되므로, 국제판을 설치한 뒤 국제판 로그인 상태를 확인하세요.

nadou auth login --profile <profile>
nadou auth status --profile <profile> --json
nadou auth whoami --profile <profile> --json

<profile>을 이 기기에서 실제로 사용하는 Profile 이름으로 바꾸세요. 기본 Profile을 쓰면 CLI 안내에 따라 이 매개변수를 생략할 수 있습니다. Cookie, token, Authorization을 직접 복사, 붙여넣기, 기록하지 마세요.

서버 모드 로그인

서버, 컨테이너 또는 그래픽 인터페이스가 없는 환경에서는 로컬 브라우저를 열거나 운영 체제 자격 증명 저장소에 접근하지 못할 수 있습니다. 이런 환경에서는 별도의 서버 모드 로그인을 사용하세요:

nadou auth login --server --profile <profile>
nadou auth status --profile <profile> --json
nadou auth whoami --profile <profile> --json

CLI는 터미널에 로그인 URL과 인증 코드를 출력하고 기본적으로 10분 동안 기다립니다. 사용자는 원하는 기기의 브라우저에서 인증 코드를 입력하고 로그인한 뒤 계정을 확인할 수 있습니다. 로그인 페이지에서 계정을 전환할 수도 있습니다.

이 모드는 CLI 전용 비공개 파일에 자격 증명을 저장하므로 서로 다른 CLI 프로세스가 로그인 상태를 공유할 수 있습니다. 상태 디렉터리를 영구 보존하지 않으면 컨테이너 삭제 후 다시 로그인해야 합니다. 이 동작은 --server를 명시한 로그인에만 적용되며, 다른 로그인 방식은 시스템 자격 증명 저장소를 계속 사용합니다.

1.4 Agent 사용 전 확인

Agent 세션은 일반 터미널과 다른 PATH, 구성 디렉터리, 시스템 자격 증명 저장소를 사용할 수 있습니다. “명령을 찾을 수 없음”, “구성을 읽을 수 없음”, “신원 검증 실패”가 나오면 먼저 Agent를 재시작한 뒤 다음을 실행하세요.

1. nadou version --json

2. nadou auth status --profile <profile> --json

3. nadou auth whoami --profile <profile> --json

로그인 상태가 실제로 무효인 것이 확인된 뒤에만 다시 로그인하세요.

CREDENTIAL_STORE_UNAVAILABLE이 반환되고 현재 서버나 컨테이너가 시스템 자격 증명 저장소를 제공할 수 없다면 기본 로그인을 반복하지 말고 다음을 사용하세요:

nadou auth login --server --profile <profile>

2. 기능 개요와 공통 규칙

2.1 명령 면

기능 영역	주요 명령	역할
시스템과 Skill	version, update, config, doctor, skill, capability	버전, 구성, 진단, Skill 동기화, 기능 탐색
신원과 공간	auth, points, space	로그인, 포인트, 공간, 디렉터리, 전달 대상
모델과 생성	model, text, image, video, material	모델 탐색, 텍스트/이미지/비디오 작업, 소재 관리
작업과 전달	task, schedule, evidence	견적, 제출, 관찰, 다운로드, 예약, 보고, 검수 증거
Canvas	canvas	캔버스, Graph, 노드, 연결선, Timeline, 완성본 보내기
로컬 미디어	media	로컬 파일을 처리하며 서버 생성 작업을 대체하지 않음

전체 명령과 현재 개방 범위는 nadou capability list --json을 따릅니다. 개별 기능은 nadou capability describe <command> --json으로 역할, 제한, 비동기 여부, 참고 명령을 확인하세요.

2.2 출력과 전역 매개변수

모든 명령은 안정적인 --json 출력을 지원합니다. 장시간 관찰, 이벤트 스트림, 재귀 디렉터리 내용은 --jsonl을 사용할 수 있습니다. 자주 쓰는 전역 매개변수는 --profile, --timeout, --trace-id, --no-interactive, --yes입니다.

• --json: 프로그램이 처리하기 좋은 구조화 결과를 반환합니다.

• --jsonl: 이벤트나 재귀 결과를 줄 단위로 출력해 지속 관찰에 적합합니다.

• --no-interactive: 대화형 프롬프트를 끕니다. 비용 확인을 의미하지 않습니다.

• --yes: 삭제, 덮어쓰기 같은 파괴적 작업을 확인합니다. 비용 승인을 의미하지 않습니다.

• --trace-id: 한 워크플로의 문제 추적을 연관시킵니다. 작업 ID나 멱등 키가 아닙니다.

2.3 Profile, 공간, 프로젝트 경계

Profile은 환경, 게이트웨이 주소, 제한 시간, 인증 모드, 기본 공간, 기본 모델 등 비민감 설정을 저장합니다. 공간, 모델, Canvas 컨텍스트는 각각 탐색하고 선택해야 합니다. 공간을 전환해도 다른 프로젝트 바인딩이 암묵적으로 만들어지거나 복원되지 않습니다.

2.4 시나리오 라우팅

시나리오	권장 담체	실행 요점
단일 텍스트, 이미지, 비디오 또는 기타 원자 기능	원자 작업	제출 전에 매개변수, 대상 공간, 권한, 예상 소모를 확인합니다.
여러 소재, 여러 단계, 캐릭터 일관성, MV, 광고, 단편	대상 공간/디렉터리 + Canvas	계정, 공간, 디렉터리를 먼저 명확히 하고 대본이나 스토리보드를 마친 뒤 고비용 단계로 들어갑니다.
기존 Canvas 수정	원래 Canvas를 읽고 수정	쓰기 전에 실시간 캔버스를 읽고, 쓴 뒤 다시 읽어 검증합니다. 덮어쓰기, 삭제, 충돌 시 먼저 확인합니다.
예약 생성	CLI가 현재 개방한 예약 모드	만들기 전에 시간, 시간대, 계정, 공간, 예상 소모를 확인합니다.

사용자가 NadouPro, 텍스트, 이미지, 비디오, 소재, 공간, 캔버스, 노드, 참고 이미지, 첫/끝 프레임 등을 분명히 언급하면 Nadou Skill을 우선 사용하세요. 현재 CLI가 지원하지 않는 기능은 분명히 설명하고, 비슷한 기능으로 대체하지 마세요.

3. 모델 탐색과 콘텐츠 생성

3.1 모델과 시나리오를 먼저 탐색

nadou model list --type image --json
nadou model list --type video --json
nadou model family "<모델 표시 이름>" --json
nadou model scenarios "<model-id>" --json
nadou model get <model-id> --json
nadou model schema <model-id> --json
nadou model use image <image-model> --profile <profile>
nadou model use video <video-model> --profile <profile>

모델 표시 이름, 매개변수, 사용 가능한 시나리오는 서버 카탈로그가 결정합니다. Agent나 스크립트에서 모델 이름을 추측하지 마세요. 시나리오 또는 Schema를 먼저 읽고 맞는 매개변수를 제출하세요.

3.2 생성 기능과 시나리오

명령	흔한 시나리오	핵심 입력
nadou text	text2text, image_to_text	프롬프트, 선택적 HTTPS 참고 이미지
nadou image	text2img, image_ref, panorama, three_view, inpaint	프롬프트, 참고 이미지, 마스크, 비율, 해상도, 수량
nadou video	text2video, first_last_frame, multi_reference, video_edit, motion_control	프롬프트, 길이, 비율, 해상도, 참고 비디오/이미지/오디오

프롬프트는 --prompt, --prompt-file, --stdin으로 제공할 수 있으며 최대 1 MiB, 유효한 UTF-8이어야 합니다. Agent가 --json, --jsonl, --no-interactive를 사용할 때는 프롬프트 출처를 명시해야 합니다. 미리보기와 비용 확인 후 정식 생성에는 --submit이 필요합니다. 위치 매개변수의 적용 조건은 명령 도움말을 따릅니다. --dry-run은 요청을 구성하고 검증만 하며 작업을 제출하지 않습니다. 이미지와 비디오는 기본적으로 제출만 하고 기다리지 않으며, --wait를 써야 같은 명령에서 완료를 관찰합니다.

현재 CLI에는 독립 AI 오디오 생성 명령이 없습니다. 비디오 작업은 시나리오에 따라 참고 오디오, 오디오 설정, 원음 유지 매개변수를 쓸 수 있지만, 이는 독립 오디오 생성과 같지 않습니다.

3.3 비용, 확인, 전달

비용 확인

비용이 발생할 수 있는 작업은 “dry-run → 포인트 조회 → 견적 → 예상 소모 설명 및 확인 → 정식 제출” 순서로 실행하세요. 잔액이 비어 있거나 무제한이거나 잠시 확인할 수 없어도 견적, 예산 설명, 최종 확인을 건너뛰면 안 됩니다.

대응 명령은 보통 nadou points summary, nadou task estimate, nadou task submit입니다. 견적은 최종 가격을 고정하지 않으며, 제출 전에 실제 반환 결과로 다시 확인해야 합니다.

독립 이미지/비디오 생성과 산출물 전달은 두 단계입니다. 기본 전달 대상은 개인 루트 디렉터리입니다. 팀 공간, 디렉터리, 복사 또는 이전 정책은 명시적으로 지정해야 합니다. CLI는 기본적으로 산출물을 다운로드하지 않고, 로컬 미디어 처리도 기본적으로 실행하지 않습니다.

4. 작업, 예약, 전달, 증거

4.1 작업 수명 주기

자주 쓰는 명령은 task estimate, task submit, task status, task wait, task events, task outputs, task report, task history, task download, task download-batch, task terminate입니다.

task events는 지속 관찰에 사용할 수 있습니다. 일괄 다운로드는 재개 가능한 manifest를 쓰며 긴 작업이나 다중 산출물 전달에 적합합니다. 쓰기 제출은 자동 재시도하지 않습니다. 프로세스가 중단되거나 네트워크가 시간 초과되거나 응답을 파싱할 수 없으면 원래 task, request, 상태 기록을 먼저 조회하고 새 제출을 만들어 재시도하지 마세요.

4.2 예약 작업

모드	적용 방식	주요 제한
server	이미지/비디오 또는 일부 Canvas 노드 생성	일반 텍스트 일정, 일정 관리, DAG 오케스트레이션을 약속하지 않습니다.
local	일반 이미지/비디오와 독립 텍스트 생성	Canvas, 프로젝트 컨텍스트, 외부 참조 URL을 포함하지 않습니다.

예약 기능은 disabled, local, server를 명시적으로 선택하고 IANA 시간대를 사용해야 합니다. 만들기 전에 시간, 시간대, 계정, 공간, 예상 소모를 확인한 뒤 현재 capability에 따라 모드를 고르세요.

예시: nadou schedule create --body-file request.json --scheduled-at <time> --timezone <iana-timezone> --max-points <확인된 포인트 상한>. 구체적 지원 범위는 명령 반환 결과를 따릅니다.

4.3 공간, 디렉터리, 소재

• space current/list/use: 공간을 보고 전환합니다.

• space directory create/list/contents: 디렉터리를 관리하고 내용을 봅니다. 재귀 내용은 --recursive --jsonl을 사용할 수 있습니다.

• space file rename: 파일을 명시적으로 이름 변경합니다.

• space artifact deliver: 신뢰할 수 있는 작업 산출물을 대상 공간 또는 디렉터리로 복사하거나 이전합니다.

• material upload: 로컬 소재를 업로드하며 분할 업로드와 선택적 워터마크 매개변수를 지원합니다.

• material delete: 소재를 삭제합니다. 영구 삭제는 --permanent를 명시하고 확인해야 합니다.

소재 업로드는 작업 산출물 전달과 같지 않으며 Canvas 노드를 자동 생성하지도 않습니다.

4.4 검수 증거

evidence generation은 알려진 task ID로 버전 관리되는 로컬 증거를 만들 수 있습니다. evidence delivery는 다운로드 manifest, 미디어 파일, 기술 검증 결과, 사람 확인을 결합해 전달 증거를 만들 수 있습니다. evidence validate는 증거 구조, 경로, 해시, 참조만 검증하며 재시도, 다운로드, 전달, Canvas 쓰기를 유발하지 않습니다.

기술 검증 통과는 창작 품질 심사와 같지 않습니다. 정식 전달에는 버전, task ID, 마스킹된 request ID, 산출물 해시, 미디어 검사 결과, 필요한 사람 확인을 남기고 token, Cookie, 전체 Authorization은 저장하지 마세요.

4.5 Agent 상호작용, 산출물 제시, 복구

제출 전에 계정, 공간, 디렉터리, Canvas가 유일하지 않으면 선택지와 예상 저장 위치를 먼저 설명해야 합니다. 모델 매개변수, 첫/끝 프레임 역할, 일괄 규모가 불명확하면 정보를 먼저 보완해야 합니다. 일괄, 고비용, 삭제, 덮어쓰기, 이동, 협업 충돌이 있으면 영향을 먼저 설명하고 확인을 받아야 합니다.

• 이미지: 실제 수량을 밝히고 각 실제 산출물과 공간 경로를 반환합니다.

• 비디오 또는 기타 미디어: 실제 재생/다운로드 진입점과 공간 경로를 반환합니다. 작업 페이지나 썸네일은 최종 산출물을 대체할 수 없습니다.

• 텍스트: 본문을 바로 제시합니다. 공간에 저장되지 않았으면 이유를 분명히 설명합니다.

• 복잡한 Canvas: 최종 산출물, 공간 경로, Canvas 이름, 실제 진입점을 제시하고 완료된 단계와 미완료 단계를 구분합니다.

• 부분 성공: 성공 항목을 먼저 전달한 뒤 실패 항목과 재작업 옵션을 따로 나열합니다. 전체 주문을 완전 성공이나 완전 실패로 위장하지 마세요.

전달 주의 사항

공간 경로와 실제 산출물 진입점은 전달 정보의 일부입니다. 서버의 실제 반환값이 없거나 다운로드가 끝나지 않았으면 로컬 경로, 작업 페이지, 중간 상태를 최종 산출물이라고 하지 마세요.

각 쓰기 또는 제출 단계는 한 번만 실행합니다. 시간 초과, 네트워크 오류, 응답을 파싱할 수 없으면 원래 task 또는 원래 작업 상태를 조회하세요. 멱등 키를 바꾸거나 다시 제출하거나, 결과가 잠시 없다고 해서 다시 생성하지 마세요. 생성 실패, 저작권 제한, 모델 거부가 있으면 하류 단계를 멈추세요. 사용자가 취소하면 취소를 한 번만 실행하고 최종 상태를 대조하세요.

5. 로컬 미디어 처리

nadou media는 로컬 파일만 처리합니다. 네트워크 생성 서비스를 호출하지 않고, 입력 파일을 수정하지 않으며, 기본적으로 기존 출력을 덮어쓰지 않습니다. 검사, 표준화, 이어붙이기, 합성, 프레임 추출, 기술 검증, 자막 처리, 오디오/비디오 먹싱을 지원합니다.

자주 쓰는 표준 프리셋은 가로, 세로, 정사각형 1080p입니다. 일반 출력은 MP4/H.264, yuv420p, 30fps, AAC-LC, 48kHz, 스테레오입니다. verify는 기술 검사이며 보고서의 creative_review_required는 여전히 사람 검토가 필요함을 뜻합니다.

로컬 미디어 처리와 Canvas Timeline/완성본 보내기는 서로 다른 기능입니다. 전자는 로컬 파일을 처리하고, 후자는 Canvas Graph와 연결된 타임라인을 읽고 쓰며 서버 완성본 작업을 실행합니다.

6. Canvas 관리와 Graph

6.1 조작 원칙

1. 먼저 canvas get으로 대상 캔버스의 최신 상태를 읽습니다.

2. 현재 노드, 연결선, 레이아웃을 기준으로 한 번의 쓰기를 구성합니다.

3. 쓰기 후 다시 읽어 노드, 연결선, 산출물 상태를 확인합니다.

4. 잠금, 협업 충돌, 권한 문제, 불명확한 결과가 있으면 추가 쓰기를 멈추고 원래 작업 상태를 먼저 본 뒤 영향을 설명합니다.

CLI는 노드 유형에 따라 쓸 수 있는 필드를 검증합니다. 사용자는 명령, 입력, 출력, 상태, 오류 처리만 보면 되며 서비스 주소, 리소스 URL, 작업 상태를 직접 이어 붙일 필요가 없습니다.

6.2 자주 쓰는 명령

분류	명령
수명 주기	canvas list/create/get/rename/move/delete/restore
읽기	canvas get, canvas node list, canvas assets list
Graph	canvas graph mutate
노드	canvas node list/create/patch/delete/estimate/generate/wait
연결선	canvas edge connect/patch/delete
Timeline	canvas media timeline validate/write/read
완성본	canvas media export prepare/submit/observe

6.3 캔버스, 노드, 소재

canvas list는 현재 접근 가능한 캔버스를 찾고, canvas get은 실시간 Graph를 읽고, canvas node list는 유형별로 노드를 보고, canvas assets list는 과거 소재나 산출물 투영을 봅니다. 목록 결과를 쓰기 전 실시간 스냅샷으로 취급하지 마세요.

사용자 지정 미디어 노드는 공개 Canvas 노드 명령을 쓰고, 소재 ID 등 지원되는 필드를 입력으로 사용하세요. CLI 바깥에서 URL, metadata, 콜백, 작업 상태를 위조하지 마세요. 캔버스 충돌, 잠금, 부분 실패는 실제 오류 안내에 따라 처리하고, 대체 노드를 만들어 원래 문제를 가리지 마세요.

6.4 Timeline과 완성본

Timeline 파일은 먼저 오프라인 검증을 한 뒤 현재 capability에 따라 완성본 흐름을 선택합니다. Timeline 쓰기, 보내기 준비, 제출, 관찰은 서로 독립된 작업이며 각 단계는 한 번만 실행합니다. 상태 조회가 처리 중, 찾을 수 없음, 알 수 없음을 반환하면 원래 작업만 계속 조회하고 경로를 바꾸거나 다시 제출하지 마세요.

실제 완성본이 가능한지는 유효한 Canvas 노드, Timeline, 작업 상태, 현재 개방 기능에 달려 있습니다. 게시나 전달 시에는 실제 명령 반환과 최종 산출물을 기준으로 하세요.

7. 현재 CLI의 기능 경계

CLI 개방 면은 버전, 계정, 시나리오에 따라 달라질 수 있습니다.

제품 페이지의 완전한 워크플로가 CLI로 열려 있지 않을 수 있습니다. 예: 디렉터 스테이지, 전체 이미지 편집과 주석, 작업대 파일 관리, 편집대, 오디오 트랙 편집, 각본 도우미. CLI는 image-tool upscale 같은 일부 이미지 처리 명령을 이미 제공합니다. 구체적 범위는 현재 명령 도움말과 실제 반환을 따릅니다. 이런 기능이 필요하면 제품 진입점을 직접 사용하고, 제품 페이지와 CLI의 현재 capability를 기준으로 하세요.

8. 문제 위치 파악과 피드백

8.1 흔한 문제

• 캔버스 노드를 찾을 수 없음: 먼저 canvas get으로 실시간 Graph를 가져온 뒤 캔버스 식별자, 노드 유형, 노드 상태, 연결된 task가 아직 유효한지 확인하세요.

• 생성 명령이 task ID를 만들기 전에 종료됨: 작업이 아직 제출되지 않은 것입니다. “생성 실패”라고 말하지 말고 다시 제출하지도 마세요.

• task ID를 받은 뒤 시간 초과: 원래 task를 계속 조회하고 다시 생성하지 마세요.

• Canvas 쓰기 결과가 불명확함: 원래 작업 상태를 조회하고 최종 캔버스 상태를 확인한 뒤 다음 단계를 결정하세요.

• Agent가 터미널 로그인 상태를 보지 못함: 먼저 Agent를 재시작하고 PATH, 구성 디렉터리, 시스템 자격 증명 저장소를 확인한 뒤 1.4절의 확인 명령을 실행하세요.

8.2 피드백 템플릿

피드백에는 최소한 실행 명령, CLI 버전, 운영 체제와 아키텍처, 사용한 모델, Canvas 식별자 또는 task ID, 마스킹된 request ID/trace ID, 오류 코드, 최종 상태, 실제 산출물 URL이 포함되어야 합니다.

Cookie, token, Authorization, 전체 요청 헤더, 로컬 자격 증명, 마스킹되지 않은 기타 민감 정보는 첨부하지 마세요.

8.3 자주 묻는 질문

dry-run 뒤에 왜 여전히 estimate와 확인이 필요한가요?

dry-run은 요청 구조와 매개변수만 검증합니다. 서버 견적, 잔액 판단, 최종 제출을 의미하지 않습니다. 비용 관련 작업은 여전히 포인트를 조회하고, 견적하고, 예산을 설명하고, 확인을 받은 뒤 정식 제출을 한 번 실행해야 합니다.

Skill을 CLI와 어떻게 맞출까요?

CLI를 업그레이드한 뒤 nadou skill install --json을 함께 실행하고, nadou capability list --json으로 현재 명령이 실제로 열려 있는지 판단하세요. Agent 실행 시에는 이 기기에 동기화된 공식 Skill을 우선 사용하세요.

최종 산출물이 보이지 않는 이유는 무엇인가요?

먼저 원래 task의 상태와 outputs를 조회한 뒤 전달 공간과 디렉터리를 확인하세요. 진입점이 늦거나 썸네일이 잠시 없거나 한 번 조회가 실패했다고 해서 작업을 다시 제출하지 마세요.