CLI 명령 참조

모의 실행 규칙과 명령 목록입니다.

공통 옵션

모든 명령에 붙일 수 있습니다.
옵션뜻
--json표준 출력에 JSON 문서 하나만 냅니다.
--execute쓰기나 체리를 쓰는 명령을 실제로 적용합니다. 없으면 모의 실행입니다.
--help그 명령의 사용법을 봅니다.
--version버전을 봅니다. 명령 없이 --version만 줄 때 동작합니다.
mellowz나 mellowz help만 치면 전체 명령 목록이 나옵니다. 목록에 없는 명령이나 옵션은 종료 코드 1로 끝납니다.

쓰기 명령의 모의 실행

쓰기 명령은 같은 경로를 읽기 도구만으로 먼저 거칩니다. 무엇이 호출될지 보여 주고, 적용은 하지 않습니다.
명령모의 실행(기본)--execute
doc create같은 이름의 문서가 있는지 보여 줍니다.빈 문서를 만듭니다.
doc propose연산을 시험 적용해 결과만 봅니다.승인 대기 제안을 올립니다. 승인은 앱에서 합니다.
batch create기존 배치와 예상 체리를 보여 줍니다.배치를 제출하고 체리를 씁니다.
batch cancel, batch retry현재 배치 상태를 읽습니다.취소하거나 재시도합니다.
모의 실행이 끝나면 표준 오류에 dry-run: nothing was changed; pass --execute to apply가 나옵니다. --json의 dryRun도 true입니다.

명령 목록

명령은 모두 11개입니다. doctor는 네트워크 없이 환경을 점검합니다(설정).
명령하는 일종류
doc create빈 캐릭터 문서를 만듭니다.쓰기
doc list내 캐릭터 문서를 최신순으로 봅니다.읽기
doc read문서의 한 섹션과 현재 revision을 읽습니다.읽기
doc simulate수정 연산을 서버 사본에 시험 적용합니다.읽기
doc propose수정 연산을 승인 대기 제안으로 올립니다.쓰기
proposals list문서의 제안 목록을 봅니다.읽기
import normalize외부 플랫폼 덤프를 정규화해 미리 봅니다. 아무것도 저장하지 않습니다.읽기
batch create캐릭터 브리프를 배치로 제출합니다.체리 사용
batch get배치 상태와 항목별 진행을 봅니다.읽기
batch cancel실행 중인 배치를 취소하고 쓰지 않은 예약을 돌려받습니다.쓰기
batch retry다시 시도할 수 있는 실패 항목을 재시도합니다.체리 사용
doctor서버 주소와 토큰을 점검합니다.로컬

명령별 사용법

doc create

사용법 — text
mellowz doc create --title <이름> --key <재시도 키> [--execute]
옵션필수뜻
--title예캐릭터 이름이자 문서 제목입니다. 1~200자입니다.
--key예재시도 키입니다. 8~128자입니다. 같은 키와 같은 제목은 같은 문서 하나로 모입니다.

doc list

사용법 — text
mellowz doc list [--query <글자>] [--limit <수>] [--cursor <커서>]
옵션뜻
--query제목 검색어입니다. 1~100자입니다.
--limit한 번에 볼 개수입니다. 1~100의 정수입니다.
--cursor이전 결과가 준 다음 쪽 커서입니다.

doc read

사용법 — text
mellowz doc read <문서 id> --section <섹션>
--section은 필수이고 다음 중 하나입니다: identity, appearance, voice, persona, chatProfile, openings, lore, situations, stats, endings, episodes, registration.

doc simulate

사용법 — text
mellowz doc simulate <문서 id> --operations <파일|->
--operations는 필수입니다. 수정 연산 1~20개가 든 JSON 파일 경로입니다. -를 주면 표준 입력에서 읽습니다. 시험 적용이 실패하면(ok:false) 결과를 그대로 보여 주고 종료 코드 2로 끝납니다.

doc propose

사용법 — text
mellowz doc propose <문서 id> --operations <파일|-> [--expected-revision <수>] [--rationale <글>] [--execute]
옵션필수뜻
--operations예doc simulate와 같은 연산 JSON입니다.
--expected-revision아니오제안이 기대하는 문서 revision입니다. 없으면 방금 시험 적용에서 받은 revision을 씁니다. 그 사이 문서가 바뀌었으면 종료 코드 4입니다.
--rationale아니오제안 이유입니다. 2,000자까지입니다.
먼저 시험 적용을 하고, 실패하면 제안하지 않고 종료 코드 2로 끝납니다.

proposals list

사용법 — text
mellowz proposals list <문서 id> [--status pending|applied|rejected] [--limit <수>] [--cursor <커서>]
--status를 생략하면 pending입니다. --limit은 1~100입니다.

import normalize

사용법 — text
mellowz import normalize --platform <플랫폼> --source <파일|->
옵션필수뜻
--platform예crack, zeta, whif, babyChat, playtoon 중 하나입니다.
--source예덤프 JSON 파일입니다. -는 표준 입력입니다. 최상위 키는 200개까지입니다.

batch create

사용법 — text
mellowz batch create --batch-id <id> --items <파일|-> [--execute]
옵션필수뜻
--batch-id예배치 id입니다. 128자까지이고 영문·숫자로 시작하며 . _ : -를 쓸 수 있습니다. 같은 id로 다시 보내면 같은 요청입니다.
--items예항목 1~150개가 든 JSON 배열 파일입니다. -는 표준 입력입니다.
모의 실행은 같은 id의 기존 배치(existingBatch)와 예상 체리(estimatedCherry)를 보여 줍니다. 예상 체리는 항목 수에 항목당 1체리를 곱한 값입니다.

batch get

사용법 — text
mellowz batch get <배치 id>

batch cancel, batch retry

사용법 — text
mellowz batch cancel <배치 id> [--expected-run-revision <수>] [--execute]
mellowz batch retry <배치 id> [--expected-run-revision <수>] [--execute]
--expected-run-revision을 생략하면 방금 읽은 배치의 revision을 씁니다. 없는 배치는 종료 코드 2로 끝납니다.

기계 판독 출력

--json 출력은 한 줄 JSON 문서이며 필드는 다음과 같습니다. --json이 없으면 표준 출력에는 결과 데이터만 사람이 읽기 좋게 나옵니다. 실패 이유는 표준 오류에 error (종류): 메시지로 나옵니다.
필드뜻
ok성공 여부
exit종료 코드
command실행한 명령
dryRun모의 실행이었는지
data결과 데이터
error실패하면 kind와 message, 아니면 null
JSON 출력으로 문서 목록 읽기 — bash
pnpm --filter @mellowz-studio/cli start -- doc list --limit 5 --json

CLI가 하지 않는 일

이미지·영상 생성, 작업 상태 조회, 에셋 업로드, 브라우저 로그인, 제안 승인은 CLI에 없습니다. MCP나 공개 REST를 쓰세요. 제안 승인은 앱에서 합니다.

관련