CLI 레퍼런스

EmDash CLI는 EmDash CMS 인스턴스 관리를 위한 명령을 제공합니다 — 데이터베이스 설정, 타입 생성, 콘텐츠 CRUD, 스키마 관리, 미디어 등.

설치

CLI는 emdash 패키지에 포함되어 있습니다. 다음 명령으로 설치합니다:

npm install emdash

npx emdash로 명령을 실행하거나 package.json에 스크립트를 추가합니다. 바이너리는 간결함을 위해 em으로도 사용 가능합니다.

인증

공유 원격 클라이언트를 사용하는 명령은 이 순서로 인증을 해결합니다:

1. --token 플래그 — 명령줄의 명시적 토큰
2. EMDASH_TOKEN 환경 변수
3. 저장된 자격 증명 ~/.config/emdash/auth.json에서 (emdash login으로 저장)
4. 개발 바이패스 — URL이 localhost이고 토큰이 없으면 개발 바이패스 엔드포인트를 통해 자동 인증

이 명령들은 --url (EMDASH_URL에서, 폴백은 http://localhost:4321) 및 --token 플래그를 받습니다. 인증 명령에는 자체 연결 옵션이 있습니다. 로컬 개발 서버를 대상으로 할 때는 토큰이 필요 없습니다.

공통 플래그

공유 원격 클라이언트를 사용하는 명령에서 사용 가능한 플래그:

출력

stdout이 TTY이면 CLI는 consola로 포맷된 결과를 출력합니다. 파이프되거나 --json이 설정되면 stdout에 원시 JSON을 출력합니다 — jq나 다른 도구에 적합합니다.

명령

emdash dev

자동 데이터베이스 설정으로 개발 서버를 시작합니다.

npx emdash dev [options]

옵션

예제

# 개발 서버 시작
npx emdash dev

# 커스텀 포트
npx emdash dev --port 3000

# 시작 전 원격에서 타입 생성
npx emdash dev --types

동작

1. 보류 중인 데이터베이스 마이그레이션 확인 및 실행
2. --types가 설정되면 원격 인스턴스에서 TypeScript 타입 생성 (URL은 EMDASH_URL 환경 변수 또는 package.json의 emdash.url에서)
3. EMDASH_DATABASE_URL을 설정하여 Astro 개발 서버 시작

emdash types

실행 중인 EmDash 인스턴스의 스키마에서 TypeScript 타입을 생성합니다.

npx emdash types [options]

옵션

예제

# 로컬 개발 서버에서 타입 생성
npx emdash types

# 원격 인스턴스에서 생성
npx emdash types --url https://my-site.pages.dev

# 커스텀 출력 경로
npx emdash types --output src/types/emdash.ts

동작

1. 인스턴스에서 스키마 가져오기
2. TypeScript 타입 정의 생성
3. 출력 파일에 타입 쓰기
4. 참조용으로 옆에 schema.json 쓰기

emdash login

OAuth Device Flow를 사용하여 EmDash 인스턴스에 로그인합니다.

npx emdash login [options]

옵션

동작

1. 인스턴스의 인증 엔드포인트 발견
2. localhost이고 인증이 설정되지 않으면 자동으로 개발 바이패스 사용
3. 그 외에는 OAuth Device Flow 시작 — 코드를 표시하고 브라우저 열기
4. 인가를 폴링한 후 ~/.config/emdash/auth.json에 자격 증명 저장

저장된 자격 증명은 같은 인스턴스를 대상으로 하는 모든 후속 명령에서 자동으로 사용됩니다.

emdash logout

로그아웃하고 저장된 자격 증명을 제거합니다.

npx emdash logout [options]

emdash whoami

현재 인증된 사용자를 표시합니다.

npx emdash whoami [options]

이메일, 이름, 역할, 인증 방법, 인스턴스 URL을 표시합니다.

emdash content

콘텐츠 항목을 관리합니다. 모든 하위 명령은 EmDashClient를 통해 원격 API를 사용합니다.

content list <collection>

npx emdash content list posts
npx emdash content list posts --status published --limit 10

content get <collection> <id>

npx emdash content get posts 01ABC123
npx emdash content get posts 01ABC123 --raw

응답에는 _rev 토큰이 포함됩니다. 덮어쓰기 전 현재 상태를 확인했음을 증명하기 위해 content update에 전달하세요.

content create <collection>

npx emdash content create posts --data '{"title": "Hello"}'
npx emdash content create posts --file post.json --slug hello-world
cat post.json | npx emdash content create posts --stdin

--data, --file, --stdin 중 정확히 하나로 데이터를 제공합니다. --draft가 설정되지 않으면 새 항목은 자동 게시됩니다.

content update <collection> <id>

현재 상태를 확인했음을 증명하기 위해 이전 get의 _rev 토큰을 제공해야 합니다:

# 1. 항목 읽기, _rev 기록
npx emdash content get posts 01ABC123

# 2. 1단계의 _rev로 업데이트
npx emdash content update posts 01ABC123 \
  --rev MToyMDI2LTAyLTE0... \
  --data '{"title": "업데이트됨"}'

get 이후 항목이 변경되었으면 서버가 409 Conflict를 반환합니다 — 다시 읽고 재시도하세요.

content delete <collection> <id>

npx emdash content delete posts 01ABC123

콘텐츠 항목의 소프트 삭제 (휴지통으로 이동).

content publish <collection> <id>

npx emdash content publish posts 01ABC123

content unpublish <collection> <id>

npx emdash content unpublish posts 01ABC123

content schedule <collection> <id>

npx emdash content schedule posts 01ABC123 --at 2026-03-01T09:00:00Z

content restore <collection> <id>

npx emdash content restore posts 01ABC123

삭제된 콘텐츠 항목을 복원합니다.

emdash schema

컬렉션과 필드를 관리합니다.

schema list

npx emdash schema list

모든 컬렉션을 나열합니다.

schema get <collection>

npx emdash schema get posts

모든 필드와 함께 컬렉션을 표시합니다.

schema create <collection>

npx emdash schema create articles --label Articles
npx emdash schema create articles --label Articles --label-singular Article --description "블로그 기사"

schema delete <collection>

npx emdash schema delete articles
npx emdash schema delete articles --force

schema add-field <collection> <field>

npx emdash schema add-field posts body --type portableText --label "본문 콘텐츠"
npx emdash schema add-field posts featured --type boolean --required

schema remove-field <collection> <field>

npx emdash schema remove-field posts featured

emdash media

미디어 항목을 관리합니다.

media list

npx emdash media list
npx emdash media list --mime image/png --limit 20

media upload <file>

npx emdash media upload ./photo.jpg
npx emdash media upload ./photo.jpg --alt "석양" --caption "브리스톨에서 촬영"

media get <id>

npx emdash media get 01MEDIA123

media delete <id>

npx emdash media delete 01MEDIA123

media repair-usage

하나의 컬렉션 또는 모든 콘텐츠 컬렉션의 콘텐츠 미디어 사용 인덱스를 복구합니다.

npx emdash media repair-usage --collection posts
npx emdash media repair-usage --all
npx emdash media repair-usage --all --json

emdash search

콘텐츠 전체 텍스트 검색.

npx emdash search "hello world"
npx emdash search "hello" --collection posts --limit 5

emdash taxonomy

택소노미와 용어를 관리합니다.

taxonomy list

npx emdash taxonomy list

taxonomy terms <name>

npx emdash taxonomy terms categories
npx emdash taxonomy terms tags --limit 50

taxonomy add-term <taxonomy>

npx emdash taxonomy add-term categories --name "Tech" --slug tech
npx emdash taxonomy add-term categories --name "Frontend" --parent 01PARENT123

emdash menu

내비게이션 메뉴를 관리합니다.

menu list

npx emdash menu list

menu get <name>

npx emdash menu get primary

모든 항목과 함께 메뉴를 반환합니다.

emdash export-seed

데이터베이스 스키마와 콘텐츠를 시드 파일로 내보냅니다.

npx emdash export-seed [options] > seed.json

옵션

출력 형식

내보낸 시드 파일에 포함되는 항목:

• 설정: 사이트 제목, 태그라인, 소셜 링크
• 컬렉션: 필드를 포함한 모든 컬렉션 정의
• 택소노미: 택소노미 정의와 용어
• 메뉴: 항목을 포함한 내비게이션 메뉴
• 위젯 영역: 위젯 영역과 위젯
• 콘텐츠 (요청 시): $media 참조와 $ref: 구문을 포함한 항목

emdash secrets generate

배포용 EMDASH_ENCRYPTION_KEY를 생성합니다. 이 키는 플러그인 시크릿의 저장 시 암호화에 사용됩니다.

npx emdash secrets generate

stdout에 새 키를 출력합니다. 시크릿 저장소로 파이프하거나 --write로 로컬 .env 파일에 직접 작성합니다:

npx emdash secrets generate --write .env

emdash secrets fingerprint <key>

키의 값을 노출하지 않고 8자 지문(kid)을 출력합니다:

npx emdash secrets fingerprint emdash_enc_v1_...

생성되는 파일

.emdash/types.ts

emdash types 명령은 각 컬렉션의 TypeScript 인터페이스를 생성합니다:

// EmDash CLI로 생성
// 수동으로 편집하지 마세요 - `emdash types`를 실행하여 재생성

import type { PortableTextBlock } from "emdash";

export interface Post {
	id: string;
	title: string;
	content: PortableTextBlock[];
	publishedAt: Date | null;
}

.emdash/schema.json

명령은 도구용 원시 스키마 내보내기도 작성합니다:

{
  "version": "a1b2c3d4",
  "collections": [
    {
      "slug": "posts",
      "label": "Posts",
      "fields": [...]
    }
  ]
}

환경 변수

패키지 스크립트

편의를 위해 CLI 명령을 package.json 스크립트로 추가:

{
	"scripts": {
		"dev": "emdash dev",
		"types": "emdash types",
		"export-seed": "emdash export-seed",
		"db:reset": "rm -f data.db"
	}
}

종료 코드