Cake20 Runtime CLI

Cake20 프로젝트를 로컬에서 생성·검사·개발하고 DB, 서버 소스와 Release를 관리합니다.

CLI 설치

@cake20/cli는 호환되는 @cake20/runtime을 정확한 버전으로 함께 설치합니다. 기본 명령은 cake이며 기존 cake20 명령도 호환용으로 제공합니다.

@cake20 범위만 Cake20 Package 서버에 연결하므로 공개 의존성은 각 패키지 관리자의 기본 Registry에서 내려받습니다. 전체 Registry를 --registry로 바꾸지 않습니다.

npm, pnpm과 Yarn 설치는 마지막에 Bun 1.3 이상을 확인합니다. Bun이 없거나 낮으면 운영체제에 맞는 설치 명령을 표시하며, Bun 설치 후 같은 CLI 설치 명령을 다시 실행하면 됩니다.

각 일반 명령의 첫 줄에는 Cake20 CLI 버전과 공식 홈페이지가 표시됩니다. cake --version은 CLI 숫자 버전만, cake -v는 CLI와 Runtime 버전을 함께 출력합니다.

npm config set @cake20:registry https://package.cake20.com
npm install -g @cake20/cli

현재 제공하는 명령

설치된 버전의 정확한 명령과 옵션은 cake --help에서 확인합니다. 현재 CLI는 아래 기능으로 구성됩니다.

프로젝트와 AI 문서: init, prepare, doctor, ai
개발과 실행: dev, design, preview, build, start, test
데이터베이스: db version, db export, db import
계정과 서버 소스: login, logout, whoami, sites, pull, sync, deploy
Archive와 유지관리: run, update, version

cake --help

프로젝트 생성

cake init은 안녕하세요 타이핑 화면이 포함된 기본 프로젝트를 만들고 Cake20 View, Cake20 UI와 Cake20 타입도 준비합니다. --standard는 표준 템플릿 tmp-e1fc3d0b0947의 짧은 옵션입니다.

--template에는 공개 tmp-* 템플릿 또는 내 web-* 웹사이트 ID를 지정합니다. 소스를 내려받아 생성 직후 개발할 수 있습니다.

대상에 파일이 있으면 yes/no 확인 메시지를 표시합니다. yes를 입력하면 숨김 파일을 포함한 기존 항목을 운영체제 휴지통으로 보냅니다.

빈 폴더는 확인 없이 바로 진행하며 --yes는 확인을 생략합니다.
루트, 홈, 현재 작업 폴더의 상위 폴더와 심볼릭 링크는 비우지 않습니다.
현재 폴더는 cake init .처럼 명시해 사용할 수 있습니다.
.DS_Store를 포함한 기존 항목도 휴지통으로 옮기며 즉시 영구 삭제하지 않습니다.

# 기본 프로젝트
cake init ./my-site

# 공개 템플릿 ID
cake init ./my-site --template tmp-e1fc3d0b0947

# 내 웹사이트 ID
cake init ./my-site --template web-fe61cd26e3b5

# 같은 표준 템플릿의 짧은 옵션
cake init ./my-site --standard

# 확인 없이 현재 폴더를 교체하고 표준 템플릿 설치
cake init . --standard --yes

VS Code와 Zed에서 개발

cake prepare는 Cake20 View 자동 import, Cake20 UI 컴포넌트와 Cake20 전역 타입을 생성합니다. cake init으로 만든 프로젝트는 자동으로 준비되며 기존 프로젝트에서 타입이 보이지 않을 때 다시 실행하면 됩니다.

package.json과 tsconfig.json은 VS Code와 Zed 탐색기에 그대로 표시합니다. Runtime이 생성하는 시스템 폴더만 별도로 관리합니다.

타입을 갱신한 뒤 편집기의 TypeScript 서버를 다시 시작합니다.
app, server, shared, public, package.json과 tsconfig.json을 프로젝트에서 확인할 수 있습니다.
package.json은 웹사이트 설정과 의존성을 직접 수정하는 단일 원본입니다.

cake prepare .

# VS Code
code .

# Zed
zed .

개발, 디자인, 빌드와 운영 실행

dev는 화면, API, files, SSE, WebSocket과 로컬 PostgreSQL을 함께 실행합니다.
dev와 build는 DB 스키마를 반영하고 신규·변경된 모델 seed를 동기화합니다.
design과 preview는 같은 화면 전용 모드이며 API와 DB가 필요 없는 작업에 사용합니다.
build는 운영 Release를 만들고 start는 현재 Release를 실행합니다.
dev, design, preview와 start의 기본 포트는 5201이며 --port로 변경합니다.
Runtime 버전 차이는 주의 로그로 남기고 가능한 경우 실행을 계속합니다.

# 전체 개발모드: 화면 HMR + API + DB + seed
cake dev . --open

# 화면 전용 디자인 모드
cake design . --open
cake preview . --open

# 운영 Release
cake doctor .
cake build .
cake start . --open

격리된 테스트 환경

cake test는 별도 모드 선택 없이 항상 격리된 테스트 환경에서 실행합니다.
현재 프로젝트에서는 테스트 파일만 지정하고, 다른 프로젝트에서는 프로젝트 경로를 먼저 지정합니다.
--suite는 같은 파일을 테스트 스위트로 실행합니다.
테스트는 build/current Release를 사용하므로 먼저 build를 실행합니다.

# 현재 프로젝트
cake test server/api/status.get.ts

# 다른 프로젝트
cake test ./my-site server/api/status.get.ts

PostgreSQL 확인, 내보내기와 가져오기

