CLI 레퍼런스

@sonamu-kit/cli 0.1.0은 sonamu 실행 파일을 제공하는 유일한 패키지입니다. API 프로젝트에서 sonamu와 함께 직접 설치하세요. sonamu 패키지는 이전 CLI를 대신 실행하는 호환용 실행 파일을 제공하지 않습니다.

pnpm add sonamu@^0.11.0 @sonamu-kit/cli@0.1.0
pnpm sonamu --version

기존 프로젝트에 sonamu가 이미 설치되어 있다면 ^0.11.0으로 업데이트하고 @sonamu-kit/cli@0.1.0을 추가하세요. 이 CLI 릴리스는 Sonamu ^0.11.0을 지원합니다. CLI는 Optique 1.2.4를 사용합니다. 설치된 버전의 정확한 명령 구조는 pnpm sonamu --help에서 확인할 수 있습니다.

대화형 사용

TTY 터미널에서는 자동화 옵션 없이 실행합니다.

# 명령 선택
pnpm sonamu

# Entity 선택
pnpm sonamu scaffold model

# Fixture import용 Entity 선택. ID는 생략할 수 없음
pnpm sonamu fixture import 1 2 3 --execute

TTY에서 최상위 명령을 생략하거나 잘못 입력하거나 퍼지하게 입력하면 명령 검색 메뉴가 열리며, 입력하는 즉시 목록이 필터링됩니다. 각 선택 단계에는 최대 10개 항목만 표시됩니다. 명령 그룹을 선택하면 바로 아래 하위 명령이 단계적으로 열리고, 그룹 자체도 실행할 수 있으면 Use current command 항목이 함께 표시됩니다. pnpm sonamu fixture처럼 불완전한 경로는 해당 그룹의 하위 명령 메뉴에서 바로 시작합니다. 명령 선택 중 어느 단계에서든 Ctrl+C를 누르면 종료 코드 130으로 끝납니다. Entity를 받는 명령은 목록에서 Entity를 선택하거나 입력한 Entity 이름을 퍼지 검색할 수 있습니다. fixture import도 TTY에서 Entity를 선택하거나 퍼지 검색하지만, 숫자 ID는 입력해야 합니다. TTY가 아니면 프롬프트를 열지 않으며, 빠진 인자와 잘못된 입력은 사용 오류로 처리합니다. Entity 검색은 Entity 메타데이터만 읽으며 Model이나 다른 애플리케이션 런타임 모듈을 불러오지 않습니다. --non-interactive를 지정하면 TTY에서도 검색과 확인 프롬프트를 사용하지 않습니다. 필수 입력이 빠져도 프롬프트로 전환하지 않습니다.

자동화와 코딩 에이전트

모든 필수 입력을 명시하고 두 자동화 옵션을 함께 전달하세요.

pnpm sonamu entity show User --non-interactive --json

dev와 start를 제외한 유한한 명령은 stdout에 JSON envelope 한 줄을 씁니다. build도 이에 포함됩니다. 성공 결과에는 ok, command, data, warnings가 들어가며, handler가 데이터를 반환하지 않으면 CLI가 data: null로 정규화합니다. 실패 결과에는 ok: false, command, error, exitCode가 들어갑니다. error에는 정제된 details가 포함될 수 있습니다. 실패한 테스트는 인증 정보를 노출하지 않고 details에 runId와 구조화된 테스트 결과를 보존합니다. task watch는 비동기 스트림을 반환하며 변경된 Workflow 실행 snapshot마다 newline-delimited JSON(NDJSON) 한 줄을 씁니다.

pnpm sonamu task watch RUN_ID --non-interactive --json

사람이 읽는 출력 문자열을 분석하지 마세요. JSON 또는 NDJSON과 프로세스 종료 코드를 함께 처리하세요. dev와 start는 장시간 실행되는 자식 프로세스에 작업을 위임하므로 사람이 읽는 출력만 지원합니다. --json을 지정하면 자식을 시작하기 전에 종료 코드 2와 JSON_UNSUPPORTED 실패 envelope 한 줄을 반환합니다. 사람용 모드에서는 자식 출력을 그대로 전달하며, signal로 종료되면 128 + signal 번호를 포함한 자식 종료 코드를 그대로 반환합니다. build는 일반 유한 명령처럼 JSON을 지원합니다. 메타데이터 출력은 JSON envelope를 사용하지 않습니다. --help와 --version은 Optique의 일반 텍스트 메타데이터를 출력합니다. completion은 JSON 자동화 옵션 없이 호출하면 일반 텍스트 자동 완성 스크립트를 출력합니다.

종료 코드	의미
`0`	성공, 메타데이터 출력 또는 preview 완료
`1`	도메인 또는 CLI 런타임 실패
`2`	명령, 인자, 옵션, 옵션 값 또는 필수 입력 오류
`3`	변경 작업에 필요한 실행 또는 확인 입력이 없음
`130`	대화형 작업 취소

위임된 dev와 start 프로세스는 이 표에 없는 종료 코드도 반환할 수 있습니다.

Fixture 자동화 입력

비대화형 fixture helper는 결정적 기본값을 사용합니다. 다음 selector가 없으면 프롬프트를 열지 않고 종료 코드 2를 반환합니다.

fixture gen에는 --all 또는 --include ENTITY_LIST가 필요합니다.
기존 방식의 fixture fetch에는 --all 또는 --include ENTITY_LIST가 필요합니다.
fixture explore에는 Entity 하나를 지정하는 --include ENTITY가 필요합니다. 쉼표로 구분한 목록을 전달하지 마세요. 이 명령에서 --all은 비대화형 selector로 인정하지 않습니다.
Fixture 전송 preview에는 위치 인자 ENTITY와 --source, --target, --field, 하나 이상의 --value, --relation include|exclude|none, --depth가 모두 필요합니다.

비대화형 fixture gen은 기본적으로 count 5, 저장 대상 db, LLM 미사용, cache 사용, dummy user 모드를 선택합니다. 명시한 옵션은 이 기본값을 대체합니다.

로깅 옵션

CLI는 Optique의 LogTape 통합을 사용합니다. 기본 warning 레벨에서 -v, -vv, -vvv를 추가하면 각각 info, debug, trace 로그를 선택합니다. 긴 옵션 --verbose도 반복할 수 있으며 한 번 추가할 때마다 로그 레벨을 한 단계 높입니다.

pnpm sonamu sync -vv
pnpm sonamu migrate status --log-output=- --log-format=plain
pnpm sonamu task watch --log-output=sonamu.log --log-format=jsonl

--log-format은 jsonl, logfmt, color, plain을 받습니다. --log-output을 생략하면 로그는 기본적으로 stderr로 전송됩니다. --log-output=-도 로그를 stderr로 보내며, 다른 값은 파일 경로로 처리합니다. --json 모드에서는 명령 봉투와 이벤트 객체만 stdout에 기록됩니다. 로깅 옵션을 지정하지 않으면 프로젝트의 Sonamu 로깅 설정을 변경하지 않습니다. 잘못된 로깅 값은 명령 초기화 전에 종료 코드 2로 거절합니다.

변경 작업

실행 전에 전용 preview 명령이나 해당 명령의 --dry-run을 사용하세요. 실행 옵션은 명령마다 다릅니다.

# Entity patch dry-run과 적용
pnpm sonamu entity apply --file entity.patch.json --dry-run --non-interactive --json
pnpm sonamu entity apply --file entity.patch.json --execute --confirm --non-interactive --json

# Scaffold 확인과 비대화형 일괄 생성
pnpm sonamu scaffold preview --entity User,Post --template model --non-interactive --json
pnpm sonamu scaffold batch --entity User,Post --template model --execute --confirm --non-interactive --json

# Migration 확인과 실행
pnpm sonamu migrate preview production --action apply --non-interactive --json
pnpm sonamu migrate apply production --execute --confirm --force-reason CHANGE_REQUEST --non-interactive --json

# 엄격한 Fixture import와 완전한 전송 preview
pnpm sonamu fixture import User 1 2 3 --execute --confirm --non-interactive --json
pnpm sonamu fixture fetch User --source production --target fixture --field id --value 1,2 --relation include --depth 1 --dry-run --non-interactive --json

# Task 변경 preview와 실행
pnpm sonamu task pause RUN_ID --dry-run --non-interactive --json
pnpm sonamu task pause RUN_ID --execute --confirm --non-interactive --json