cake db version은 현재 PostgreSQL 버전과 local·server 데이터 모드를 표시합니다. .dump는 PGlite 데이터 디렉터리 전체를 보존하는 로컬 백업이고 .sql은 Cake20 PostgreSQL 사이의 이동에 사용합니다.

local DB는 data/postgres에 저장됩니다. import는 기본적으로 빈 DB에만 허용하며 --force는 기존 DB를 교체한다는 명시적인 승인입니다. DB 가져오기는 files와 프로젝트 소스를 함께 복원하지 않습니다.

cake db version
cake db export ./backup.dump
cake db export ./backup.sql
cake db import ./backup.dump
cake db import ./backup.sql

# 기존 로컬 DB를 명시적으로 교체
cake db import ./backup.sql --force

서버 소스 받기와 동기화

pull은 서버 프로젝트를 지정한 로컬 폴더에 다운로드합니다. 대상에 파일이 있으면 yes/no 확인 후 숨김 파일까지 휴지통으로 옮깁니다.

sync local은 서버 소스를 로컬에 반영하고 sync server는 로컬 소스를 서버에 반영해 Git 커밋을 만듭니다.

Core 웹 에디터와 CLI 동기화는 동시에 사용할 수 있습니다. 같은 파일을 수정하면 마지막으로 저장한 내용이 유지됩니다.

sync local은 내려받고 sync server는 서버에 반영하는 방향을 명확히 구분합니다.
테스트는 cake test 하나만 사용하며 항상 격리된 테스트 환경에서 실행합니다.

# 서버 프로젝트를 로컬 폴더에 받기
cake pull web-fe61cd26e3b5 ./my-site

cd ./my-site
cake sync local
cake sync server

로그인과 Cake20 배포

처음 원격 명령을 실행하면 브라우저 로그인이 자동으로 열립니다. CLI는 ID나 비밀번호를 직접 받지 않고 연결 토큰만 사용자 설정 폴더에 저장합니다.

처음 deploy할 때 package.json name이 등록된 web-* ID가 아니면 프로젝트 이름과 생성 여부를 확인한 뒤 Cake20 Core가 새 웹사이트 ID를 발급하고 그 값을 system-managed name으로 저장합니다.

등록되지 않은 web-* name을 임의의 원격 대상으로 신뢰하지 않고 새 ID를 발급합니다. 이후 deploy는 저장된 name의 웹사이트에 소스를 올리고 build/debug 검수 후 운영 Release를 배포합니다.

cake push web-*는 이전 호환 명령이며 웹사이트에는 cake deploy를 사용합니다. 관리자의 tmp-* 템플릿 push는 계속 즉시 반영합니다.

.git, .vscode, .zed, node_modules, build, data, files와 tmp는 전송하지 않습니다.
Runtime 생성 파일과 서버 관리 파일도 전송 대상에서 제외합니다.
로그아웃은 장비에 저장된 CLI 연결만 제거하고 Cake20 계정을 삭제하지 않습니다.

cake login

# 연결되지 않은 로컬 프로젝트를 처음 생성·배포
cake deploy ./my-site

# 이미 연결된 웹사이트를 다시 배포
cake deploy ./my-site --yes

# 관리자 템플릿 즉시 갱신은 push 호환 명령 사용
cake push tmp-e1fc3d0b0947 ./my-template

cake logout

Cake20 ZIP 바로 실행

run은 사용자가 압축을 풀지 않아도 ZIP을 검사하고 실행 폴더를 만든 뒤 doctor, build와 start를 수행합니다. Runtime 준비가 끝나면 기본 브라우저를 자동으로 엽니다.

hello.cake.zip의 기본 실행 폴더는 hello.cake입니다. ZIP이 바뀌면 압축이 관리한 소스만 갱신하고 data/postgres와 files는 보존합니다.

지원 형식은 .zip, .cake.zip과 .cake입니다.
ZIP 루트 또는 최상위 폴더 하나 안에 package.json이 있어야 합니다.
경로 이탈, 실행 데이터 폴더와 과도한 파일 수·압축 크기를 거부합니다.
--memory는 OS 임시 폴더를 사용하고 종료 시 소스, DB와 files를 제거합니다.
run은 local 데이터 모드로 실행하며 Cake20 운영 DB에 연결하지 않습니다.

cake run ./hello.cake.zip

# 사용자 작업 폴더를 남기지 않는 일회성 실행
cake run ./hello.cake.zip --memory

# 위치, 브라우저와 포트 지정
cake run ./hello.cake.zip --dir ./workspace --no-open --port 5300

CLI와 Runtime 버전 관리

update는 현재 CLI를 설치한 패키지 관리자를 자동으로 감지하고 최신 CLI와 호환되는 Runtime을 함께 설치합니다. 필요하면 bun, npm, pnpm 또는 yarn을 --manager로 지정합니다.

cake --version은 CLI 숫자 버전만 출력합니다. cake -v는 CLI와 Runtime 버전을 함께 표시하고 cake version은 Runtime 버전을 표시합니다.

# 설치 없이 새 버전 확인
cake update --check

# CLI와 호환 Runtime 업데이트
cake update

# 설치 관리자를 직접 지정
cake update --manager bun

# 버전 확인
cake --version
cake -v
cake version

AI와 자동화에서 사용

AI 개발 도구는 Cake20 폴더에서 prepare, doctor, dev와 build를 그대로 호출합니다.
CI는 doctor, 필요한 test와 build를 조합해 Runtime 호환성을 검사합니다.
cake version은 CLI가 사용하는 Runtime 버전을 확인합니다.
Cake20 Core는 시각적 Control Plane이고 CLI는 로컬·터미널·자동화 인터페이스입니다.