# locale로 거른 i18n 목록, JSON export와 import
pnpm sonamu i18n list --locale en --non-interactive --json
pnpm sonamu i18n export --format json --file translations-en.json --locale en --non-interactive --json
pnpm sonamu i18n import --format json --file translations.json --execute --confirm --non-interactive --json

# CDD 규칙 dry-run과 실행
pnpm sonamu cdd rule add --rule-key api --id require-auth --when "엔드포인트를 추가할 때" --text "인증을 적용한다." --dry-run --non-interactive --json
pnpm sonamu cdd rule add --rule-key api --id require-auth --when "엔드포인트를 추가할 때" --text "인증을 적용한다." --execute --confirm --non-interactive --json
pnpm sonamu cdd ac --document requirements/signup.md --text "중복 이메일 가입을 거절한다." --dry-run --non-interactive --json
pnpm sonamu cdd ac --document requirements/signup.md --text "중복 이메일 가입을 거절한다." --execute --confirm --non-interactive --json

migrate apply와 migrate rollback의 비대화형 실행에는 --execute --confirm이 필요합니다. 운영 DB를 대상으로 실행할 때는 --force-reason REASON도 전달해야 합니다. fixture init, fixture import, fixture sync, fixture gen은 기본적으로 dry-run이며, --execute를 지정해야만 데이터를 변경합니다. TTY에서는 확인 프롬프트에 응답해야 합니다. 비대화형 호출에는 --execute --confirm이 필요하며, 실행 승인 없이 기본 또는 명시적 dry-run을 호출하면 종료 코드 3을 반환합니다. 엄격한 import 형식은 fixture import ENTITY ID... --execute입니다. Entity와 숫자 ID를 하나 이상 명시하세요. TTY에서는 Entity를 선택하거나 퍼지 검색할 수 있지만 ID는 입력해야 합니다. fixture fetch는 기본적으로 dry-run입니다. 실행하려면 --execute를 지정하고 TTY 확인 프롬프트에 응답하거나 --execute --confirm을 사용합니다. 전송 형식에는 ENTITY, --source, --target, --field, 하나 이상의 --value, --relation, --depth가 모두 필요하며, 기존 형식에는 --all 또는 --include가 필요합니다. scaffold batch, task pause, task resume, task cancel, cdd rule add, cdd ac는 기본적으로 dry-run입니다. TTY에서 파일이나 상태를 변경하려면 --execute를 지정하고 확인 프롬프트에 응답하거나 --confirm을 추가하세요. 비대화형 실행에는 --execute --confirm을 사용합니다. cdd rule add에는 --rule-key, --id, --when, --text가 모두 필요합니다. migrate run은 기본적으로 dry-run이지만 이 모드는 Migration 계획을 만들지 않습니다. migrate preview TARGET --action apply로 적용 계획을 확인한 다음, migrate run --execute를 실행하고 TTY 프롬프트에 응답하거나 --confirm을 추가하세요. NODE_ENV=production에서 migrate run --execute를 호출할 때는 --force-reason REASON도 전달해야 하며, 생략하면 종료 코드 3을 반환합니다. migrate shadow TARGET은 test와 fixture만 받습니다. dry-run은 입력만 검증하며 Shadow Migration을 실행하지 않습니다. 실제 Shadow 검증에는 --execute를 지정하고 TTY 프롬프트에 응답하거나 --execute --confirm을 사용하세요. scaffold batch는 --execute를 지정해야 파일을 생성합니다. 확인한 결과가 기존 파일을 대체해야 한다면 실행 명령에도 --overwrite를 추가합니다. i18n import는 --format workbook|json 형식의 --file FILE을 읽고, i18n export는 지정한 형식과 경로에 파일을 씁니다. i18n import와 항목 변경에는 --execute --confirm을 사용하며, export는 파일만 생성합니다. i18n list나 i18n export에 --locale LOCALE을 추가하면 해당 locale만 포함합니다. i18n update에 --source project|entity를 추가하면 갱신할 항목의 출처를 명시합니다. 생략하면 사전에 등록된 기존 출처를 그대로 사용하며, 사전에 없는 key라면 project로 폴백합니다. skills sync는 이전 프로젝트의 postinstall 스크립트를 위한 호환 명령입니다. 파일을 변경하지 않고 외부 설치 안내만 출력한 뒤 종료 코드 0으로 끝납니다. entity show ENTITY는 존재하지 않는 Entity id를 받으면 실패합니다. 이전처럼 ok: true와 data: null을 종료 코드 0으로 반환하지 않고, ENTITY_NOT_FOUND 오류 봉투와 종료 코드 1을 반환합니다. null 응답을 “찾지 못함”으로 처리하던 --json 자동화는 수정해야 합니다. CLI는 Entity 제안 명령을 제공하지 않습니다. AI를 이용한 Entity 대화 기능은 Sonamu Web에서만 사용할 수 있습니다.

명령 경로

그룹	명령
Entity	`entity list`, `entity show ENTITY`, `entity search QUERY`, `entity apply --file FILE`
Fixture	`fixture init`, `fixture import ENTITY ID...`, `fixture sync`, `fixture gen`, `fixture fetch [ENTITY]`, `fixture explore`
Migration	`migrate run`, `migrate apply TARGET...`, `migrate generate`, `migrate status`, `migrate connections`, `migrate code TARGET`, `migrate preview TARGET`, `migrate shadow TARGET`, `migrate rollback TARGET`
Scaffold	`stub entity NAME`, `stub practice NAME`, `scaffold model ENTITY`, `scaffold model_test ENTITY`, `scaffold view_list ENTITY`, `scaffold view_form ENTITY`, `scaffold status`, `scaffold preview`, `scaffold batch`, `cone gen ENTITY`
런타임	`build`, `dev`, `sync`, `start`
i18n	`i18n list`, `i18n check`, `i18n import`, `i18n export`, `i18n create`, `i18n update`, `i18n delete`
Task	`task definitions`, `task list`, `task show RUN_ID`, `task steps RUN_ID`, `task watch RUN_ID`, `task pause RUN_ID`, `task resume RUN_ID`, `task cancel RUN_ID`
Test	`test [FILES...] [-p PATTERN] [-t]`, `test -s`
CDD	`cdd tree`, `cdd read PATH`, `cdd rules`, `cdd rule show RULE_KEY`, `cdd rule add`, `cdd ac`
Auth	`auth generate`, `auth add-companions`
호환	`skills sync`

migrate apply는 development, staging, production, fixture, test 다섯 대상을 원하는 순서와 조합으로 받습니다. TTY에서는 대상을 생략하면 하나 이상을 고르는 다중 선택 프롬프트가 열립니다. TTY가 아니거나 --non-interactive를 지정한 호출에는 대상을 하나 이상 전달해야 합니다. migrate shadow TARGET은 로컬의 fixture와 test 대상만 받습니다. migrate code, migrate preview, migrate rollback은 다섯 대상 중 하나를 받습니다. auth generate --plugins PLUGINS에는 다음 plugin ID를 쉼표로 구분해 전달할 수 있습니다.

2fa, admin, anonymous, api-key, audit-log, jwt, organization, passkey,
phone-number, sso, username

필수 옵션과 허용된 값을 확인하려면 하위 명령의 도움말을 실행하세요.

pnpm sonamu migrate rollback --help
pnpm sonamu fixture fetch --help

셸 자동 완성

Optique 1.2.4는 Bash, zsh, fish, PowerShell, Nushell용 스크립트를 생성합니다.

pnpm sonamu completion bash
pnpm sonamu completion zsh
pnpm sonamu completion fish
pnpm sonamu completion pwsh
pnpm sonamu completion nu

생성한 표준 출력을 해당 셸의 자동 완성 설정에 저장하거나 source 하세요.

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

대화형 사용

자동화와 코딩 에이전트

Fixture 자동화 입력

로깅 옵션

변경 작업

명령 경로

셸 자동 완성

관련 문서

​대화형 사용

​자동화와 코딩 에이전트

​Fixture 자동화 입력

​로깅 옵션

​변경 작업

​명령 경로

​셸 자동 완성

​관련 문서

대화형 사용

자동화와 코딩 에이전트

Fixture 자동화 입력

로깅 옵션

변경 작업

명령 경로

셸 자동 완성

관련 문서